---

name: write-skill description: Use when creating, editing, or improving Claude Code skills (SKILL.md files). Also use when a skill isn't triggering reliably or needs restructuring.

Writing Claude Code Skills

A skill is a folder that Claude explores, not a file it reads. The SKILL.md is the entrypoint, but scripts/, references/, and assets/ around it are just as important. Skills load through progressive disclosure: descriptions are always present, the body loads when triggered, and supporting files load only when Claude reads them.

Step 1: Choose a Purpose

Every skill fits one purpose category. Choosing the right one shapes what the skill contains and how it should be structured.

| Category | What It Does | Examples | | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------ | | Library / API Reference | Teaches Claude about internal tools, APIs, SDKs | MCP server docs, internal API patterns | | Product Verification | Pairs with testing frameworks to confirm code works | TDD workflows, integration test runners | | Data Fetching | Connects to monitoring/data stacks with credential handling | Metrics dashboards, event source queries | | Business Process | Automates workflows, keeps logs for consistency | PR workflows, deployment checklists | | Code Scaffolding | Generates boilerplate where templates alone aren't enough | Project setup, component generators | | Code Quality | Enforces standards, sometimes spawning adversarial subagents | Linting, audit dispatchers | | CI/CD | Babysits PRs, retries flaky tests, resolves merge conflicts | PR monitors, build fixers | | Runbook | Walks through multi-tool investigations from a symptom | Incident response, debugging playbooks | | Infrastructure Operations | Finds orphaned resources, posts findings, executes cascading cleanup | Resource cleanup, environment provisioning |

The best skills fit one category cleanly. Confusing skills straddle several.

Then choose a structural pattern based on how the skill teaches:

| Structure | Examples | Key Patterns | | ---------- | ------------------- | ---------------------------------------------------- | | Discipline | TDD, verification | Iron Laws, rationalization tables, red-flags lists | | Technique | debugging, research | Templates, reference tables, step-by-step procedures | | Workflow | planning, execution | Flowcharts, cross-references, integration sections | | Reference | API docs, tools | Architecture diagrams, comparison tables |

Purpose (what the skill does) x Structure (how it teaches) = the design space.

Step 2: Name and Structure

skill-name/
  SKILL.md              # Required -- frontmatter + instructions
  scripts/              # Executable code (runs without consuming context)
  references/           # Documentation loaded into context as needed
  assets/               # Templates, config files, icons

• Name: kebab-case, max 64 chars, must match directory name
• Gerunds for processes: creating-skills, testing-hooks
• Avoid vague names: helper, utils, tools

Claude does NOT auto-explore skill folders. It follows explicit references in SKILL.md only. Every file in scripts/, references/, and assets/ must be enumerated in the body or Claude won't know it exists. Keep references one level deep -- if advanced.md references details.md, Claude may only partially read the second file.

Scripts are first-class. The most powerful thing you can put in a skill folder is code. Scripts execute and return results without their source code occupying context. A validation script, a language detector, a test runner -- these preserve context for reasoning while delegating deterministic work to code. When test runs reveal Claude independently writing the same helper script across sessions, that's a signal to bundle it in scripts/.

Step 3: Write the Description

The description is how Claude decides whether to load your skill. This is the highest-leverage part of skill authoring.

Rules:

1. Start with "Use when..." -- triggering conditions only
2. Include trigger keywords -- words and phrases users would actually say, error messages they'd encounter, symptoms they'd describe
3. Be aggressively specific -- "Use when tests have race conditions" not "For async testing"
4. Make it pushy -- Claude undertriggers skills. Include contexts like "even if they don't explicitly ask for X"
5. NEVER summarize the workflow

Why rule 5 matters: A description saying "dispatches subagent per task with code review between tasks" caused Claude to perform ONE review, even though the body specified TWO. Claude treated the description as sufficient instruction and never read deeply enough into the body to discover the second review. Changing to pure triggering conditions fixed it. The description says when to activate. The body says what to do.

# BAD: Summarizes workflow
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

Debug triggers: Ask Claude "When would you use the [skill name] skill?" It quotes the description back. Adjust based on what's missing.

Limits: Max 1024 characters per description. All descriptions share a budget of ~2% of context window (fallback 16K chars, ~30-40 skills at ~100 words each). Exceeding the budget causes silent truncation -- skills vanish without warning. Run /context to check.

