skill-creator

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

```

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

```

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.

```

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

```

```markdown

---

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).

\\\`bash

# Essential commands only

\\\`

1. First Step

• Key points only
• No lengthy explanations

2. Second Step

• Action-oriented
• Link to references for details

| Reference | Purpose |

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

| references/detailed-guide.md | Full implementation details |

| references/examples.md | Code examples |

```

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

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

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)

| Reference | Purpose |

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

| references/architecture.md | 3-tier system deep dive |

| references/frontmatter.md | YAML frontmatter spec |

| references/writing-guide.md | Content writing best practices |

| references/refactoring.md | How to split bloated skills |

| references/anti-patterns.md | What NOT to do |

| references/examples.md | Complete skill examples |

After creating/refactoring a skill:

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