claude-code-skill-expert

# 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**:
```markdown
## 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**:
```yaml
description: Books cinema tickets at Classic Cinemas. Use when Nathan asks to book tickets, see movies showing, or get cinema seats.
```

**Bad description**:
```yaml
description: A helpful skill for booking things
```

**Rules**:
- Include **what** the skill does
- Include **when** to use it (trigger phrases)
- Use third person ("Books tickets" not "I book tickets")
- Max 1024 characters
- Include key terms users would mention

### 3. File Organization

**One-level-deep references** from SKILL.md:

```
skill/
├── SKILL.md              # Overview, workflow steps
└── references/
    ├── templates.md      # Output formats
    ├── commands.md       # CLI reference
    └── errors.md         # Error recovery
```

**Don't do**:
```
skill/
├── SKILL.md
└── references/
    ├── advanced/
    │   └── deep-file.md  # Too deep!
```

---

## SKILL.md Structure

### Recommended Format

``