claude-skill-builder

Claude Skill Builder

Build Claude Code skills following Anthropic's official methodology — from planning through distribution.

PRIMARY SOURCE: "The Complete Guide to Building Skills for Claude" (Anthropic, January 2026)

• PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Local copy: ./claude-skill-builder-guide.pdf

---

Quick Start

To create a skill from scratch, follow the 4-phase process below. To improve an existing skill, read references/refining-skills.md. To validate a skill's structure, run scripts/audit-skill.sh.

Invoke with: /claude-skill-builder or ask about creating, improving, or auditing a skill.

---

How It Works

Four-phase methodology from the Anthropic guide:

Phase	Activity	Time
1: Planning & Design	Define use cases, category, success criteria	15-30 min
2: Implementation	Create folder, write SKILL.md, add resources	30-60 min
3: Testing	Triggering, functional, performance tests	20-40 min
4: Distribution	Package, document, publish to GitHub	10-20 min

Total: ~75-150 minutes for a complete, tested skill

Phase 1 covers Steps 1–2 below; Phases 2–4 correspond to Steps 3–5.

---

Skill Creation Workflow

Step 1: Discover Requirements

Research the domain first — before writing instructions, verify current best practices for the skill's subject. Use WebSearch and WebFetch to check official docs, community standards, and authoritative examples. Outdated or incorrect guidance in a skill is worse than no guidance: Claude will follow it confidently.

Retain all sources: every URL consulted must be recorded in the skill with its full link and a note of what it confirmed. Without sources, guidance cannot be verified or updated when the domain changes.

For research strategies, source quality standards, and the required Sources section format: references/research.md

1. Identify the problem and target users
2. Define 2-3 concrete use cases
3. Set measurable success criteria (time saved, errors reduced, quality improved)
4. Choose a skill category:

Category	INPUT → OUTPUT	Examples
1: Document & Asset Creation	Data/specs → document, code, report	API test generator, meeting notes summarizer
2: Workflow Automation	Task params → completed multi-step process	Deploy pipeline, code review workflow
3: MCP Enhancement	MCP tool outputs → smarter orchestration	Smart file search, BigQuery assistant

For in-depth category guidance: references/categories.md For interactive discovery questions: references/discovery.md

Step 2: Design Structure

Design using progressive disclosure — 3 loading levels:

Level	When loaded	Target length	Content
1: Metadata	Always (~100 words)	name + description	Trigger conditions
2: SKILL.md body	When skill triggers	under 5,000 words (ideally under 2,000)	Core workflow + pointers
3: references/ files	As needed	Unlimited	Deep detail, schemas, examples

For progressive disclosure writing tips and success metrics: references/best-practices.md

Step 3: Implement

Critical Rules:

• ✅ File MUST be named SKILL.md (not README.md)
• ✅ Folder name MUST be kebab-case — no spaces, no capitals (my-skill not My Skill)
• ✅ YAML frontmatter MUST include name, description, and version fields
• ✅ Description MUST include specific trigger phrases — what users SAY to activate the skill
• ✅ Description must be under 1024 characters (hard limit — longer descriptions are truncated)
• ✅ No XML angle brackets (< or >) in any frontmatter field
• ❌ NO README.md inside the skill folder — all docs go in SKILL.md or references/ (Exception: a README.md at the GitHub repo ROOT, outside the skill folder, is fine for GitHub.)
• ❌ NO spaces or underscores in folder names (my_skill → my-skill)

Frontmatter: required fields:

---
name: your-skill-name          # kebab-case only; no spaces, capitals, or underscores
description: What it does. Use when user asks to "specific phrase", "another phrase".
             # MUST include: what it does + when to use it (trigger conditions)
             # Under 1024 characters. No XML angle brackets.
             # Do NOT start with "claude" or "anthropic" (reserved namespaces).
version: 0.1.0                 # Required; use semantic versioning
---

Frontmatter: all optional fields:

