creating-skill

# Skill Creation Guide

Practical guidelines for creating skills that Claude Code can effectively discover and use.

## Core Principles

### 1. Brevity is Key

**Claude is already smart** - Only add context that Claude doesn't already have.

```markdown
✓ Good example (concise):
## Extracting PDF Text
Use pdfplumber:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

✗ Bad example (verbose):
PDF (Portable Document Format) files are...
First, you need to install using pip...
```

**Token Budget**: Keep SKILL.md body under 500 lines

### 2. Set Appropriate Freedom Levels

Adjust specificity level to match task fragility:

**High Freedom** (multiple approaches valid):
```markdown
## Code Review Process
1. Analyze code structure and organization
2. Check for potential bugs
3. Suggest readability improvements
```

**Low Freedom** (operation is fragile):
```markdown
## Database Migration
Execute this script exactly:
python scripts/migrate.py --verify --backup
Do not modify the command.
```

### 3. Test with All Models

Test your skill with all models you plan to use (Haiku, Sonnet, Opus).

## Skill Structure

### YAML Front Matter

```yaml
---
name: example-skill        # lowercase, numbers, hyphens only (max 64 chars)
description: Specific description  # max 1024 chars, written in third person
---
```

**Naming Conventions** (gerund form recommended):
- ✓ `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`
- ✗ `helper`, `utils`, `anthropic-helper`

### Writing Effective Descriptions

**Always write in third person**:
- ✓ "Processes Excel files and generates reports"
- ✗ "I can help you process Excel files"

**Be specific and include key terms**:
```yaml
description: Extracts text and tables from PDF files and fills forms. Use when mentioning PDF files, forms, or document extraction.
```

## Progressive Disclosure Patterns

### Pattern 1: High-Level Guide with References

```markdown
## Quick Start
[Basic code