Overview: Building Skills for Claude

Download The Complete Guide to Building Skills for Claude (PDF).

What a Skill Is

• A folder containing a required SKILL.md file plus optional scripts/, references/, and assets/ directories
• Teaches Claude a workflow once so it applies it consistently, without re-explaining every session

Core Design Principles

• Progressive disclosure: three levels — YAML frontmatter (always loaded), SKILL.md body (loaded when relevant), linked files (loaded on demand)
• Composable: works alongside other skills
• Portable: identical behavior across Claude.ai, Claude Code, and API

YAML Frontmatter Rules

• Folder and name field must be kebab-case (e.g. my-cool-skill)
• File must be named exactly SKILL.md (case-sensitive)
• description must include both what it does and when to trigger (under 1024 chars)
• No XML angle brackets < > anywhere; no README.md inside the skill folder

Writing Good Descriptions

• Include specific trigger phrases users would actually say
• Too vague = won’t trigger; too broad = triggers too often
• Negative triggers help narrow scope (e.g. “Do NOT use for simple data exploration”)

Five Common Patterns

• Sequential workflow orchestration (ordered multi-step processes)
• Multi-MCP coordination (workflows spanning multiple services)
• Iterative refinement (quality improves through loops and validation)
• Context-aware tool selection (same outcome, different tools based on conditions)
• Domain-specific intelligence (embedded compliance, expertise, or rules)

Testing Approach

• Triggering tests: verify skill loads on relevant queries and ignores unrelated ones
• Functional tests: verify correct outputs, API calls, and edge case handling
• Performance comparison: measure token usage and tool calls with vs. without the skill

Common Troubleshooting

• Skill won’t upload → check YAML delimiter formatting and exact SKILL.md naming
• Doesn’t trigger → description too vague, missing trigger phrases
• Triggers too often → add negative triggers, be more specific
• Instructions ignored → keep them concise, put critical rules at the top, use deterministic scripts for key validations
• Slow/degraded responses → keep SKILL.md under 5,000 words, move detailed docs to references/

Distribution

• Host on GitHub with a clear README (separate from the skill folder itself)
• Upload via Claude.ai Settings → Capabilities → Skills, or place in Claude Code skills directory
• Organisation admins can deploy skills workspace-wide
• API access via /v1/skills endpoint and container.skills parameter