Jonathon's AI Wiki

The Complete Guide to Building Skills for Claude

8 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.

The official evals workflow (skill-creator, March 2026 overhaul)

skill-creator (in anthropics/skills, also a Claude Code plugin) shipped a full evaluation workflow that operationalizes the three testing areas above:

  1. Authors write test prompts to evals/evals.json.
  2. skill-creator spawns paired with-skill / baseline subagents in the same turn — the direct mechanism for the “performance comparison” testing area.
  3. Results are graded into grading.json (assertion-based).
  4. Grades aggregate into benchmark.json / .md — pass rate, tokens, duration, mean ± stddev per scenario.
  5. Review via a generated HTML eval-viewer, or --static output for headless/Cowork environments where a browser isn’t available.

A separate loop optimizes the description field itself — the single highest-leverage field for triggering accuracy — against 20 should-trigger / should-not-trigger test queries, run via claude -p under the hood.

Anthropic’s official “Skill authoring best practices” doc formalizes this as “build evaluations first”: write 3+ test scenarios and get a baseline before writing the SKILL.md instructions, and test across Haiku/Sonnet/Opus rather than a single model tier. One explicit limitation from Anthropic’s own docs: “there is not currently a built-in way to run these evaluations” outside the skill-creator flow itself — there’s no first-party standalone eval runner you can point at an arbitrary skill.

CI integration (community tooling fills the gap)

Nothing first-party wires skill behavioral regression testing into CI beyond skill-creator’s own subagent-based evals. The gap is filled by a cluster of independent, convergent community linters — all static-analysis (deterministic, no LLM call needed), all wired into GitHub Actions on pull_request triggers scoped to .claude/skills/**:

  • skill-validator (Go) — pre-commit hooks + GitHub Actions PR annotations, with an optional LLM-judge scoring mode for deeper checks.
  • agent-skill-linter (~20 rules, installed via npx skills add) — structural SKILL.md rules (frontmatter shape, description quality signals, file-size limits).
  • skillscore (Dart) — scores a skill 0–100 across 7 categories, emits SARIF output so findings show up as native PR annotations. A published case study ran it against a 52k-star public agent-skills repo.
  • pulser eval — zero-dependency frontmatter/reference-integrity linter, lightest-weight of the four.

All four converge on the same shape: gate merges on a skill-path change with --strict / --min-score flags, similar in spirit to this vault’s own bin/lint-frontmatter-integrity. For running Claude Code itself unattended in CI (as opposed to linting a skill’s structure), the general mechanism is headless mode (-p/--print, with --bare for reproducible output) plus anthropics/claude-code-action@v1 — but as of this research, nothing publicly documented wires headless mode specifically into skill behavioral regression testing beyond what skill-creator’s own evals already do.

Practical takeaway: structural correctness (frontmatter valid, description well-formed, files present) is CI-solved territory — pick one of the four linters above and gate on skill-path PRs. Behavioral correctness (does the skill actually produce better output than baseline) is still a manual or skill-creator-mediated process, not something you can drop into a GitHub Action unattended today.

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
  • CI testing splits in two: structural linting (SKILL.md frontmatter/description/file-shape) is CI-solved via community tools (skill-validator, agent-skill-linter, skillscore, pulser eval, all GitHub-Actions-ready); behavioral regression testing (does the skill actually beat baseline) is still manual or mediated by skill-creator’s own with-skill/baseline subagent evals — Anthropic’s own docs admit there’s no built-in standalone eval runner yet.
  • 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