Part 1 of a 5-part series on building production-grade skills for Claude
Next: Part 2: Anatomy of a Skill
If you’ve ever caught yourself re-explaining the same workflow to Claude (your team’s code review process, your document formatting standards, your data pipeline methodology), skills solve that problem permanently by letting you teach Claude once so it applies that knowledge every time.
A skill is a folder containing instructions, packaged as Markdown with YAML frontmatter, that teaches Claude how to handle specific tasks or workflows. Think of it as encoding your domain expertise into a reusable, portable unit that Claude loads on demand.
When Skills Make Sense
Skills shine when you have repeatable workflows that require consistent execution:
- Generating frontend designs from specs with your team’s design system
- Conducting research following a specific methodology
- Creating documents that follow your organization’s style guide
- Orchestrating multi-step processes across multiple tools
- Enhancing MCP (Model Context Protocol) integrations with workflow intelligence
If you’re already using MCP servers to give Claude access to external tools, skills add a critical knowledge layer on top: MCP gives Claude access to the kitchen, and skills give it the recipes.
The Kitchen Analogy
This framing from Anthropic captures it well:
| Layer | What It Provides | Example |
|---|---|---|
| MCP (Connectivity) | Tool access, real-time data, API invocation | Connect to Linear, Notion, Sentry |
| Skills (Knowledge) | Workflows, best practices, domain expertise | Sprint planning methodology, PR review process |
Skills transform the MCP experience by ensuring that pre-built workflows activate automatically, best practices are embedded in every interaction, and new users accomplish tasks on their first try; otherwise, every conversation starts from scratch, results vary inconsistently, and support tickets pile up asking “how do I do X with your integration?”
Three Categories of Skills
Based on patterns Anthropic has observed, skills fall into three categories:
Category 1: Document and Asset Creation. This category focuses on creating consistent, high-quality outputs (documents, presentations, code, designs) using Claude’s built-in capabilities, requiring no external tools. Examples include the built-in docx, pptx, xlsx, and frontend-design skills.
Category 2: Workflow Automation. These skills handle multi-step processes with consistent methodology. The skill-creator skill itself is an example, walking you through use case definition, frontmatter generation, instruction writing, and validation.
Category 3: MCP Enhancement. This category provides workflow guidance layered on top of MCP tool access. Sentry’s sentry-code-review skill is a real-world example: it automatically analyzes and fixes bugs in GitHub pull requests using Sentry’s error monitoring data via their MCP server.
Core Design Principles
Three principles govern how skills work under the hood:
Progressive Disclosure. Skills use a three-level loading system to minimize token usage:
- YAML frontmatter is always loaded in Claude’s system prompt and contains just enough information for Claude to recognize when to use the skill.
- SKILL.md body is loaded when Claude determines the skill is relevant and contains the full instructions.
- Linked files are additional references that Claude discovers only as needed (documentation, templates, scripts).
Composability. Claude can load multiple skills simultaneously, so your skill should work alongside others rather than assuming it’s the only capability available.
Portability. Skills work identically across Claude.ai, Claude Code, and the API, meaning you can build once and run everywhere as long as the environment supports any dependencies your skill requires.
What’s Coming in This Series
- Part 2: Anatomy of a skill, covering folder structure, YAML frontmatter, and writing effective instructions
- Part 3: Building your first skill, from use case definition to working prototype
- Part 4: Patterns that work, including sequential workflows, multi-MCP coordination, and iterative refinement
- Part 5: Testing, debugging, and distributing your skills
By the end, you’ll be able to build a functional skill in a single sitting, typically 15 to 30 minutes using the skill-creator tool.