creating-skills

name	creating-skills
disable-model-invocation	true
description	Skill authoring and optimization. Use when creating new skills, editing existing skills, verifying skill quality, or optimizing trigger descriptions.

Creating Skills

Skills are eval-driven process documentation. Build evaluations first, write the skill to pass them, then optimize trigger descriptions for activation accuracy.

For comprehensive Anthropic guidelines, see best-practices-reference.md.

Eval-Driven Development

Why Evals First

A skill without evals is untested code. The eval proves the skill teaches the right thing and activates at the right time.

The Claude A / Claude B Pattern

Use two separate agent sessions to avoid self-confirmation bias:

1. Claude A (author) — writes the skill content
2. Claude B (tester) — runs evaluation scenarios cold, without seeing the authoring process

This separation ensures the skill works for any agent, not just one primed by the authoring context.

Minimum Evaluation Requirements

Every skill needs at least 3 evaluation scenarios before writing content:

1. Baseline (no skill) — Run scenarios without the skill. Document what the agent did wrong, what rationalizations it used (verbatim), which pressures triggered violations.
2. With-skill pass — Run the same scenarios with the skill loaded. The agent should now comply.
3. Adversarial/edge case — Test boundary conditions, near-misses, and rationalization attempts.

Record concrete outputs, not impressions. Quote agent responses verbatim when documenting failures.

Eval-Write-Eval Cycle

1. Design 3+ realistic evaluation scenarios
2. Run baseline WITHOUT skill (Claude B) -> document failures
3. Write minimal skill addressing those specific failures (Claude A)
4. Run same scenarios WITH skill (Claude B) -> verify compliance
5. If new failure modes appear, add counters and re-test

Do not add content for hypothetical cases. Every section should trace back to an observed failure.

Skill Types

• Technique — Concrete method with steps (e.g., root-cause-tracing, condition-based-waiting)
• Pattern — Way of thinking about problems (e.g., flatten-with-flags)
• Reference — API docs, syntax guides, tool documentation

Directory Structure

skills/
  skill-name/          # letters, numbers, hyphens only
    SKILL.md           # required — main instructions, under 500 lines
    reference.md       # optional — detailed docs, loaded on demand
    examples.md        # optional — usage examples, loaded on demand
    scripts/
      helper.py        # optional — executed via Bash, NOT loaded into context
    assets/
      template.pptx    # optional — output files (templates, icons, fonts), NOT loaded into context

assets/ holds files used in skill output (brand logos, slide templates, boilerplate projects). Unlike references, assets are never read into context — they're copied, modified, or embedded in output.

Keep references one level deep from SKILL.md. Nested references (SKILL.md → advanced.md → details.md) cause Claude to partially read files. For files over 100 lines, include a table of contents at the top.

SKILL.md Frontmatter

---
name: skill-name-with-hyphens
description: What it does. Use when [specific triggering conditions]
---

Hard constraints:

• name: Max 64 chars. Lowercase letters, numbers, hyphens only. No "anthropic" or "claude".
• description: Max 1024 chars. Non-empty. No XML tags.
• Prefer gerund form for names: processing-pdfs, analyzing-data, testing-code

Optional frontmatter fields:

• disable-model-invocation: true — only user can invoke (not auto-triggered, saves context budget)
• user-invocable: false — only Claude can invoke (background knowledge, hidden from / menu)
• allowed-tools — restrict tools when skill is active (e.g., Read, Grep, Glob)
• context: fork — run in isolated subagent context
• agent — which subagent type when context: fork is set
• model — override model for this skill (e.g., haiku for cheap tasks)
• effort — low, medium, high, max (Opus 4.6 only)
• hooks — lifecycle hooks scoped to this skill's execution
• paths — glob patterns limiting when skill auto-activates (e.g., ["src/**/*.py"])
• shell — bash (default) or powershell
• argument-hint — shown during autocomplete (e.g., [issue-number])