---
name: your-skill-name
description: What it does and when. Use when user says "trigger phrase 1", "trigger phrase 2".
license: MIT                   # Optional: open-source license (MIT, Apache-2.0, etc.)
allowed-tools: "Bash(python:*) WebFetch"  # Optional: restrict which tools the skill can use
compatibility: Claude Code     # Optional: 1-500 chars; environment requirements
metadata:                      # Optional: custom key-value pairs
  author: Your Name
  version: 1.0.0               # Version inside metadata (Anthropic's spec); also accepted at top level
  mcp-server: your-server      # If skill requires a specific MCP server
  category: productivity
  tags: [automation, workflow]
  documentation: https://example.com/docs
---

Positioning language (outcome-focused: "generate tests 87% faster") belongs in README.md or GitHub landing page — NOT in the description field. See references/best-practices.md.

Folder structure (standalone skills at ~/.claude/skills/):

~/.claude/skills/your-skill-name/
├── SKILL.md                         # Required — loaded when skill triggers (<5k words)
├── references/                      # Docs Claude loads into context as needed
│   ├── detailed-guide.md            #   schemas, API docs, policies, detailed workflows
│   └── examples/                    #   working code users copy (subdirectory of references/)
│       └── working-example.sh
├── scripts/                         # Executables (run without loading into context)
│   └── validate.sh
└── assets/                          # Files used IN skill output (not loaded to context)
    └── template.html

Directory	Load into context?	Use for
references/	Yes, as needed	Schemas, API docs, policies, workflow guides
references/examples/	As needed	Working code users copy and adapt
scripts/	No (run directly)	Validators, scaffolders, utilities
assets/	No (used in output)	Images, fonts, HTML templates the skill pastes into output

Note: Plugin skills (in plugin-name/skills/) may place examples/ at the top level — that is plugin-dev convention. For standalone ~/.claude/skills/ skills, put examples inside references/.

To scaffold a new skill: bash scripts/scaffold-skill.sh my-skill-name To start from template: copy references/examples/SKILL-template.md

Step 4: Test

Three testing approaches (run in order):

1. Triggering tests — verify Claude activates on expected phrases; does NOT activate on unrelated requests
2. Functional tests — validate the skill's core workflow produces correct output for known inputs
3. Performance tests — measure improvement over baseline (time saved, error reduction, consistency)

Debugging trigger issues:

Ask Claude: "When would you use the [skill name] skill?"

Claude will quote its description back at you. Adjust based on what's missing or too vague.

Fixing undertriggering: Add more specific trigger phrases and relevant technical terms.

Fixing overtriggering: Add negative triggers to the description:

description: Processes PDF legal documents for contract review. Use for "review this contract",
  "analyze legal document", "extract contract clauses". Do NOT use for general PDF viewing,
  image extraction, or non-legal documents (use doc-converter skill instead).

To validate skill structure, naming, and frontmatter:

bash ~/.claude/skills/claude-skill-builder/scripts/audit-skill.sh ~/.claude/skills/YOUR-SKILL

For automated quality review, use the built-in skill-creator skill:

"Use the skill-creator skill to review this skill and suggest improvements"

Also available: the skill-reviewer agent from the plugin-dev plugin checks description quality.

For detailed test case templates and the Testing Triangle methodology: references/testing.md

Step 5: Distribute

Three distribution channels (choose one or all):

A. Claude.ai / Claude Code (individual install)

# Clone into Claude Code skills directory:
cd ~/.claude/skills && git clone https://github.com/username/your-skill-name
# Or: download ZIP → upload in Claude.ai Settings > Capabilities > Skills

B. Organization-wide deployment (admins only, shipped Dec 2025) Admins can deploy skills workspace-wide via Claude.ai admin console — automatic updates, centralized management. Users get the skill without any install step.

C. Programmatic / API Add skills to Messages API requests via container.skills parameter. Use the /v1/skills endpoint to manage skills. Works with the Claude Agent SDK for building custom agents.

GitHub setup for public distribution:

1. Create a public repo — the skill folder IS the repo (or is nested inside it)
2. Add README.md at the repo root (OUTSIDE the skill folder) with installation instructions and outcome-focused positioning: "Generate tests 87% faster" (GitHub marketing, not SKILL.md)
3. Share in Claude Discord or communities

For full distribution guidance, GitHub templates, and community strategies: references/distribution.md

---

Common Pitfalls

