Jonathon's AI Wiki

The Complete Guide to Building Skills for Claude

5 min read

Source: raw/The-Complete-Guide-to-Building-Skill-for-Claude.pdf Type: Documentation Author: Anthropic Published: 2026 (exact date not specified)

Anthropic’s official 30-page guide to building skills — reusable instruction packages that teach Claude how to handle specific tasks and workflows. Covers everything from fundamentals through distribution. Aimed at developers, power users, and teams wanting consistent, repeatable Claude behavior.

What is a skill?

A skill is a folder containing:

  • SKILL.md (required) — instructions in Markdown with YAML frontmatter
  • scripts/ (optional) — executable code (Python, Bash, etc.)
  • references/ (optional) — documentation loaded as needed
  • assets/ (optional) — templates, fonts, icons used in output

Skills use progressive disclosure — a three-level system that minimizes token usage:

  • First level (YAML frontmatter): Always loaded into Claude’s system prompt. Tells Claude when the skill should activate.
  • Second level (SKILL.md body): Loaded when Claude decides the skill is relevant. Contains the full instructions.
  • Third level (linked files): Additional files in the skill directory that Claude navigates and discovers as needed.

MCP vs. Skills — the kitchen analogy

  • MCP provides the professional kitchen: tools, ingredients, equipment (connectivity to Notion, Asana, Linear, etc.)
  • Skills provide the recipes: step-by-step instructions for how to create something valuable (knowledge)

Without skills, users connect MCP but don’t know what to do next. With skills, pre-built workflows activate automatically, best practices are embedded in every interaction.

Three skill categories

  1. Document & Asset Creation — generating consistent, high-quality output (documents, presentations, apps, designs, code). Key techniques: embedded style guides, template structures, quality checklists.
  2. Workflow Automation — multi-step processes that benefit from consistent methodology. Key techniques: step-by-step validation gates, templates, built-in review suggestions, iterative refinement loops.
  3. MCP Enhancement — workflow guidance to enhance tool access an MCP server provides. Key techniques: coordinates multiple MCP calls in sequence, embeds domain expertise, provides context users would otherwise need to specify, error handling for common MCP issues.

Technical requirements

Critical rules:

  • File must be exactly SKILL.md (case-sensitive)
  • Folder name: kebab-case only (no spaces, underscores, or capitals)
  • No README.md inside the skill folder — all documentation goes in SKILL.md or references/
  • No XML angle brackets (< >) in frontmatter — security restriction
  • Skills cannot use “claude” or “anthropic” in the name

YAML frontmatter fields:

  • name (required) — kebab-case, should match folder name
  • description (required) — must include WHAT it does + WHEN to use it. Under 1024 characters. Include specific trigger phrases users might say.
  • license (optional) — MIT, Apache-2.0, etc.
  • compatibility (optional) — environment requirements (1-500 chars)
  • metadata (optional) — author, version, mcp-server

Description formula: [What it does] + [When to use it] + [Key capabilities]

Writing effective instructions

  • Be specific and actionable — include exact commands, expected outputs, common issues
  • Reference bundled resources clearly — tell Claude where to look and what’s in each file
  • Use progressive disclosure — keep SKILL.md focused on core instructions, move detailed docs to references/
  • Include error handling with specific solutions
  • Include examples for common scenarios
  • Include troubleshooting sections

Testing approach

Three testing areas:

  1. Triggering tests — does the skill load at the right times? Test obvious tasks, paraphrased requests, and verify it doesn’t trigger on unrelated topics.
  2. Functional tests — does it produce correct output? Valid outputs, API calls succeed, error handling works, edge cases covered.
  3. Performance comparison — does the skill improve results vs. baseline? Compare tool calls, token consumption, user corrections needed.

The skill-creator skill (built into Claude.ai and Claude Code) can generate skills from descriptions, review existing skills, and suggest improvements.

Distribution

Individual users: Download skill folder, zip it, upload to Claude.ai (Settings > Capabilities > Skills) or place in Claude Code skills directory.

Organization-level: Admins deploy workspace-wide skills with automatic updates and centralized management (shipped December 2025).

Via API: /v1/skills/ endpoint, container.skills parameter in Messages API, works with Claude Agent SDK. Plugins bundle skills with MCP servers for easier distribution.

Agent Skills is an open standard — skills should be portable across tools and platforms, not just Claude. See Skills Ecosystem for how this fits into the broader extensibility landscape, and Skills vs MCP vs Plugins for when to use each layer.

Key Takeaways

  • Skills are reusable instruction packages — folder with SKILL.md + optional scripts/references/assets
  • Progressive disclosure (frontmatter → body → linked files) keeps token usage efficient
  • The description field is the most important part — it determines when Claude loads the skill
  • Three categories: document creation, workflow automation, MCP enhancement
  • Test for triggering accuracy, functional correctness, and performance vs. baseline
  • The skill-creator skill can generate and review skills in 15-30 minutes
  • Keep SKILL.md under 5,000 words; move detailed docs to references/
  • Skills are an open standard (Agent Skills) — portable across platforms

Try It

  1. Think of a workflow you repeat often in Claude (e.g., writing a specific type of document, running a multi-step process)
  2. In Claude Code, say: “Use the skill-creator skill to help me build a skill for [your use case]”
  3. The skill-creator will walk you through use case definition, frontmatter generation, instruction writing, and validation
  4. Test by running the task with and without the skill — compare results
  5. Iterate based on under/over-triggering signals

Open Questions

  • How does skill performance degrade as the number of enabled skills increases past 20-50?
  • What’s the best way to version skills across a team without the org-level distribution?
  • How do skills interact with CLAUDE.md project instructions — which takes precedence when they conflict?

Graph View

Backlinks