Description rules:

• Third-person always. Description is injected into the system prompt.
• CRITICAL: Description = when to use ONLY. NEVER summarize the skill's process or workflow. Testing shows that when a description summarizes workflow, Claude follows the description instead of reading the skill body.
• Include both what the skill does AND when to use it.
• Include 5+ keywords from actual user workflows.
• Front-load the key use case — descriptions are truncated at ~250 chars in skill listings.
• Be assertive about activation — include phrases like "Make sure to use this skill whenever the user mentions X, even if they don't explicitly ask for it."

Context budget: All skill descriptions share a pool of ~1% of context window (fallback ~8K chars). Every character in every description consumes from this shared pool. Skills with disable-model-invocation: true are NOT loaded into context at all. Override with SLASH_COMMAND_TOOL_CHAR_BUDGET env var.

SKILL.md Body Structure

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## Quick Reference
Table or bullets for scanning common operations

## Core Pattern
Before/after comparison (for techniques/patterns)

## Implementation
Inline code for simple patterns, link to file for heavy reference

## Common Mistakes
What goes wrong + fixes

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece: "Does Claude really need this explanation?"

Writing style: Use imperative/infinitive form ("Validate the input", "Configure the server"), not second person ("You should validate..."). Explain why behind instructions — LLMs respond better to reasoning than bare ALWAYS/NEVER directives.

Degrees of Freedom

Match specificity to task fragility:

Level	When to use	Example
High (text instructions)	Multiple valid approaches, context-dependent	Code review guidelines
Medium (parameterized scripts)	Preferred pattern exists, some variation ok	Report generation with template
Low (exact scripts, no params)	Fragile operations, consistency critical	Database migrations, deployments

Token Efficiency

• Every-session skills (loaded via hook): absolute minimum tokens. <200 words.
• Frequently-triggered skills: <500 words preferred.
• On-demand skills (disable-model-invocation): more generous, but still under 500 lines.
• Body word count target: 1,500-2,000 words ideal, <5,000 words max.
• Scripts in scripts/ are executed, not loaded — only output consumes tokens.

Progressive Disclosure Split

Even skills under 300 lines benefit from splitting SKILL.md into a lean core + reference.md. The split reduces context consumption by ~46% on average with zero quality loss — Claude reads reference.md on demand only when it needs detailed code examples.

What stays in SKILL.md (always loaded when skill triggers):

• Workflow steps, decision tables, rules, API summaries
• Minimal code snippets (2-5 lines) showing correct/wrong patterns
• Checklists, quick-reference tables
• Cross-references to other skills
• A "## Detailed Reference" section linking to [reference.md](reference.md)

What moves to reference.md (loaded only when Claude needs implementation details):

• Full code examples (>10 lines) from the codebase
• Complete class/system implementations showing patterns end-to-end
• Deep-dive explanations of internal mechanisms
• Test code examples

When to split: Always consider splitting if the skill has code examples >10 lines. The question is not "is this skill too long?" but "does Claude need this code block to understand the workflow, or only when implementing?" If the latter, extract it.

Description Optimization

The description controls activation rate. Optimize methodically:

Step 1 — Keyword Coverage

Use words Claude would search for: error messages, symptoms ("flaky", "hanging", "race condition"), tool names, synonyms. Cover the vocabulary space of likely user prompts.

Step 2 — Build Eval Queries

Create at least 20 evaluation queries:

• 8-10 should-trigger queries (realistic user prompts with personal context, specific details)
• 8-10 should-not-trigger queries (near-misses from adjacent domains, not obviously irrelevant)

Step 3 — Test and Iterate

1. For each query, check if the description would cause activation
2. Adjust keywords and phrasing to improve precision and recall
3. Re-test until satisfied with activation accuracy

Activation Rate Benchmarks

• Good: >80% correct activation on eval set
• Acceptable: >70% with no false positives on critical should-not-trigger queries
• Needs work: <70% or any false positive on dangerous near-misses

