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.

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.

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.

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"

"Does every line in this skill improve Claude's behavior?"

If any line is decorative, inspirational, or redundant - cut it.