Expert guidance for creating high-quality Claude Code skills following Anthropic's official best practices. Use when creating, improving, or auditing skill files.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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]
