Big Idea

The argument in one line.

Anthropic's internal skill-building principles reveal that most Claude users underuse skills by treating them as single markdown files rather than structured folders of context that progressively disclose information to the model.

Who This Is For

Read if. Skip if.

READ IF YOU ARE…

You use Claude Code regularly and have built at least one skill, but your results feel inconsistent or Claude keeps ignoring parts of your instructions.
You are a non-developer or solo builder who wants reliable AI automation without deep technical knowledge.
You write skill instructions as numbered steps and wonder why Claude sometimes skips them or does something unexpected.
You want to share skills with a team and are not sure whether to use a repo or a plugin.

SKIP IF…

You are a senior AI engineer already building multi-agent pipelines at scale - the video targets non-technical users and stays surface-level.
You have already read the Anthropic article in full - this is a curated highlight reel, not a comprehensive deep dive.

TL;DR

The full version, fast.

Anthropic published a guide to how they build Claude Code skills internally, and the core revelation is that a skill is a folder - instructions, scripts, data, and supporting files - not just a markdown document. Their six key principles: scope each skill to one of nine categories (skills that span multiple categories confuse the agent), build a gotchas section documenting known failure modes, use the file system for progressive disclosure so Claude reads supporting files only when needed, avoid over-specifying steps (give Claude the goal and constraints, not a recipe), write descriptions as model trigger conditions not human summaries, and share via .claude/skills or plugins. Most of their best internal skills started as a few lines and a single gotcha.

Free for members

Chat with this breakdown — free.

Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.

Create a free account →

Chapters

Where the time goes.

00:00 – 01:00

01 · Why Anthropic's article matters

Brock frames the video: Anthropic's article is developer-leaning, so he translated the key points for non-technical Claude users.

01:00 – 02:01

02 · What a skill actually is

Core misconception corrected: a skill is a folder of instructions, scripts, assets, and data - not just a markdown file.

02:01 – 03:30

03 · The nine categories of skills

Anthropic's internal taxonomy of skill types. The rule: each skill should cleanly fit one category. Skills straddling multiple categories confuse the agent.

03:30 – 04:20

04 · Build a gotchas section

The highest-signal content in any skill. Documents known failure modes. Updated over time as Claude hits new edge cases.

04:20 – 05:26

05 · Email drafter example: good vs avoid files

Live Claude Code demo showing a real email-drafter skill with both a good-examples file and an avoid file listing phrases Claude should never write.

05:26 – 06:36

06 · Progressive disclosure and the file system

Think of the entire skill folder as context engineering. Tell Claude what files exist and it reads them at appropriate times.

06:36 – 07:41

07 · Stop railroading Claude

Counterintuitive principle: prescriptive numbered steps make skills worse. Give Claude the goal and constraints, not a recipe.

07:41 – 08:39

08 · Write descriptions for the model, not humans

Claude scans skill descriptions at session start to build an invocation index. The description field is a trigger condition, not a summary.

08:39 – 09:43

09 · Distributing skills

Two sharing methods: drop skill folders into .claude/skills in a repo, or package as a plugin for larger multi-skill bundles.

09:43 – 10:27

10 · Start small, iterate

Most of Anthropic's best internal skills started as a few lines and a single gotcha, then improved because people added failures over time.

Atomic Insights

Lines worth screenshotting.

Most Claude users treat a skill as a markdown file. It is actually a folder - the intelligence lives in the supporting files, not just the main instructions.
The gotchas section is the highest-signal content in any skill because it documents what goes wrong, not what should happen.
Over-specifying steps in a skill actively degrades results - Claude follows the recipe even when the situation calls for judgment.
The description field is a session-start prompt to the model, not a label for yourself - writing it as a trigger condition reduces token cost and speeds invocation.
Progressive disclosure means you can maintain 20 supporting files in a skill folder and Claude reads only the ones it needs at the right moment.
Anthropic's nine-category taxonomy exists to catch over-scoped skills early - if a skill spans multiple categories, it does too much.
Skills that start as a few lines and a single gotcha consistently outperform skills written comprehensively from scratch.
Sharing a skill is as simple as dropping a folder into .claude/skills - no build step, no registry, no configuration.
Writing what not to do in a skill (the avoid file) is as important as writing what to do - both shape model behavior.
When Claude Code starts a session it builds an index of every skill from descriptions alone - that index is what decides which skills get invoked.

Takeaway

The folder is the skill, not the file

WHAT TO LEARN

Anthropic's internal playbook rewrites the mental model: a skill is a folder of structured context, and the discipline is knowing what to put in it, where, and when Claude reads it.

