I Read Anthropic's Internal Guide on Building Claude Skills. Here's Everything You Need to Know.

This article summarizes Anthropic’s internal guide on building skills for Claude, covering essential aspects from skill structure to testing and distribution.

What is a Skill?

A skill is essentially a folder containing a SKILL.md file (required) and optional subfolders for scripts, references, and assets. This folder is zipped and uploaded to Claude, enabling it to perform specific workflows.

Three-Level Loading System

Skills load in three levels:

1. YAML Frontmatter: Always present, used to determine skill relevance.
2. SKILL.md Body: Loaded when the skill is deemed applicable, containing the main instructions.
3. Linked Files (references/): Loaded only when needed, providing deep documentation and edge-case guides.

The frontmatter description is crucial for triggering the skill.

Writing the SKILL.md File

The SKILL.md file consists of:

• YAML Frontmatter: Includes name (kebab-case) and description (what the skill does and when to use it). Optional fields like license, author, version, and mcp-server can be added.
• Instructions Body: Written in Markdown, providing step-by-step instructions, examples, and troubleshooting tips.

Example:

---
name: your-skill-name
description: What it does and when to use it.
---

# Skill Name

## Step 1: First thing
Clear explanation. What to do, what success looks like.

## Step 2: Next thing
...
## Examples
User says: "Set up a new project"
Actions:
1.  Fetch existing projects via MCP
2.  Create new project with provided parameters
Result: Project created with confirmation link
## Troubleshooting
Error: Connection refused
Cause: MCP server isn't running
Solution: Settings > Extensions > [Service] > Reconnect

Skill Categories

Anthropic identifies three main use cases:

1. Document and Asset Creation: Generating consistent outputs (documents, code, designs).
2. Workflow Automation: Multi-step processes with consistent methodology.
3. MCP Enhancement: Workflow guidance layered on top of an existing MCP server connection.

Skills + MCP

Skills provide the “recipes” for using MCP (which provides the “kitchen”). Skills enable consistent workflows and embed domain expertise.

Five patterns for MCP-enhanced skills:

1. Sequential workflow orchestration
2. Multi-MCP coordination
3. Iterative refinement
4. Context-aware tool selection
5. Domain-specific intelligence

Testing Your Skill

Testing involves:

• Triggering Tests: Ensuring the skill loads when it should.
• Functional Tests: Verifying correct output.
• Performance Comparison: Comparing performance with and without the skill.

Debugging tip: Ask Claude when it would use the skill to identify gaps in the description.

Common Failures and Fixes

• Skill won’t upload: Naming issues (e.g., incorrect case for SKILL.md).
• Skill doesn’t trigger: Vague description or missing trigger phrases.
• Skill triggers too much: Lack of negative triggers or specific scope.
• MCP calls fail: MCP connection issues.
• Claude ignores instructions: Instructions are too long, critical steps are buried, or language is ambiguous.
• Context feels slow: Keep SKILL.md under 5,000 words and limit the number of enabled skills.

Distributing Your Skill

Distribution involves hosting the skill on GitHub with a clear README and adding it to MCP documentation. Organization admins can deploy skills workspace-wide.

Checklist

• Identify concrete use cases and needed tools.
• Use kebab-case folder name and exact SKILL.md spelling.
• Include both “what” and “when” in the description.
• Provide clear, specific instructions with error handling and examples.
• Test triggering and workflow.
• Monitor for under/over-triggering and iterate based on feedback.

Key Takeaway

The description field is critical for determining when Claude loads the skill. Get it right first.