Skill Writing

Quick Start

Every skill needs a SKILL.md file with YAML frontmatter and markdown body:

---
name: Task Name (gerund form preferred)
description: What it does and when to use it (third person, specific)
---

# Task Name

[Concise instructions here]

Core Workflow

Copy and track your progress:

Skill Creation:
- [ ] Step 1: Identify the reusable pattern
- [ ] Step 2: Draft concise instructions
- [ ] Step 3: Add metadata (name, description)
- [ ] Step 4: Test with target model(s)
- [ ] Step 5: Iterate based on usage

Step 1: Identify the reusable pattern

What context do you repeatedly provide? What procedural knowledge is needed?

Step 2: Draft concise instructions

Start minimal. Claude is already smart - only add what Claude doesn't know.

Challenge each piece of information:

• Does Claude really need this explanation?
• Can I assume Claude knows this?
• Does this paragraph justify its token cost?

Step 3: Add metadata

Write description in third person, including:

• What the skill does
• When to use it (key terms and triggers)

description: Extract text from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Step 4: Test with target model(s)

• Haiku: Does it provide enough guidance?
• Sonnet: Is it clear and efficient?
• Opus: Does it avoid over-explaining?

Step 5: Iterate based on usage

Observe how Claude uses the skill. Watch for:

• Unexpected exploration paths
• Missed connections
• Overreliance on certain sections
• Ignored content

Set Appropriate Degrees of Freedom

Match specificity to task fragility:

High freedom (text instructions): Multiple approaches valid, context-dependent Medium freedom (pseudocode/templates): Preferred pattern exists, variation acceptable Low freedom (exact scripts): Operations fragile, consistency critical

Progressive Disclosure

Keep SKILL.md body under 500 lines. Split into separate files:

# SKILL.md

## Quick start
[Basic usage here]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Important:

• Keep references one level deep from SKILL.md
• Use forward slashes in paths (not backslashes)
• Add table of contents for files >100 lines

Common Patterns

Workflow pattern (complex tasks):

## Workflow
Copy this checklist:
- [ ] Step 1: Do first thing
- [ ] Step 2: Do second thing
[Detailed steps below]

Feedback loop (quality-critical):

1. Create output
2. Validate: `python scripts/validate.py`
3. If validation fails, fix and repeat
4. Only proceed when validation passes

Template pattern (consistent output):

ALWAYS use this exact structure:
[Template here]

Anti-Patterns to Avoid

❌ Windows-style paths (scripts\\helper.py) ✓ Unix-style paths (scripts/helper.py)

❌ Too many options ("You can use X, or Y, or Z...") ✓ Provide default with escape hatch ("Use X. For special case, use Y instead.")

❌ Time-sensitive info ("Before August 2025...") ✓ Use "Current method" and "Old patterns" sections

❌ Inconsistent terminology (mix "field", "box", "element") ✓ Choose one term, use consistently

❌ Deeply nested references (SKILL.md → advanced.md → details.md) ✓ One level deep (SKILL.md → details.md)

For Skills with Code

Utility scripts: Provide pre-made scripts rather than having Claude write them

• More reliable than generated code
• Save tokens and time
• Ensure consistency

Package dependencies: List required packages and verify availability

Visual analysis: Convert to images for Claude to analyze layouts

Verifiable outputs: Create plan files that get validated before execution

Quick Reference

Naming: Use gerund form ("Processing PDFs", "Analyzing Data")

Description: Third person, specific, includes when to use

File limit: Keep SKILL.md under 500 lines

Structure: YAML frontmatter + markdown body

Testing: Test with all target models

Conciseness: Assume Claude is smart, only add what's needed

Detailed Reference

For comprehensive guidance, see specs/skills-best-practices.md:

• Complete examples for all patterns
• Advanced progressive disclosure techniques
• Evaluation-driven development
• Runtime environment details
• MCP tool references