SKILL.md

name: skill-design-philosophy description: 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.

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.

スコア

総合スコア

60/100

リポジトリの品質指標に基づく評価

✓SKILL.md

SKILL.mdファイルが含まれている

+20

✓LICENSE

ライセンスが設定されている

+10

○説明文

100文字以上の説明がある

0/10

○人気

GitHub Stars 100以上

0/15

○最近の活動

3ヶ月以内に更新がある

0/10

○フォーク

10回以上フォークされている

0/5

✓Issue管理

オープンIssueが50未満

+5

✓言語

プログラミング言語が設定されている

+5

○タグ

1つ以上のタグが設定されている

0/5

レビュー

💬

レビュー機能は近日公開予定です