skill-writing

Guide the creation of new Claude Code skills following official best practices to ensure optimal performance, discoverability, and maintainability.

Step 1: Identify the Gap

Ask: Does Claude really need this skill?

```bash

# Test Claude's baseline performance WITHOUT the skill

# - Can Claude already do this task reasonably well?

# - What specific knowledge/capability is missing?

# - Will a skill genuinely improve results?

```

Only create a skill if:

• ✅ Claude lacks specific domain knowledge
• ✅ Task requires exact procedures or formats
• ✅ Performance improvement is measurable
• ❌ Claude can already handle it well
• ❌ Only saves a few minutes
• ❌ Task is too variable/creative

Step 2: Create Evaluations First

Before writing extensive documentation:

```python

# Create 3+ test scenarios

evaluations = [

{

"input": "Process this PDF with forms",

"expected": "Extracted form data in JSON format",

"baseline_performance": "fails to extract structured data"

},

{

"input": "Generate chart from spreadsheet",

"expected": "Bar chart with proper labels",

"baseline_performance": "creates chart but missing labels"

},

# Add more scenarios...

]

```

Test baseline: Run scenarios without skill, measure gaps

Step 3: Write Minimal SKILL.md

Keep under 500 lines

```bash

# Create skill directory

mkdir -p ~/.claude/skills/my-skill

# Create SKILL.md

touch ~/.claude/skills/my-skill/Skill.md

```

Start with this template:

```markdown

---

name: processing-pdfs

description: Extract text, tables, and forms from PDF files including scanned documents. Use when working with PDFs or document extraction tasks.

version: 1.0.0

---

# PDF Processing

[One sentence: what this skill does]

Step 1: [Action]

\\\`bash

# Concrete command

\\\`

Step 2: [Action]

[Clear instructions]

[2-3 input/output examples]

```

Step 4: Test with Fresh Instances

```bash

# Open new Claude Code session

# Test skill by triggering scenarios

# Observe where Claude struggles

# Note which files get accessed

```

Step 5: Iterate Based on Usage

```markdown

# Refinement cycle:

1. Observe real usage patterns
2. Identify missing information
3. Add only what's needed
4. Test again
5. Repeat until evaluations pass

```

Directory Structure

```

skill-name/ # Use gerund: verb + -ing

├── Skill.md # Required (capital S)

├── REFERENCE.md # Optional (large reference material)

├── TEMPLATE.md # Optional (output templates)

└── scripts/ # Optional (executables)

└── helper.py

```

YAML Frontmatter (Required)

```yaml

---

name: processing-pdfs # Gerund form, lowercase-with-hyphens, max 64 chars

description: Extract text, tables, and forms from PDF files including scanned documents. Use when working with PDFs or document extraction tasks. # Max 1024 chars, third person, specific

version: 1.0.0 # SemVer format

dependencies: python>=3.8, pdfplumber>=0.9.0 # Optional, list required packages

---

```

Naming Rules:

• ✅ Use gerund form (verb + -ing): processing-pdfs, analyzing-spreadsheets
• ✅ Max 64 characters
• ✅ Lowercase letters, numbers, hyphens only
• ❌ Avoid vague names: helper, utils, tool

Description Rules:

• ✅ Third person: "Extracts text from PDFs"
• ❌ First/second person: "I can extract" or "You can use"
• ✅ Specific: "Extract text, tables, and forms from PDF files"
• ❌ Vague: "Helps with documents"
• ✅ Include WHAT it does: "Extracts text, tables, forms"
• ✅ Include WHEN to use: "Use when working with PDFs"
• ✅ Include key terms: "PDF", "document extraction", "tables"

Good vs Bad Descriptions

```yaml

# ❌ Bad - Vague, first person, no triggers

description: I help you process different types of files and documents.

# ❌ Bad - Too generic, missing context

description: Processes data efficiently.

# ❌ Bad - Second person, unclear

description: You can use this to work with files.

# ✅ Good - Specific, third person, clear triggers

description: Extract text, tables, and forms from PDF files including scanned documents. Use when working with PDFs or document extraction tasks.

# ✅ Good - Clear capability and context

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing tabular data or Excel files.

```

