# The Complete Guide to Building Skills for Claude Official Anthropic PDF guide. Retrieved 2026-03-19. ## Core Design Principles ### Progressive Disclosure Skills use a three-level system: - First level (YAML frontmatter): Always loaded in Claude's system prompt. Just enough for Claude to know when each skill should be used. - Second level (SKILL.md body): Loaded when Claude thinks the skill is relevant. Contains full instructions and guidance. - Third level (Linked files): Additional files bundled within the skill directory, discovered only as needed. ### Composability Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available. ### Portability Skills work identically across Claude.ai, Claude Code, and API. ## Planning and Design ### Start with Use Cases Before writing any code, identify 2-3 concrete use cases your skill should enable. Three common categories: 1. Document & Asset Creation — Creating consistent, high-quality output 2. Workflow Automation — Multi-step processes that benefit from consistent methodology 3. MCP Enhancement — Workflow guidance to enhance MCP server tool access ### Define Success Criteria Quantitative metrics: - Skill triggers on 90% of relevant queries - Completes workflow in X tool calls - 0 failed API calls per workflow Qualitative metrics: - Users don't need to prompt Claude about next steps - Workflows complete without user correction - Consistent results across sessions ## Technical Requirements ### File Structure ``` your-skill-name/ ├── SKILL.md # Required ├── scripts/ # Optional - executable code ├── references/ # Optional - documentation └── assets/ # Optional - templates, fonts, icons ``` ### YAML Frontmatter Required fields: - `name`: kebab-case only, no spaces or capitals, should match folder name - `description`: MUST include BOTH what the skill does AND when to use it. Under 1024 characters. No XML tags. Optional fields: - `license`: e.g. MIT, Apache-2.0 - `compatibility`: 1-500 characters, environment requirements - `metadata`: custom key-value pairs (author, version, mcp-server) ### Security Restrictions Forbidden in frontmatter: - XML angle brackets (< >) - Skills with "claude" or "anthropic" in name (reserved) ### The Description Field Structure: [What it does] + [When to use it] + [Key capabilities] Include specific tasks users might say. Mention file types if relevant. ## Writing Effective Skills ### Best Practices for Instructions - Be specific and actionable - Reference bundled resources clearly - Use progressive disclosure (keep SKILL.md focused, move details to references/) - Include error handling ## Testing and Iteration Three levels of rigor: 1. Manual testing in Claude.ai 2. Scripted testing in Claude Code 3. Programmatic testing via skills API Pro Tip: Iterate on a single task before expanding. Most effective skill creators iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. ### Recommended Testing 1. Triggering tests — Triggers on obvious tasks, paraphrased requests, doesn't trigger on unrelated topics 2. Functional tests — Valid outputs, API calls succeed, error handling works, edge cases covered 3. Performance comparison — Prove the skill improves results vs. baseline ### Iteration Based on Feedback Undertriggering: Add more detail and nuance to description, keywords for technical terms Overtriggering: Add negative triggers, be more specific Execution issues: Improve instructions, add error handling ## Patterns 1. Sequential workflow orchestration — Multi-step processes in specific order 2. Multi-MCP coordination — Workflows spanning multiple services 3. Iterative refinement — Output quality improves with iteration (validation loop) 4. Context-aware tool selection — Same outcome, different tools depending on context 5. Domain-specific intelligence — Specialized knowledge beyond tool access ## Troubleshooting - Skill won't upload: File not named exactly SKILL.md (case-sensitive) - Invalid frontmatter: Missing --- delimiters, unclosed quotes - Skill doesn't trigger: Description too generic, missing trigger phrases - Skill triggers too often: Add negative triggers, be more specific, clarify scope - Instructions not followed: Too verbose, critical instructions buried, ambiguous language - Large context issues: Move detailed docs to references/, keep SKILL.md under 5,000 words ## Quick Checklist Before you start: - Identified 2-3 concrete use cases - Tools identified (built-in or MCP) - Reviewed guide and example skills - Planned folder structure During development: - Folder named in kebab-case - SKILL.md file exists (exact spelling) - YAML frontmatter has --- delimiters - name field: kebab-case, no spaces, no capitals - description includes WHAT and WHEN - No XML tags anywhere - Instructions clear and actionable - Error handling included - Examples provided - References clearly linked Before upload: - Tested triggering on obvious tasks - Tested triggering on paraphrased requests - Verified doesn't trigger on unrelated topics - Functional tests pass