Skill Design Philosophy
Skills provide knowledge and context, not autonomous execution.
The Knowledge Test
Ask: "Does this TEACH Claude or DO something?"
| TEACH (Skill) |
DO (Agent) |
| Coding conventions |
Run linters and fix code |
| Workflow methodology |
Execute multi-step processes |
| Framework patterns |
Generate reports |
| Tool usage guidance |
Fetch and analyze data |
Rule: If it produces artifacts without user guidance, it's probably an agent.
Good Skill Examples
| Skill |
Why It Works |
dhh-coder |
Coding style guidance - patterns Claude applies when writing code |
tdd-workflow |
Methodology knowledge - steps Claude follows for test-driven development |
stimulus-coder |
Framework patterns - conventions Claude uses for Stimulus controllers |
pdf-processing |
Tool knowledge - how to use specific libraries and scripts |
Pattern: Skills TEACH Claude patterns, conventions, and approaches.
Bad Skill Examples
| Skill |
Why It Fails |
| "Code reviewer" |
Does autonomous work - should be an agent |
| "Git helper" |
Vague scope - what specifically does it teach? |
| "Best practices" |
Too broad - not actionable |
| "Documentation generator" |
Creates artifacts - should be an agent |
Pattern: These skills DO things instead of TEACHING things.
Content Rules
| Include |
Exclude |
| Concrete patterns and conventions |
Persona statements ("You are an expert...") |
| Specific templates and examples |
Attribution ("Inspired by X...") |
| Decision criteria |
Decorative quotes |
| Error handling guidance |
ASCII art or box-drawing |
| Framework-specific idioms |
Vague "best practices" |
Quality Test
"Does every line in this skill improve Claude's behavior?"
If any line is decorative, inspirational, or redundant - cut it.
