skill checklist Shipped
What this lens looks for
Read a Claude Code skill across three lenses. Structure and format: file opens and closes with --- YAML frontmatter; name field present, lowercase kebab-case matching ^[a-z][a-z0-9-]{0,63}$ and ≤64 chars; description present with natural trigger keywords a user would say (not too vague like "does stuff", not too narrow like "only for X on Tuesdays"); SKILL.md ≤500 lines; supporting non-SKILL.md files live in subdirectories (references/, scripts/, examples/) rather than loose at the skill root; SKILL.md references its supporting files (mentions them or loads via ${CLAUDE_SKILL_DIR}) when references/ exists; directory basename matches the frontmatter name; argument-hint present when SKILL.md uses $ARGUMENTS or $1/$2; skill located in .claude/skills/ or ~/.claude/skills/; only recognized frontmatter fields appear (name, description, argument-hint, disable-model-invocation, user-invocable, allowed-tools, model, effort, context, agent, hooks, paths, shell); main file named exactly SKILL.md (uppercase stem, not skill.md or Skill.md); supporting files use lowercase descriptive names matching ^[a-z][a-z0-9-]*(\.[a-z]+)+$ that describe content (not doc1.md). Content quality: single responsibility, one clear purpose not a grab-bag; task skills carry step-by-step numbered instructions or a clear workflow; reference vs task content appropriate (reference skills avoid imperative "do X" steps, task skills aren't pure documentation); error handling addressed (tool failures, missing files, bad input); $ARGUMENTS used when the description implies the skill takes input; ${CLAUDE_SKILL_DIR} used for own-file references rather than hardcoded paths; instructions concrete and actionable, not vague directives; no self-contradiction; well-structured markdown with headings/lists/code blocks; no large content duplicated between SKILL.md and reference files. Best practices: a verification method provided (run tests, check output, verify file exists); does not replicate native Claude capabilities; disable-model-invocation: true for side-effect skills that deploy/commit/send/modify external state; context: fork considered for isolated heavy-read/fetch task skills that return a result; examples or usage patterns included; no kitchen-sink anti-pattern (stays focused); no infinite-exploration anti-pattern (task skills scope their investigation, don't read unbounded files); not a CLAUDE.md dump of project rules; allowed-tools set when tool restriction is needed; model: override matches complexity (no opus for trivial tasks); dynamic context injection via ` !command ` is safe, fast, and deterministic; description concise (under ~200 chars) for the context budget.
What its verifier checks
Frontmatter opens and closes with ---; name present and matching ^[a-z][a-z0-9-]{0,63}$ (≤64 chars); description present with natural trigger keywords; SKILL.md is ≤500 lines; supporting files sit in subdirectories, not loose at root; SKILL.md references its supporting files when references/ exists; directory name matches the name field; argument-hint is present when $ARGUMENTS/$1/$2 are used; skill is located in .claude/skills/ or ~/.claude/skills/; only recognized frontmatter fields are used; the main file is named exactly SKILL.md; supporting files use lowercase descriptive names; the skill has a single clear responsibility; task skills have step-by-step instructions and reference/task content is appropriate; error handling is addressed; $ARGUMENTS is used when input is implied; own-file references use ${CLAUDE_SKILL_DIR} not hardcoded paths; instructions are concrete and actionable; no conflicting instructions; markdown is well-structured; no large content is duplicated with reference files; a verification method is provided; native capabilities are not re-taught; disable-model-invocation: true is set for side-effect skills; context: fork is considered for isolated task skills; examples or usage patterns are present; no kitchen-sink scope and no unbounded exploration; content is not a CLAUDE.md dump; allowed-tools is set when restriction is needed; any model: override fits the complexity; any ` !command ` injection is safe/fast/deterministic; description is under ~200 chars.