Anthropic published a 33-page document titled "The Complete Guide to Building Skills for Claude". On first read, it looks like technical documentation. On second read, it's a statement: the way professionals work with Claude is shifting from "find a smarter prompt" to "version-control repeatable workflows as a code artifact".
Skills are not a new model. They are a folder. More precisely: a folder with one required file – SKILL.md – and a tiny YAML header that tells Claude when to activate that skill. That's it at the core. And that simplicity is the point.
What a skill is – stripped to the minimum
A skill is a directory with this structure:
your-skill-name/ ├── SKILL.md # Required: Markdown with YAML frontmatter ├── scripts/ # Optional: executable code ├── references/ # Optional: additional docs loaded as needed └── assets/ # Optional: templates, fonts, icons
The SKILL.md opens with a YAML block that has two required fields: name and description. The description is the most important field in the entire skill, because it determines whether Claude loads the skill at all.
--- name: contract-risk-review description: Reviews B2B contracts for typical liability, termination, and IP-assignment clauses. Use when the user says "contract review", "risk check", "AGB review", or uploads .pdf/.docx contracts. ---
The clever part is called Progressive Disclosure
The real innovation isn't the format – it's how Claude loads the contents. Anthropic calls it progressive disclosure: three levels, and only the one currently needed gets loaded.
Always in the system prompt. A few lines per skill. Just enough so Claude can decide whether the skill is relevant – without loading the rest.
Loaded only when Claude decides the skill matches the current task. Contains the actual instructions, examples, and error cases.
References, scripts, templates. Pulled in only when the skill genuinely needs them. A skill can carry hundreds of pages of documentation without a single token of it touching the default context.
Practical consequence: you can keep ten or twenty skills enabled without bloating your context. You pay tokens only for what Claude actually pulls in for the task at hand.
Skills are not MCP – and that's the most important distinction in the guide
Anthropic uses a kitchen analogy that lands well:
MCP
- • Provides the tools
- • Connects Claude to services (Linear, Notion, Stripe…)
- • Delivers real-time data and API access
- • Answers: what can Claude do?
Skill
- • Provides the recipe
- • Describes the workflow step by step
- • Embeds domain knowledge and best practices
- • Answers: how should Claude do it?
MCP without skills means the user has access to 30 tools and, on every second prompt, has no idea in what order to combine them. MCP with skills means the user describes the outcome, and the skill orchestrates the right MCP calls in the right sequence – the same way every time.
Three categories that cover almost everything
The guide groups productive skill use cases into three classes that hold up well in practice:
-
Document & asset creation. Skills that produce consistent output to fixed standards – presentations in a corporate design, code in a style guide, technical reports against a template. Example from the guide: the
frontend-designskill, which noticeably lifts Claude's design output. - Workflow automation. Multi-step processes with explicit validation gates. Sprint planning, customer onboarding, schema-based code review. When order matters and steps depend on each other, the workflow belongs in a skill.
-
MCP enhancement. Skills that sit on top of an existing MCP integration as a knowledge layer. Sentry did this publicly: a
sentry-code-reviewskill that calls the Sentry MCP server's tools in the right sequence to auto-fix bugs from production data inside pull requests.
The description field is the most important sentence in the entire skill
Anthropic dedicates several pages to the description field – for good reason. That one line decides whether Claude even considers the skill for a given user request. The rule is simple: what the skill does + when to trigger it.
Bad
description: Helps with projects.
Too generic. No triggers. Claude has no signal when to load.
Good
description: End-to-end onboarding flow for PayFlow customers including account creation and subscription setup. Use when the user says "onboard new customer", "create PayFlow account", or "set up subscription".
Specific. Outcome-focused. Real trigger phrases.
What actually matters in the skill body
The guide takes a refreshingly pragmatic line: be specific, be checkable, let code check whatever can be automated.
Instead of writing "validate inputs carefully" – a sentence every model interprets differently – prefer: "run python scripts/validate.py --input {filename}. On error check: missing required fields, date format YYYY-MM-DD". Scripts are deterministic. Language isn't. Where correctness matters, the script wins.
Anthropic recommends a simple structure for the body: workflow steps as a numbered list, examples for the most common scenarios, and a troubleshooting section for the two or three errors that genuinely keep recurring. Rarely more is needed.
Testing, without a test framework
The guide proposes three layers of testing – all doable without elaborate infrastructure:
- Triggering tests. Twenty realistic queries, check when the skill loads and when it doesn't. Include edge cases ("what's the weather in San Francisco") to make sure it doesn't fire everywhere.
- Functional tests. Run the workflow, check the output. Are the tickets created? Are properties correct? Do any API calls fail?
- Before/after comparison. Same task with and without the skill. How many clarifying turns? How many tokens? How many retries? This is where the value shows up.
Anthropic ships a skill-creator skill for exactly this loop – a meta-skill that walks you through definition, YAML, examples, and validation. If you have an MCP server and know your two or three top workflows, you can build a working skill in 15 to 30 minutes.
What skills change in practice
Without skills, a familiar pattern repeats: every team member re-explains the sprint-planning process to Claude each sprint. Fifteen messages back and forth. Inconsistent output across colleagues. Support tickets of the "how do I use your connector properly" kind.
With skills, the point at which knowledge is stored shifts. Instead of living in individual power users' heads, it lives in the repository – versioned, reviewable, activatable team-wide. Anthropic shipped organization-wide skill deployment in December 2025. Admins can roll out skills to a whole workspace. Updates land centrally. Onboarding a new team member no longer means "read up on our prompts" but "enable this skill bundle".
Where skills end – and CLAUDE.md continues
Skills aren't the right tool for everything. General behavioral rules – "ask when in doubt", "don't overwrite code you haven't understood", "match the repo's style" – still belong in a CLAUDE.md, because they apply to every task, not just specific workflows.
The clean split I currently use in projects: CLAUDE.md for discipline and style. Skills for concrete, recurring workflows. MCP for tool access. Three layers that don't overlap, but together produce what the guide calls "encoded workflows".
The bigger picture
The guide is more than documentation. It's a marker for a shift that's been visible for a few months now. The "clever prompting" era is winding down. The "encoded workflows" era is starting. Anyone who uses Claude daily but hasn't built a single skill yet is, by comparison, still working manually – every conversation starts from zero, every result depends on the day's prompt mood.
Skills solve this with an almost embarrassingly simple idea: a folder with a Markdown file. But that triviality is precisely why the concept will stick. It needs no new stack, no framework, no special SDK. A text editor and one hour are enough for the first productive skill. From the second skill onward, the change becomes obvious.
Sources:
Wondering where skills would give your team the biggest lever – onboarding, code reviews, a multi-step compliance workflow? Let's talk. I help build skill libraries that work in real projects, not just in demos.