Skill Creator

Create effective agent skills using progressive disclosure. Skills are workflow capabilities, not documentation dumps. The goal is loading the right information at the right time.

Core Principle

Skills ≠ Documentation

• devops isn’t “Cloudflare docs” → it’s the ability to deploy infrastructure
• ui-styling isn’t “Tailwind docs” → it’s the ability to design interfaces
• Each skill teaches how to perform a task, not what a tool does

3-Tier Architecture

Tier 1: Metadata (always loaded)
├── YAML frontmatter only (~100 words)
└── Enough for Claude to decide relevance

Tier 2: SKILL.md entry point (loaded on activation)
├── ~200 lines MAX
├── Overview, quick start, navigation
└── Points to references (doesn't include them)

Tier 3: references/ (loaded on-demand)
├── 200-300 lines each
├── Detailed documentation
└── Focused on single topics

The 200-Line Rule

Entry point MUST be under 200 lines. This enables:

• Fast relevance scanning
• Quick reference selection
• 400-700 lines of relevant context vs 1,000+ of mixed relevance

If you can’t fit core instructions in 200 lines, you’re putting too much in the entry point.

Skill Structure

skills/my-skill/
├── SKILL.md              # Entry point (<200 lines)
├── references/           # Detailed content
│   ├── guide-a.md        # 200-300 lines each
│   ├── guide-b.md
│   └── examples.md
├── scripts/              # Optional executable code
└── assets/               # Optional templates

SKILL.md Template

---
name: skill-name
description: One-line description. When to use this skill.
tools: Read, Write, Edit, Bash  # Optional
model: opus                      # Optional
---

# Skill Name

Brief description (2-3 sentences max).

## Quick Start

\`\`\`bash
# Essential commands only
\`\`\`

## Workflow

### 1. First Step
- Key points only
- No lengthy explanations

### 2. Second Step
- Action-oriented
- Link to references for details

## References

| Reference | Purpose |
|-----------|---------|
| `references/detailed-guide.md` | Full implementation details |
| `references/examples.md` | Code examples |

Writing Guidelines

1. Imperative tone: “Run the build” not “You should run the build”
2. Action-oriented: What to do, not what things are
3. Progressive detail: Overview → Reference → Implementation
4. No redundancy: Say it once, in the right place

When to Create vs Reference

Create a skill when:

• Task requires specific workflow knowledge
• Multiple steps with decision points
• Reusable across projects

Use references when:

• Detailed implementation specifics
• Code examples
• Edge cases and troubleshooting

Refactoring Bloated Skills

Signs you need to refactor:

• SKILL.md over 200 lines
• Loading 5+ skills causes context issues
• 90% of loaded content isn’t used

Process:

1. Extract detailed sections to references/
2. Keep only overview in SKILL.md
3. Add navigation table to references
4. Test cold start (should load <500 lines)

References

Metrics

After creating/refactoring a skill:

• Entry point: <200 lines ✓
• Each reference: 200-300 lines ✓
• Cold start load: <500 lines ✓
• Relevant info ratio: >80% ✓