02What a skill actually is

Skills are folders containing instructions, scripts, data, and assets - not just a markdown file.
The supporting files in the folder are where much of the intelligence lives; SKILL.md is the hub, not the whole skill.

03The nine categories of skills

Anthropic uses nine categories internally; skills that cleanly fit one category outperform skills that straddle several.
Non-developers mostly work in Business Automation, Data and Analysis, and Library/API References - knowing your category helps scope the skill correctly.

04Build a gotchas section

The gotchas section is the highest-signal content in any skill - it documents known failure modes, not aspirational instructions.
Update the gotchas section over time as Claude hits new edge cases; the skill gets better through accumulated failures, not upfront completeness.

06Progressive disclosure and the file system

Tell Claude what files exist in the skill folder and it will read them at appropriate times - this is context engineering via file structure.
Supporting documents are read on-demand, so you can have rich coverage without bloating the main instruction file.

07Stop railroading Claude

Over-prescribing steps makes skills worse - Claude follows the recipe mechanically even when the situation calls for judgment.
Give Claude the goal and the constraints, not a numbered sequence; the open-ended instruction outperforms a five-step checklist.

08Write descriptions for the model, not humans

Claude scans skill descriptions at session start to build an invocation index - the description is a model prompt, not a human label.
Rewriting descriptions as when to use this skill makes Claude invoke the right skill faster and with less token overhead.

Glossary

Terms worth knowing.

Gotchas section: A dedicated block inside a skill file that lists known failure modes - specific things Claude gets wrong when using this skill. Updated over time as new edge cases appear.
Progressive disclosure: A file-system design pattern where the main skill file lists supporting documents that Claude reads only when it encounters the specific situation they cover.
Railroading: Writing skill instructions as numbered step-by-step recipes so prescriptive that Claude follows them mechanically even when the situation calls for judgment, producing worse results than giving it a goal and constraints.
Skill description field: The metadata field attached to a Claude Code skill that is scanned at session start. Anthropic recommends writing it as a trigger condition (when to invoke) rather than a summary (what it does).
Plugin (Claude Code): A packaged collection of multiple skills that can be installed by team members, as opposed to individual skill folders shared via a repository.

Resources

Things they pointed at.

00:05linkAnthropic: Lessons from building Claude Code - How we use skills

08:39toolClaude Code .claude/skills folder (built-in skill sharing)

10:07productBrock's School community (AI for Non Techies)

10:20link15 Claude skills I can't live without (free resource)

Quotables

Lines you could clip.

01:47

“Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.”

Direct Anthropic definition that corrects the most common misconception→ IG reel cold open↗ Tweet quote

07:41

“The description field is not a summary. It's a description of when to trigger this skill.”

Tight one-two punch that immediately changes how viewers will write their next skill→ TikTok hook↗ Tweet quote

06:36

“Give Claude the information it needs, but give it the flexibility to adapt to the situation.”

Counter-intuitive instruction that challenges the instinct to over-specify→ newsletter pull-quote↗ Tweet quote

09:43

“Most of our best skills began as a few lines and a single gotcha, then got better because people kept adding to them as Claude hit new edge cases.”

Permission to start messy - validates the iterate approach→ IG reel cold open↗ Tweet quote

The Script

Word for word.

Read-along

Don't just watch it. Burn it in.

See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.

metaphoranalogy

Anthropic just dropped this article breaking down how they use Claude skills and all the key lessons they've learned while building Claude code. I went through the entire article, and this is a bit more tailored towards developers. So what I did is I broke down key points here that you can use in order to implement into Claude to build better skills.

So in this video, I'm gonna break down the key things that Anthropic has learned from building Claude code and how they're using skills. We're gonna talk about the nine different skills that Claude uses, and we're gonna go over all the common misconceptions and mistakes people make when it comes to using Claude skills. So by the end of this video, you'll walk away a better Claude user.

I can guarantee you that. And there's a lot of things that I personally learned from this article that I'm gonna be implementing myself. Alright.

So first of all, if you wanna read this yourself, there will be a link in the description to go through the exact same article I'm gonna talk about in this video. So without further ado, let's dive right into this. So first things first, here are the key lessons that Anthropic has learned from building Claude code and how they're personally using skills across the entire Anthropic team.

So what better way to learn about how to craft skills than from Anthropic themselves? So first of all, Anthropic says we've been building and using skills in Claude Code extensively at Anthropic with hundreds of them in active use. These are the lessons we've learned about using skills to accelerate our development.

And from Anthropic themselves, here's how they classify what a skill is. Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Now if you've used Claude before, is absolutely a no brainer.

