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.