Step 4 — Add Concrete Examples

If keyword coverage alone is insufficient, add specific phrases from real user prompts. Concrete examples improve activation from ~50% to 72-90%.

Workflow Patterns

Checklist Pattern

For complex multi-step tasks, provide a copyable checklist Claude can track progress with.

Feedback Loop Pattern

Run validator → fix errors → repeat. Greatly improves output quality for document generation, form filling, code review.

Plan-Validate-Execute Pattern

Have Claude create an intermediate plan file → validate with script → execute. Catches errors early.

Conditional Workflow

Guide Claude through decision points: "Creating new? → Creation workflow. Editing existing? → Editing workflow."

Template Pattern

Provide output format templates (strict or flexible) so Claude produces consistent structured output.

Examples Pattern

Input/output pairs work like few-shot prompting — show what good output looks like for representative inputs.

Bulletproofing Discipline Skills

For skills that enforce rules, resistance to rationalization is critical.

Close every loophole explicitly — state the rule, then forbid specific workarounds.

Build a rationalization table from baseline testing:

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |

Red flags list — makes agent self-checking easy.

Dynamic Features

String Substitutions

Variable	Description
$ARGUMENTS / $N	Arguments passed when invoking the skill
${CLAUDE_SKILL_DIR}	Directory containing the skill's SKILL.md
${CLAUDE_SESSION_ID}	Current session ID

Dynamic Context Injection

The !`command` syntax runs shell commands before skill content is sent to Claude:

## PR context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

Anti-Patterns

• Narrative — "In session 2025-10-03, we found..." is too specific, not reusable
• Multi-language dilution — One great example beats mediocre examples in 5 languages
• Generic labels — helper1, step3 have no semantic meaning
• Skipping evals — Writing content before observing failures produces bloated skills
• Graphviz diagrams — Rendered as raw text in terminals. Use numbered lists or tables instead.
• Workflow summary in description — Claude follows description shortcut instead of reading body
• Vague descriptions — "Helps with documents" achieves ~20% activation
• Over-explaining — Claude knows what PDFs are and how libraries work
• Deeply nested references — Keep one level deep from SKILL.md
• Time-sensitive info — "Before August 2025, use old API" becomes wrong. Use "Old patterns" section.
• Inconsistent terminology — Pick one term ("endpoint" not "endpoint/URL/route/path")
• Too many options — Provide one default with an escape hatch, not 5 choices
• Excessive ALWAYS/NEVER caps — Explain reasoning instead; LLMs respond better to "why" than bare directives

Testing Across Models

What works for Opus may need more detail for Haiku. If a skill will be used across models:

• Haiku: May need more explicit guidance and examples
• Sonnet: Balanced — good default target
• Opus: May be over-served by verbose instructions — trim for efficiency

Checklist

EVAL Phase:

• Design 3+ realistic evaluation scenarios
• Run WITHOUT skill (Claude B) — document exact failures verbatim
• Record rationalizations and failure modes

WRITE Phase:

• Name: lowercase, hyphens, max 64 chars, gerund form preferred
• Frontmatter max 1024 chars, description in third person
• Description: no workflow summary, includes "Use when..." + keywords, under 250 chars
• Body under 500 lines. Heavy reference in separate files.
• Appropriate degree of freedom for the task type
• Only context Claude doesn't already have
• References one level deep, files >100 lines have TOC
• Progressive disclosure split — code examples >10 lines moved to reference.md

VERIFY Phase:

• Run WITH skill (Claude B) — verify compliance on all scenarios
• Add rationalization table (if discipline skill)
• Re-test until bulletproof

OPTIMIZE Phase:

• Build 20+ eval queries for description
• Test activation accuracy (target >80%)
• Add concrete examples if activation <70%
• Test with Haiku, Sonnet, and Opus if cross-model use planned