You probably already know that, and you've probably begin building skills yourself. But what we wanna focus on is the fact that they said a common misconception we hear about skills is that they are just markdown files. They're actually a folder that can include scripts, assets, data, etcetera, that the agent can discover, explore, and manipulate.

So these aren't just markdown files. Anthropic is basically stating that most people don't realize these are actual folders that include extra context in order to make these skills more useful. Later on in this video, I'm gonna show you exactly what I mean.

So let's move on to the nine different types of skills Anthropic says that you can create. So Anthropic says after cataloging all of our internal skills at Anthropic, we noticed they cluster into nine different categories. And then this highlighted part is what we really wanna focus on.

So they said the best skills cleanly fit into one. The ones that try to do too much straddle several and confuse the agent.

And then they go on to mention this isn't a definitive list, but it's a useful framework for us to begin identifying which of these different categories do each of our skills play into. So this part gets a little bit technical, but stay with me.

So the first category is library and API references. So this is, you know, if you're using APIs, CLIs, SDKs, all these different things, kind of more developer speak.

Next up, we have product verification, then data and analysis. Next up, we have business automation.

You could think of these as, you know, our actual skills that are automating our workflows and specific tasks. We have scaffolding and templates, so framework correct boilerplates.

Then we have code quality and review, CD deployment, incident runbooks, infrastructure ops. So if you're not a developer, a lot of these don't necessarily pertain to you. Most of your skills might fall under the business automation, data and analysis, and maybe your library and API references.

I think the key thing to focus on here is not to fully understand each of these different types of skills, but I think what we need to take from this is that you wanna make sure your skills aren't doing too many different things. You wanna make sure it kinda falls under one of these categories and not multiple. Otherwise, it's not gonna work as efficiently as if you have one separate for each different types of skills.

Alright. So now moving into the actual structure of our skills. Next up, they are saying that we should be building a gotcha section.

They even go on to call this the highest signal content in any skill, and that is the gotcha section. Says these sections should be built up from common failure points that Claude runs into when using your skills. Ideally, you will update your skill over time to capture these gotchas.

So, basically, what Anthropic is saying is not only do we wanna instruct Claude how to do something in a skill, but we really wanna focus on what not to do, and that's a really good starting point to kind of reverse engineer how to craft it perfectly. Now in order to show you exactly what I mean, I'm inside of Claude code here, and what I'm gonna focus on is I'm gonna go over to one of the skills that I have.

So I'm gonna come down and click on email drafter skill, And what we're gonna see is inside of this skill, we obviously have our demo skill, we have email drafter, we have examples, and then we have our actual skill MD file. What we wanna focus on is the examples here. So it shows our good emails markdown.

This right here shows references which are actual good emails that we should be sending. Looks like we have a couple of different examples here that we could actually go ahead and look at. I personally had Claude go and read my email inbox to see exactly how I respond to my emails, and this is exactly, you know, the structure of that.

Now on top of the good emails example markdown file, we also now have this avoid markdown file, which if I open this up, this is what it looks like. It says what not to make an email sound like. Never sound like a corporate template, a LinkedIn thought leader, an AI assistant, all these things.

So it broke down, basically, the key things and the keywording it should never use. And this is something that we could add directly inside of the skill folder, but not inside of the skill markdown file.

Now this is a perfect segue into the next concept that they talked about in this article, and they suggested use the file system in progressive disclosure. And, basically, what that means is if we take a look at this graphic, we obviously have our main skill MD file, which is basically our hub for this workflow. This is kind of what that looks like.

It's the markdown instructions on how this, you know, workflow should run. But underneath that, we have a couple of other different markdown files.

We have a stuck jobs MD. We have a dead letters, retry storms, and consumer lag. Basically, what this means is if it ever gets stuck, it will read this markdown file, and, basically, it will help debug that specific problem that the skill is running into.

And if we come down to read the key point that Anthropic makes here, it says, you should think of this entire file system as a form of context engineering in progressive disclosure. Tell Claude what files are in your skill, and it will read them at appropriate times.

So this is a key thing that for me, sometimes I forget or I just don't fully utilize. I really just think of the main skill MD file. I don't really think of these separate ones that we could create to troubleshoot things or, you know, to be really specific if it's a really niche problem that I'm trying to solve within that, you know, given workflow.

Now next up is something that's pretty contrary to what a lot of people say, including me when it comes to creating our skills. So Anthropic is suggesting to avoid railroading Claude, and what they mean by this is giving it room to go and figure out how to do a task and not be too strict with how we get a workflow done.

