Expert guidance for creating high-quality Claude Code skills following Anthropic's official best practices. Use when creating, improving, or auditing skill files.
Expert guidance for creating high-quality Claude Code skills following Anthropic's official best practices. Use when creating, improving, or auditing skill files.
Claude Code Skill Expert
Guide for creating effective, well-structured Claude Code skills that follow Anthropic's official best practices.
When to Use This Skill
Creating a new SKILL.md file
Improving an existing skill's structure or effectiveness
Auditing a skill for token efficiency
Troubleshooting why a skill isn't being triggered
Optimizing skill context usage
Core Principles
1. Progressive Disclosure (CRITICAL)
Structure skills as a table of contents where Claude loads content on-demand:
Metadata (name + description) loads at startup
SKILL.md loads when triggered
Reference files load only as needed
Pattern: Keep SKILL.md under 500 lines. Move detailed content to separate reference files.
Example:
## Step 1: Analyze Code
Run the analyzer: `bun run analyzer.ts`**Output**: See [output-templates.md#analysis](references/output-templates.md#analysis) for format
2. Name and Description Quality
The most critical fields - Claude uses these to decide when to trigger the skill.
Good description:
description:Books
cinema
tickets
at
Classic
Cinemas.
Use
when
Nathan
asks
to
book
tickets,
see
movies
showing,
or
get
cinema
seats.
Bad description:
description:Ahelpfulskillforbookingthings
Rules:
Include what the skill does
Include when to use it (trigger phrases)
Use third person ("Books tickets" not "I book tickets")
---
name: my-skill
description: What it does and when to use it
allowed-tools: Bash, Read, Write
model: claude-sonnet-4-5
---# Skill Title
Brief introduction explaining purpose.
## Workflow Overview
[Optional: Visual diagram of steps]
## Step 1: First Action**Action**: What to do
**Command/Tool**: Specific tool or bash command
**Output**: Template reference or inline format
**Wait for**: User response or validation
---
## Step 2: Second Action
[Continue pattern...]
---
## References- [Templates](references/templates.md) - Exact output formats
- [Commands](references/commands.md) - CLI reference
- [Errors](references/errors.md) - Recovery patterns
Key Elements
Workflow clarity: Numbered steps with clear actions
Template references: Link to exact formats
Validation checkpoints: Where to wait for user confirmation
Progressive disclosure: "See X for details" instead of inline detail
Output Templates Best Practice
CRITICAL: Create a separate references/output-templates.md file with exact copy-paste formats.
Template File Structure
# Output Templates**CRITICAL**: Use these exact templates. Copy the structure precisely.
---
## Template Name**ALWAYS use this exact format**:
\`\`\`
[Exact format with placeholders]
\`\`\`
**Rules**:
- Specific formatting requirements
- What to show/hide
- How to handle edge cases
**Mapping from data**:
\`\`\`
field_name → [PLACEHOLDER]
nested.field → [OTHER_PLACEHOLDER]
\`\`\`
**Example**:
\`\`\`
[Concrete example with real data]
\`\`\`
Why This Works
Strictness levels: "ALWAYS use this exact format" vs "use your best judgment"
Visual examples: Claude sees the desired output structure
Mapping clarity: Links data sources to placeholders
Progressive disclosure: Loaded only when needed for that step
Common Patterns
1. Conditional Workflow Pattern
## Step 2: Choose Path**If** creating new content → Go to Step 3
**If** editing existing → Go to Step 5
2. Validation Loop Pattern
## Step 4: Validate
Run validator → identify errors → fix → repeat until passing
**See**: [error-handling.md#validation](references/error-handling.md#validation)
3. Tool Selection Pattern
## Step 1: Analyze Request**Use**:
-`kit_grep` for literal text search
-`kit_semantic` for "find where we handle X"
-`kit_symbols` for function definitions
**See**: [tool-selection.md](references/tool-selection.md) for full decision tree
4. High-Level Guide with References
# My Skill
Keep SKILL.md as overview.
**Resources**:
- [Forms](references/forms.md) - Advanced form handling
- [API](references/api.md) - API details
- [Examples](references/examples.md) - Concrete examples
Token Efficiency Strategies
1. Split Mutually Exclusive Content
If certain contexts are rarely used together, keep paths separate:
references/
├── create-workflow.md # Only for creating new items
└── edit-workflow.md # Only for editing existing
2. Use Code for Deterministic Operations
Scripts don't load into context - only their output does.
Efficient:
bun run extract-fields.ts # Code not in context
Inefficient:
Parse the JSON manually and extract these 20 fields...
[20 lines of parsing instructions]
