claude-skill-builder

What this skill does

# 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**:
```yaml
---
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**:
```yaml
---
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:
```yaml
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).