Right here, it says Claude will generally try to stick to your instructions and because skills are reusable, you'll wanna be careful of being too specific in your instructions. Give Claude the information it needs, but give it the flexibility to adapt to the situation.

Now if I zoom in on this example that they give us, right here, it shows that this is actually too prescriptive. It shows each of these different steps exactly what to do, whereas it shows the better skill instruction, says cherry pick the commit onto a clean branch, resolve the conflicts preserving intent. If you can't land cleanly, explain why.

So it's really kind of giving it the room it needs to go and run this task, which think for a lot of people is pretty contrary to kinda what they would believe. You'd really think that you want it to be very, very structured. So that way you get the same output every time, but apparently, Claude is saying that that's something that they try to do is they try to avoid railroading Claude and instead let the model just do its thing and figure it out.

Next up, this one's pretty interesting and this makes a lot of sense. They're saying to write descriptions for the model, not for humans.

So when Claude code starts a session, it builds a listing of every available skill with its description, and that part is really important. And in order to show you exactly what I mean, um, if I pull up this skill here, you can see that I have, you know, description. And a lot of times, somebody might think, hey.

Maybe I write this description for me so I could understand, you know, and remember what this skill is for. But, really, that's not the case. Anthropic is saying that we need to use this description box in order to give our AI model context on when they should be running that skill.

A key thing here is this says, this means the description field is not a summary. It's a description of when to trigger this skill. So this is something that I think a lot of us could actually take and begin applying immediately.

It could be worth it to go into Claude and say, hey. But I want to actually update the description for all these different skills, and then we could go and begin editing those. And, hopefully, it makes them run quicker as well as save you on some token costs.

Alright. So next up, they talk about distributing skills. One of the biggest benefits of skills that you could share them with the rest of your team.

This is something we know if you've used Claude or in Claude CoWork before. You can use something called plug ins. They say there are two main ways right now that you could share these with others, and I get so many questions inside of my school community about what's the best way to go about sharing the particular skills that we make ourselves with our team members.

So there's a couple ways we could either check our skills into our repo under Claude dash skills. And in order to show you what I mean, if I come into Claude code, you can now see in my files, I have this dot skills section. So if I click on this, click on skills, we now have, you know, all these skills right here that we could always pull up at any given time, see our markdown files here, and begin making changes and edits there.

So we can take our skill file, share it with a team member, and all they have to do is dump it into this dot skills folder. And the other way to do this is to just simply make a plug in that you could share with your team. This is gonna be better if we have a culmination in a bunch of different skills that we wanna share as opposed to just, like, you know, one or two singular ones.

And lastly, the main takeaway from this is they say most of Anthropic skills that they've created began as a few lines and a single gotcha and then got better because people kept adding to them as Claude hit new edge cases. So, really, sometimes it is best just to start from scratch, really start from zero. Try to explain what it is you're trying to build.

Make sure to add some of the gotchas that we talked about earlier on in this video, which is basically just explaining what not to do a lot of the time, and then begin just making changes and iterating from there. Anyways, guys, I hope you got some value from this.

Subscribe to this channel for more Claude and AI content for nontechnical people. If you wanna dive deeper, make sure to join my school community. And if you want the 15 Claude skills that I can't live without, there's gonna be a link in the description for free.

Thanks for staying to the end, and I'll see you in the next

The Hook

The bait, then the rug-pull.

Anthropic published its internal playbook for building Claude Code skills - and the headline finding is not a feature announcement but a correction: almost every Claude user has the wrong mental model of what a skill even is.

Frameworks

Named ideas worth stealing.

02:01list

Anthropic's internal taxonomy for classifying skills. Each skill should fit cleanly into one category. Non-developers mostly work in Business Automation, Data and Analysis, and Library/API References.

Steal foraudit existing skills to find over-scoped ones that should be split

05:26concept

Progressive Disclosure File System

A skill folder is a form of context engineering. The main SKILL.md is the hub; supporting files are listed in the main file and read by Claude on-demand when needed.

Steal forany skill with more than one failure mode worth documenting

03:30concept

Gotchas Section

A dedicated section listing known failure points the agent hits when using the skill. Updated over time. Anthropic calls it the highest-signal content in any skill.

Steal forevery skill - start with even one gotcha and add more as failures occur

CTA Breakdown

How they asked for the click.

VERBAL ASK

10:07subscribe

“Subscribe to this channel for more Claude and AI content for nontechnical people. If you want the 15 Claude skills that I can't live without, there's gonna be a link in the description for free.”

Clean verbal CTA at the end, no mid-roll asks. Leads with a free resource link to maximize conversion.

Storyboard