Anthropic's 33-Page Blueprint for Claude Skills

An official guide that shows how to teach Claude the way you work – without writing a single line of code. What's actually in it, and why skills quietly retire the term "prompt engineering".

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.

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. Anthropic's docs give the order of magnitude: roughly 100 tokens per skill for level 1, under 5,000 tokens for the body, and level 3 costs nothing until a file is actually read.

Skills are not MCP – and that's the most important distinction in the guide

Anthropic uses a kitchen analogy that lands well:

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.

A real skill from the inside: the pdf skill

The best way to see how the three levels work together is a skill that runs in production: the pdf skill from Anthropic's skills repository. According to Anthropic, it powers Claude's document capabilities – and anyone can look inside:

pdf/
├── SKILL.md          # Overview: text, tables, merge, split, OCR …
├── forms.md          # Form workflow, read only for forms
├── reference.md      # Deep dive: more libraries, detailed examples
└── scripts/          # 8 Python scripts, including:
    ├── check_fillable_fields.py
    ├── extract_form_field_info.py
    ├── fill_fillable_fields.py
    └── fill_pdf_form_with_annotations.py

The form workflow is the interesting part. For forms, SKILL.md simply points to forms.md – level 3 in its purest form. There, a script first checks whether the PDF has fillable fields. If it does, the field metadata is extracted as JSON and filled in programmatically. If it doesn't, the skill determines the field coordinates, runs a script to check the bounding boxes for overlaps, only then places the text annotations, and renders the result as an image for visual verification. The scripts run via Bash: their code never enters the context, only their output.

The same thing as an MCP server? I'd need my own server, would have to define tool schemas, implement error handling, and run the whole thing for every user. The skill is a folder with Markdown and a few Python scripts. My rule of thumb: if the capability runs locally – reading, converting, generating files – a skill with scripts is enough. MCP only comes into play when Claude needs to reach an external system.

Three categories that cover almost everything

The guide groups productive skill use cases into three classes that hold up well in practice:

1. 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-design skill, which noticeably lifts Claude's design output.
2. 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.
3. MCP enhancement. Skills that sit on top of an existing MCP integration as a knowledge layer. Sentry did this publicly: a sentry-code-review skill 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.

description: Helps with projects.

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".

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:

1. 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.
2. Functional tests. Run the workflow, check the output. Are the tickets created? Are properties correct? Do any API calls fail?
3. 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.

How a skill gets into Claude Code

In Claude Code, there's no upload involved. Skills are folders on the file system, and according to the docs, the location determines the scope:

• ~/.claude/skills/<name>/SKILL.md – personal, available in all your projects.
• .claude/skills/<name>/SKILL.md in the repository – applies to that project and is versioned and reviewed along with the code.
• Plugins – ready-made skill bundles. You add Anthropic's collection with /plugin marketplace add anthropics/skills; the pdf skill lives in the document-skills plugin.

Claude Code picks up changes to these folders without a restart. Claude loads a skill automatically when its description matches, but you can also invoke it directly as /name – the former custom slash commands have been merged into skills. And because Agent Skills is now an open standard that Codex, Cursor, Gemini CLI and GitHub Copilot support as well, your skill folder isn't locked to Claude.

A note from the security corner: a skill ships instructions and executable code. Anthropic advises using skills only from trusted sources and fully auditing third-party ones first. So treat community skills like any other dependency: read first, then install. Good community libraries do exist, such as Jesse Vincent's Superpowers, which I analyzed in a separate article.

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. Since December 2025, owners of Team and Enterprise organizations can provision skills organization-wide: on by default for everyone, switchable off per user, and approved updates reach everyone automatically. 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.