Progressive Disclosure Pattern

Keep SKILL.md under 500 lines for optimal performance (target: under 300 lines for complex skills)

#### Directory Structure

```

skill-name/

├── SKILL.md # Main file (always loaded, <500 lines)

└── references/ # On-demand detailed content

├── WORKFLOW-STEPS.md # Detailed step-by-step procedures

├── TROUBLESHOOTING.md # Error handling and edge cases

├── TEMPLATE-EXAMPLES.md # Templates and code examples

└── [DOMAIN-SPECIFIC].md # Skill-specific detailed content

```

#### SKILL.md Structure (Always Loaded)

```markdown

Core Steps

1. Step Name: Brief description of what to do
2. Step Name: Brief description of what to do

[...concise steps...]

For detailed step-by-step workflow with commands and examples:

\\\`

Read ~/.claude/skills/[skill-name]/references/WORKFLOW-STEPS.md

\\\`

Use when: Performing the task, need specific commands, or understanding each step

```

#### Loading Guidance Format

Always include explicit loading instructions with "Use when" context:

```markdown

For [detailed topic]:

\\\`

Read ~/.claude/skills/[skill-name]/references/[FILENAME].md

\\\`

Use when: [specific scenario requiring this content]

```

#### What to Extract to references/

| Content Type | Reference File | Extract When |

| ------------------ | ---------------------- | ------------------------------ |

| Detailed workflows | WORKFLOW-STEPS.md | Steps exceed 20 lines |

| Troubleshooting | TROUBLESHOOTING.md | >5 error scenarios |

| Templates/examples | TEMPLATE-EXAMPLES.md | Complex output formats |

| Domain checks | [DOMAIN]-CHECKS.md | Language/tool-specific details |

| Validation rules | VERIFICATION-CHECKS.md | Detailed verification criteria |

#### Example: Before and After

Before (680 lines - too long):

```markdown

Step 1: Discovery

[50 lines of detailed commands and examples]

Step 2: Extraction

[80 lines of detailed procedures]

...

```

After (200 lines - optimal):

```markdown

Core Steps

1. Discovery: Identify files using grep/glob patterns
2. Extraction: Read source, copy exact signatures
3. Documentation: Use templates, follow patterns
4. Verification: Check accuracy against source

For detailed workflow with commands and verification checklists:

\\\`

Read ~/.claude/skills/my-skill/references/WORKFLOW-STEPS.md

\\\`

```

#### Reference File Guidelines