Pitfall	❌ Wrong	✅ Correct
File naming	my_skill/README.md	my-skill/SKILL.md
Description field	Outcome-focused: "generates tests 87% faster"	Trigger phrases: "create a skill", "improve my skill"
README positioning	Trigger phrases in GitHub README	Outcome-focused: "generate tests 87% faster"
No progressive disclosure	Monolithic wall of text	3-level: hook (50-100w) → workflow (200-400w) → detail
No testing	Write → publish immediately	Triggering + functional + performance tests
Missing success criteria	"Build a skill that helps with APIs"	"Reduce API test writing time by 75%"
Feature-focused description	"Uses OpenAPI parser and Jinja2 templates"	Trigger phrases + concise capability summary

---

Refining Existing Skills

Signs a skill needs refinement:

• File named README.md or folder has underscores/capitals (P0 — Claude cannot find it)
• Missing YAML frontmatter (P0 — Claude cannot auto-activate it)
• Description is outcome-focused instead of trigger-phrase format (P1)
• SKILL.md is over 5,000 words (P0 — hard limit; Claude reports degraded quality above this)
• SKILL.md is over 2,000 words with no references/ files (P1 — detail belongs in references/)
• Wall of text with no progressive disclosure structure (P1)

For the complete 5-step refinement process (audit → prioritize → fix → validate → document), migration scenarios, before/after examples, and performance tracking: references/refining-skills.md

---

Additional Resources

Reference Files (loaded as needed by Claude)

• references/research.md — Research strategies before writing skill instructions: how to find authoritative sources, evaluate quality, and translate knowledge into skill content
• references/best-practices.md — Progressive disclosure writing tips, success metrics framework, Testing Triangle, common anti-patterns
• references/refining-skills.md — Complete 5-step refinement process with migration scenarios, before/after examples, and continuous improvement framework
• references/sources.md — Anthropic PDF guide URL, MCP docs, community links, full citations
• references/categories.md — In-depth guide to all 3 skill categories with characteristics, examples, and best practices for each
• references/discovery.md — Interactive 20-question guided Q&A for discovering skill requirements, design choices, and implementation plan
• references/testing.md — Detailed test case templates for triggering, functional, and performance testing with concrete examples
• references/distribution.md — GitHub setup guide, installation instructions template, positioning language, community sharing strategies
• references/patterns.md — 5 advanced patterns (sequential orchestration, multi-MCP coordination, iterative refinement, context-aware selection, domain intelligence)
• references/troubleshooting.md — Fix guide: skill doesn't trigger, triggers too often, instructions not followed, context overload
• references/changelog.md — Version history and improvement notes
• notes/2026_03_reliable_skill_usage_and_design.md — Community research on skill activation rates (250 sandboxed evals): keyword matching vs semantic, naming conventions, forced-eval hooks, description template patterns

Scripts (run directly — do not load into context)

• scripts/audit-skill.sh — Skill structure smoke test with scored output (0-100%)

  bash ~/.claude/skills/claude-skill-builder/scripts/audit-skill.sh ~/.claude/skills/YOUR-SKILL
  

• scripts/scaffold-skill.sh — Create a new skill directory with correct structure

  bash ~/.claude/skills/claude-skill-builder/scripts/scaffold-skill.sh my-skill-name
  

---

Version History

v1.1.0 - 2026-03-05

• Added YAML frontmatter (enables Claude auto-detection)
• Rewrote body to imperative form throughout
• Integrated IMPROVEMENTS.md self-critique (moved to references/changelog.md)
• Corrected description templates: trigger-phrase format for SKILL.md, outcome-focused for README
• Trimmed SKILL.md from 932 → ~350 lines; moved detail to references/
• Corrected directory taxonomy: references/examples/ for standalone skills (Anthropic's recommended structure)
• Corrected README.md rule: enforce "no README inside skill folder" with distribution exception
• Added description field constraints: 1024-char hard limit, no angle brackets, kebab-case names
• Added Additional Resources section linking all references/ files and scripts/
• Created references/patterns.md with 5 advanced patterns + troubleshooting from Anthropic's guide
• Confirmed skill categories are from Anthropic's official guide — no "unofficial" label

v1.0.0 - Initial release based on Anthropic's Complete Guide

• Complete 4-phase methodology
• Progressive disclosure templates
• Testing framework
• Distribution strategies
• Common pitfalls guide