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.