• ✅ Keep references ONE level deep (SKILL.md → references/FILE.md)
• ✅ Use ALL CAPS for reference filenames
• ✅ Include complete, standalone content (don't reference other references)
• ✅ Start each reference with brief context of what it contains
• ❌ Don't nest references (references/A.md → references/B.md)
• ❌ Don't duplicate content between SKILL.md and references

File Naming Conventions

```

✅ Good:

• Skill.md (capital S, required)
• REFERENCE.md (all caps for supporting docs)
• TEMPLATE.md (all caps)
• FORMS.md (all caps)

❌ Bad:

• skill.md (lowercase s)
• reference.txt (wrong extension)
• my_template.md (underscores)

```

Sequential Workflows

```markdown

Step 1: Validate Input

\\\`bash

# Check file exists

test -f document.pdf || echo "File not found"

\\\`

Step 2: Extract Text

\\\`python

import pdfplumber

with pdfplumber.open('document.pdf') as pdf:

text = pdf.pages[0].extract_text()

\\\`

Step 3: Verify Output

Expected format:

\\\`json

{

"pages": 5,

"text": "extracted content..."

}

\\\`

```

Concrete Examples Pattern

Provide 2-3 examples minimum:

```markdown

Example 1: Simple Text Extraction

Input:

\\\`

document.pdf (invoice)

\\\`

Output:

\\\`json

{

"invoice_number": "INV-001",

"amount": "$100.00",

"date": "2024-01-01"

}

\\\`

Example 2: Table Extraction

Input:

\\\`

spreadsheet.pdf (financial data)

\\\`

Output:

\\\`json

[

{"month": "Jan", "revenue": 1000},

{"month": "Feb", "revenue": 1200}

]

\\\`

```

Template Patterns

When output format matters:

```markdown

\\\`json

{

"field1": "value", // Required

"field2": 123, // Optional, number

"field3": ["array"], // Optional, array of strings

"metadata": { // Required

"timestamp": "ISO8601",

"version": "1.0"

}

}

\\\`

```

Validation Steps

```markdown

After extraction:

• [ ] All required fields present
• [ ] Data types correct
• [ ] Values within expected ranges
• [ ] No parsing errors in logs

```

Key anti-patterns to watch for:

• ❌ Offering too many options (pick ONE default approach)
• ❌ Vague descriptions (be specific about what skill does)
• ❌ Deeply nested references (max one level: Skill.md → REFERENCE.md)
• ❌ Inconsistent terminology (choose one term per concept)
• ❌ First/second person (use third person in descriptions)
• ❌ Too much context (Claude knows programming basics)
• ❌ Missing "When NOT to Use" section
• ❌ No concrete examples (need 2-3 minimum)
• ❌ Placeholder values in examples (use realistic values)

See REFERENCE.md Section 1 for detailed anti-patterns with examples.

Best practices for code in skills:

• ✅ Explicit error handling (catch specific exceptions)
• ✅ Configuration comments explain WHY, not WHAT
• ✅ Forward slashes in all paths (cross-platform)
• ✅ Input validation (fail fast with clear errors)
• ✅ Resource cleanup (use context managers)

See REFERENCE.md Section 2 for detailed code guidance with examples.

Required testing before releasing a skill:

• ✅ Create 3+ evaluation scenarios first (test-driven approach)
• ✅ Test across models (Haiku, Sonnet, Opus)
• ✅ Fresh instance testing (no prior context)
• ✅ Baseline comparison (prove skill adds value)
• ✅ Real-world validation (actual user tasks)
• ✅ Continuous improvement (iterate based on usage)

See REFERENCE.md Section 3 for comprehensive testing guidelines.

Before sharing a skill, verify:

Core Quality

• [ ] Description includes specific key terms and usage triggers
• [ ] Description written in third person
• [ ] SKILL.md body under 500 lines
• [ ] Additional details in separate reference files
• [ ] Reference files one level deep from SKILL.md
• [ ] Consistent terminology throughout
• [ ] Concrete examples provided (2-3 minimum)
• [ ] Clear workflow steps with verification points

Naming & Structure

• [ ] Name uses gerund form (verb + -ing)
• [ ] Name max 64 characters, lowercase-with-hyphens
• [ ] Directory named correctly (matches skill name)
• [ ] Skill.md with capital S
• [ ] YAML frontmatter complete (name, description, version)

Content Quality

• [ ] Only includes info Claude doesn't already know
• [ ] Progressive disclosure pattern used
• [ ] One default approach (not too many options)
• [ ] No time-sensitive information
• [ ] No deeply nested references
• [ ] No vague confidence language

Code Quality (if applicable)

• [ ] Scripts handle errors explicitly
• [ ] All constants justified in comments
• [ ] Required packages listed and verified available
• [ ] Validation steps for critical operations
• [ ] Forward slashes in all file paths

Testing

• [ ] At least 3 evaluations created
• [ ] Tested with Haiku, Sonnet, and Opus
• [ ] Real-world usage scenarios validated
• [ ] Fresh instance testing completed
• [ ] Team feedback incorporated

• [Official Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
• [Skill Template](TEMPLATE.md)
• [Example Skills](EXAMPLES.md)
• [Claude Documentation](https://platform.claude.com/docs)

```bash

# Create new skill

mkdir -p ~/.claude/skills/my-skill-name

cd ~/.claude/skills/my-skill-name

# Copy template

cp ~/.claude/skills/skill-writing/TEMPLATE.md ./Skill.md

# Edit frontmatter and content

# Test with fresh Claude instance

# Iterate based on usage

```