For rigorous description optimization, see references/evaluation.md.

Step 4: Design the Content

Start with Gotchas

Gotchas are the highest-signal content in any skill. A skill without a gotchas section hasn't been used enough. Gotchas are built from observed failure points -- the specific, concrete ways Claude goes wrong without guidance.

A gotcha is NOT a generic best practice. It is a particular mistake that was actually observed, described precisely enough that Claude can recognize when it's about to make the same mistake. Add gotchas as the first section of a new skill and make them the primary focus of every maintenance pass.

## Gotchas

### Claude will try to mock the database
When tests touch persistence, Claude defaults to mocking. This burned us last quarter
when mocked tests passed but the production migration failed because mocks diverged
from the actual schema. Always use the real test database.

### The retry logic swallows connection errors
Claude's default error handling catches too broadly. Connection errors in the job
queue must propagate to trigger the circuit breaker. Catch only ValueError and
ValidationError -- let everything else raise.

Each gotcha explains what happens, why it's wrong, and what to do instead. The "why" is what gives Claude the judgment to handle edge cases the gotcha doesn't explicitly cover.

Explain the Why, Not MUSTs

Claude has theory of mind. When it understands why a practice matters -- the incident that motivated the rule, the failure mode it prevents -- it handles edge cases that rigid constraints miss.

A rule that says "NEVER mock the database in these tests" is less effective than explaining that last quarter, mocked tests passed while a production migration broke because the mocks diverged from the actual schema. The explanation carries the rule AND the judgment about when it applies.

If you find yourself writing ALWAYS or NEVER in capitals, that's a signal to stop and ask whether the reasoning can be explained instead. Reserve imperative constraints for genuine non-negotiables where the reasoning is too subtle or the consequences too severe to leave to judgment.

Push Past Defaults

Effective skill content pushes Claude out of its default patterns, not back into them. Restating what Claude already knows wastes context. Focus on:

• Company-specific conventions Claude can't know
• Counter-intuitive best practices that contradict Claude's training
• Domain knowledge that only comes from experience with this codebase
• Patterns Claude consistently gets wrong without guidance

If the skill content matches what Claude would do anyway, it's not earning its budget.

Match Structure to Skill Type

Discipline skills need anti-rationalization mechanisms because Claude will find convincing reasons to skip the hard parts:

1. Rationalization table -- maps common excuses to reality checks ("The test is trivial" -> "Trivial tests catch regression")
2. Red-flags list -- thoughts that mean "stop" ("I already know this works" -> run the test anyway)
3. Explicit loophole closure -- forbid specific workarounds Claude might exploit
4. One Iron Law -- a non-negotiable statement that anchors the entire discipline

Technique skills need templates, reference tables, and step-by-step procedures that provide structure without removing judgment.

Workflow skills need cross-references between phases, integration points with other skills, and clear handoff criteria.

Reference skills need comparison tables, architecture diagrams, and context for when each option is appropriate.

Quality Markers

From analysis of 18 production skills:

| Marker | Excellent | Mediocre | | --------------------- | ---------------------------------- | ----------------------------- | | Agent internal state | Red-flags map thoughts to actions | Rules without self-monitoring | | Empirical grounding | "24 failures", "6 iterations" | No evidence of real use | | Executable algorithms | Pseudocode, templates, checklists | Abstract principles only | | Good/Bad comparisons | Side-by-side with explanation | One example or none | | Scope boundaries | Explicit "when NOT" with reasoning | Missing or vague |

Step 5: Organize for Progressive Disclosure

Skills load in three stages with dramatically different costs:

| Level | What Loads | When | Token Impact | | ----- | ------------------ | ------------------- | --------------------- | | 1 | Name + description | Always | ~100 tokens per skill | | 2 | SKILL.md body | When skill triggers | ~1-2% of context | | 3 | Referenced files | When Claude reads | On-demand only |

The file system IS the progressive disclosure mechanism. Put the core workflow in SKILL.md. Put heavy reference material (API docs, lookup tables, exhaustive examples) in references/. Put executable tools in scripts/.

The Routing Pattern

When a domain has many subspecialties, separate skills consume the description budget rapidly. Fifteen programming subskills at 100 words each eat 40% of the budget even when the user is writing documentation.

The routing pattern consolidates subspecialties under a single description. One SKILL.md body acts as a router, directing Claude to the appropriate reference file:

## Language-Specific References

