| name | skill-authoring |
| description | Enforces SKILL.md frontmatter and body conventions when a skill file (or command markdown file) is opened for authoring or review — description quality, user-invocable vs model-invocable choice, archetype fit, progressive disclosure, and the 500-line body cap. |
| user-invocable | false |
| paths | ["**/skills/**/SKILL.md","**/.claude/skills/**/SKILL.md","**/commands/*.md"] |
Skill authoring checklist
Apply this to the file you just opened, top to bottom. The two mistakes that break triggering most often: a description that summarizes the workflow instead of stating trigger conditions, and a paths: glob broad enough to auto-load on unrelated files.
Checklist
- Description is trigger-only, third person, "Use when...". If it narrates steps ("reads the diff, then writes a message, then runs tests"), Claude follows the description as a shortcut and skips the body. Rewrite to state only when the skill applies.
description alone stays under the 1,024-char platform hard cap; combined description + when_to_use stays under the 1,536-char listing cap. Lead with the strongest trigger phrase first — it's what gets matched.- Invocation field is deliberate, not defaulted. Pick one:
- Default (no field) — Claude auto-loads by description match; user can also
/invoke.
user-invocable: false — background/enforcement knowledge, no meaningful /name command. Use this for all five path-based skills in this family.disable-model-invocation: true — side-effecting actions (/deploy, /commit) the user must trigger deliberately; description is excluded from context.
- Archetype matches shape. See taxonomy below — a skill built as the wrong archetype fights its own frontmatter.
- Progressive disclosure enforced. Every
references/*.md pointer in the body is preceded by an explicit "Load when:" guard. No reference is inlined wholesale into SKILL.md.
- References are one level deep.
references/foo.md must not itself point to references/foo/bar.md. Flatten instead.
- Body stays under 500 lines. Over that, split into references and leave SKILL.md as the index.
paths: glob is as narrow as the file shape actually is. **/*.md is almost always wrong — say what kind of markdown file.allowed-tools (if set) lists only what the skill's body actually invokes, scoped (Bash(git *)), never a bare Bash.
House archetype taxonomy
Every skill in this plugin family is one of four shapes. Naming a skill's archetype up front resolves most frontmatter arguments:
| Archetype | Shape | Invocation | Example in this repo |
|---|
| Context | SKILL.md index + references/ deep dives, no execution | user-invocable: false typically; description carries the index's own trigger | anthropic-docs |
| Workflow | User-invoked with arguments:/argument-hint:, orchestrates a multi-step procedure | disable-model-invocation: true for side-effecting workflows | out of scope this phase |
| Pattern | Ships scripts/helpers under scripts/ that do a concrete thing | default or user-invocable: false depending on whether Claude should decide to run it | planned (nudge design, bash templates) |
| Path-based | paths: glob, auto-loads as an enforcer the moment a matching file is opened, no execution of its own | always user-invocable: false | this skill, and its four siblings |
A context skill that also declares paths: is doing double duty — fine, but be sure the description alone is strong enough for description-triggered loads too, since the two mechanisms compose rather than replace each other.
Common mistakes
- Description recapping the body — becomes the shortcut Claude takes instead of reading further.
paths: set on a skill that should be description-triggered (task-kind-specific, not file-shape-specific) — it'll never fire when no matching file is open.- Inlining a reference's field table into SKILL.md "for convenience" — duplicated content drifts out of sync with the reference; point instead.
- Missing
argument-hint on a user-invokable workflow skill that takes arguments.
user-invocable: false skill that still declares argument-hint — dead field, users can't invoke it.
Read for the full contract
${CLAUDE_PLUGIN_ROOT}/skills/anthropic-docs/references/skills.md — every frontmatter field, invocation matrix, substitution variables, lifecycle.${CLAUDE_PLUGIN_ROOT}/skills/anthropic-docs/references/skill-best-practices.md — conciseness, degrees of freedom, naming, description rules, progressive-disclosure patterns, eval-first iteration, the pre-share checklist.
Reviewing whether the body's language will actually land — imperative force, urgency tiers, XML structure? Invoke the persuasion skill.
