Structure and document Claude Code skills

Structure and document reusable Claude Code skills

Teams and individuals building reusable workflows in Claude Code who need to document skills in a format that enables agent discovery and execution.

• · Task/domain the skill covers
• · Specific use cases
• · Whether executable scripts are needed
• · Reference materials or examples

• · skill-name/ folder with:
• · - SKILL.md (main instructions, required)
• · - REFERENCE.md (detailed docs if content > 500 lines)
• · - EXAMPLES.md (usage examples if needed)
• · - scripts/ subdirectory (utility scripts if deterministic operations needed)

• · Clear definition of skill scope (what it does, when to use it)
• · At least 1-2 use cases articulated
• · User approval before finalization

• · Description unclear (agent cannot decide when to trigger skill)
• · SKILL.md exceeds 100 lines (too complex to read in context)
• · No 'Use when...' triggers specified (agent treats skill as generic)
• · Includes time-sensitive information (outdated fast)
• · Script added when procedure is non-deterministic (waste of code)

• · Description includes 'Use when' triggers (agent can decide to load skill)
• · Max description length (1024 chars) enforced
• · SKILL.md split into separate REFERENCE.md if > 100 lines
• · Review checklist provided (8-item verification before publishing)
• · Scripts added only for deterministic operations (not guesswork)