Read the appropriate reference based on the project:
- Swift code (.swift files): Read `references/swift.md`
- TypeScript/React (.ts, .tsx): Read `references/typescript.md`
- C++ (.cpp, .h): Read `references/cpp.md`
- PostgreSQL queries: Read `references/postgres.md`

Fourteen descriptions eliminated, ~7000 characters returned to the budget. The content is preserved; only the loading mechanism changes.

For the complete routing pattern with examples, the flag-file enhancement for conditional hooks, and composability guidance, see references/routing-pattern.md.

Size Guidance

• SKILL.md body: under 500 lines (~2,000-3,000 words)
• One excellent code example in the most relevant language, not multi-language
• Keep references one level deep from SKILL.md
• Monitor /context for budget warnings when running 20+ skills

Step 6: Test and Iterate

Testing

Three areas:

1. Triggering: Does the skill activate on relevant queries? NOT on unrelated ones? Target: 90% on 10-20 test queries.
2. Functional: Does Claude follow the instructions correctly? Handle edge cases? Use Given/When/Then format.
3. Performance: Run with-skill vs without-skill on the same task. Track pass rate, messages, tool calls, tokens.

For the full evaluation methodology -- including description optimization loops, parallel test runs, and statistical benchmarking -- see references/evaluation.md.

Skills Evolve Through Use

A skill without observed failures hasn't been tested seriously. The lifecycle:

1. Draft -- write the initial skill based on what you know
2. Test -- run against realistic scenarios
3. Observe -- watch where Claude goes wrong
4. Add gotchas -- each failure becomes a gotcha
5. Test again -- verify the gotchas help
6. Review periodically -- as models improve, guardrails that helped weaker models may constrain stronger ones

Anthropic's AskUserQuestion tool took three complete redesigns. The first two were technically sound but Claude didn't gravitate toward using them. Skills should be designed with the expectation that the first version won't be right.

Step 7: Deploy

1. Create the skill directory in the appropriate location:
   • Global: ~/.claude/skills/skill-name/
   • Project: .claude/skills/skill-name/
   • Plugin: skills/skill-name/ within the plugin structure
2. Verify the skill appears in /context on next conversation start
3. Check budget -- ensure other skills aren't being truncated

Frontmatter Quick Reference

---
name: skill-name          # kebab-case, max 64 chars, must match directory
description: Use when ... # Max 1024 chars, triggering conditions only
---

Key optional fields:

| Field | Purpose | | -------------------------- | ------------------------------------------------------ | | user-invocable: false | Hidden from / menu; only Claude can trigger | | disable-model-invocation | User-only via /name; removed from description budget | | context: fork | Runs in isolated subagent context | | model | Override model for this skill | | allowed-tools | Space-delimited pre-approved tools | | hooks | Event handlers scoped to skill lifetime |

For the complete frontmatter reference including all fields, string substitutions, dynamic context, and persistent data patterns, see references/frontmatter.md.

For frontmatter hooks (component-scoped event handlers), see references/hooks.md.

Additional Resources

• references/frontmatter.md -- Complete frontmatter fields, string substitutions, persistent data patterns
• references/routing-pattern.md -- Complex skill organization, flag-file enhancement, composability
• references/evaluation.md -- Description optimization loops, parallel testing, benchmarking
• references/hooks.md -- Frontmatter hooks: all events, handler types, output formats

Common Mistakes

| Mistake | Fix | | -------------------------------- | ------------------------------------------------------------ | | Description summarizes workflow | Description = triggering conditions only | | No gotchas section | Add observed failure points as the first maintenance pass | | Skill too long (500+ lines) | Move reference material to references/ | | No trigger keywords | Add error messages, symptoms, tool names to description | | Vague description | "Use when tests have race conditions" not "For testing" | | Multi-language examples | One excellent example in the most relevant language | | No scope boundaries | Add "When NOT to use" section | | States the obvious | Focus on what Claude gets wrong, not what it already knows | | ALWAYS/NEVER without reasoning | Explain why -- Claude handles edge cases better with context | | Narrative storytelling | Convert to patterns, tables, checklists | | Files not enumerated in SKILL.md | Claude won't discover unenumerated files | | Nested file references | Keep references one level deep from SKILL.md | | Write-once, never revised | Skills evolve through gotchas, testing, periodic review | | Untested skill | Test triggering + functional + performance |