Skill Author — Authoring & Evaluation Guide

Create high-quality Claude Code skills that are concise, actionable, and load only what the model needs at invocation time.

Valid Frontmatter Fields

Field	Description
`name`	Kebab-case skill identifier (required)
`description`	One-line summary; shown in skill listings (required)
`argument-hint`	Placeholder shown to user, e.g. `[branch-name]`
`allowed-tools`	Restrict which tools the skill may use
`user-invocable`	Whether user can trigger via `/name` (default: true)
`disable-model-invocation`	Prevent model from auto-invoking (default: false)
`model`	Pin to a specific model tier
`context`	Additional files/globs to load with the skill
`agent`	Agent configuration for the skill
`hooks`	Shell commands triggered by skill lifecycle events

SKILL.md Sizing Rules

•Target: 80–120 lines
•Ceiling: 500 lines (hard max for any SKILL.md)
•Overflow strategy: Extract to references/ and link from SKILL.md
•Every line should earn its place — if removing a line wouldn't change model behavior, cut it

What Belongs in SKILL.md

• Purpose summary (2-3 lines)
• When-to-use decision aid (table or short list)
• Core workflow / essential commands (compact form)
• Session start and end protocols (if applicable)
• Links to reference files for details

What to Move to References

These are valuable but don't need to load on every invocation:

•Full command catalogs with exhaustive flag documentation
•Concrete worked examples and walkthroughs
•Integration guides for optional companion tools
•Error recovery and troubleshooting tables
•Rigid output format contracts or templates
•Migration guides and version-specific notes

What to Cut Entirely

Claude already knows these things — including them wastes context:

•Git conventions — commit message formats, branching strategies, .gitignore patterns
•Priority/severity definitions — P0-P3 scales, standard triage definitions
•Basic tool usage — how to run git, npm, cargo, etc.
•Verbose examples of simple concepts — if one example suffices, don't add three
•Installation/setup instructions — unless the tool is obscure or has non-obvious steps
•Marketing copy — "This revolutionary skill will transform your workflow..."
•Motivation/persuasion — The model doesn't need to be convinced to follow instructions

Evaluation Checklist

When reviewing a skill, verify each item:

•Line count — Is SKILL.md within 80-120 lines? Under 500 ceiling?
•Frontmatter — Uses only official fields listed above? Has name and description?
•No redundant knowledge — Nothing Claude already knows (git basics, priority scales)?
•Decision aid present — Can the model decide when to use vs. skip this skill?
•References extracted — Detailed content in references/, not inline?
•Actionable — Every section changes model behavior; no filler or decoration?
•Single-purpose — Skill does one thing well; not a grab-bag of loosely related guidance?
•No over-prescribed formats — Output formats are flexible unless a strict contract is essential?

Recommended Directory Structure

code

skills/<skill-name>/
  SKILL.md              # Core instructions (80-120 lines)
  references/           # Detailed supplementary material
    <topic>.md          # One file per topic, linked from SKILL.md

Reference Files

For detailed evaluation criteria, anti-patterns, and the section triage table, see:

•references/evaluation-guide.md — Deep-dive on what to keep, move, or cut