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

Writing Guidelines

• Imperative tone: "Run the build" not "You should run the build"

• Action-oriented: What to do, not what things are

• Progressive detail: Overview → Reference → Implementation

• 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:

• Extract detailed sections to references/

• Keep only overview in SKILL.md

• Add navigation table to references

• Test cold start (should load <500 lines)

References

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

Metrics

After creating/refactoring a skill:

• Entry point: <200 lines ✓

• Each reference: 200-300 lines ✓

• Cold start load: <500 lines ✓

• Relevant info ratio: >80% ✓