skill-design-philosophy
Original：🇺🇸 English
Translated
Core philosophy for designing Claude Code skills - when to use skills vs agents, the knowledge test, and what makes skills valuable. Use when deciding component type or evaluating skill quality.
1installs
Added on
NPX Install
npx skill4agent add majesticlabs-dev/majestic-marketplace skill-design-philosophyTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →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 |
|---|---|
| Coding style guidance - patterns Claude applies when writing code |
| Methodology knowledge - steps Claude follows for test-driven development |
| Framework patterns - conventions Claude uses for Stimulus controllers |
| 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.