Add Skill

add-skill

Builds one production-quality skill in skills/<name>/, eval-first, in whatever repository you are currently in. Read references/skill-authoring.md and references/evals.md once per session before starting — they are the rulebook this workflow enforces (repos scaffolded by create-skill-repo also carry them as docs/). If invoked as /add-skill <args>, treat $ARGUMENTS as the skill name or idea to scope in step 1.

When NOT to use

• Creating a new skills repository → create-skill-repo.
• Turning a research pack into one or more skills → skill-from-research (it drives this workflow per skill after distilling the pack).
• Infrastructure work (hooks, CI, validators) → plain editing, PR-level scrutiny.
• A "skill" that merely restates what the model already does well → don't build it; a skill must fix a specific observed failure.

Workflow

1. Scope, and pick the invocation mode. State in one sentence what the skill does and the concrete failure it fixes. If the sentence needs "and", split into multiple skills, one at a time. Check the repo's existing skill catalog for overlap — near-neighbor descriptions steal each other's triggers; plan disjoint wording. Then decide who invokes it, because it changes the name, the description, and the eval set: model-invoked (default — the router picks it from the user's words) or user-invoked (disable-model-invocation: true — the user types /name; correct for side-effecting skills and for anything whose value is a memorable command). When one capability wants both, use the alias-over-engine split in references/skill-authoring.md rather than compromising one for the other.
2. Gather. Read the repo's .local/ recursively if present (research, examples, constraints — never cite .local/ paths from a skill). Research beyond it: web-search for current facts, official docs, and prior art; verify anything load-bearing against primary sources. Verified facts the skill depends on go into skills/<name>/references/ as cleaned, committed files.
3. Evals first. Create skills/<name>/evals/evals.json per references/evals.md: ≥8 should_trigger (vary formality, typos, terseness), ≥8 should_not_trigger (near-misses sharing keywords), 3–5 quality cases with plain-language expected_behavior assertions. If you can't write these, the scope is unclear — back to step 1. For a user-invoked skill both trigger counts are waived — no router weighs its description — so write the quality cases only.
4. Draft SKILL.md. Frontmatter: name == folder name; description on a single line, third person. Model-invoked: [what] + [use when …] + [not for …], 150–400 chars, trigger keywords in the first ~120. User-invoked: one verb-first line that reads well in a / menu — trigger phrasings and exclusions are dead weight there. Body per references/skill-authoring.md: purpose → when/when-not → numbered workflow → output spec → gotchas → pointers. Under 500 lines; deterministic steps as scripts/ (non-zero exit on failure); long material as references/ with a TOC. Reference bundled files via ${CLAUDE_SKILL_DIR} so installed copies work.
5. Validate. If the repo has a validator (make check / scripts/validate_skills.py), it must exit 0 — fix every error, triage every warning. If it has none, self-check against the frontmatter rules in the authoring reference (single-line description, name==folder, length bounds). Where scripts/run_evals.py exists (make evals), it must also pass: it scores each trigger prompt against every sibling description and fails on no-overlap prompts, a sibling outranking the skill, or a near-duplicate description. Fix the description it points at — never the evals.
6. Trigger self-test. For ≥3 should-trigger and ≥2 should-not-trigger prompts, reason explicitly: would the description alone route this prompt here against every other installed skill? Fix the description, not the evals. (Skip for user-invoked skills — nothing routes them.)
7. Measure. Scan the available-skills list for Anthropic's official skill-creator (typically skill-creator:skill-creator; the plugin-qualified name varies by marketplace — match on name/description, don't hardcode). If present, invoke it as a subskill via the Skill tool, scoped to measure only: it runs each quality case as with-skill vs baseline subagents, grades assertions, and benchmarks pass rate / time / tokens. Hand it cases from evals/evals.json translated per "Automated harness" in references/evals.md, and follow that section's guardrails (workspace-only writes, cases-run check, description acceptance gate). If it's absent, run the manual protocol instead and say so — it certifies triggering only, not quality uplift; never let a skipped Measure pass silently as "measured".
8. Register. Update the repo's README catalog, CHANGELOG.md, and skills.sh.json grouping when those exist (schema shape: "groupings": [{"title": ..., "description": ..., "skills": [...]}] — not groups/name; skills.sh silently ignores a non-conforming file). Re-check sibling descriptions for new overlap.

Output spec (Definition of Done)

• skills/<name>/ with SKILL.md + evals/evals.json (+ scripts/references as needed)
• Repo validator green (or the self-check documented when no validator exists)
• Measured: official skill-creator benchmark when installed, else the manual protocol from references/evals.md — state which ran (the fallback certifies triggering only)
• Catalog/CHANGELOG/groupings updated where present
• A 3-line summary: purpose, trigger phrase examples, known limitations

Gotchas

• Keep description on ONE physical line — multi-line values have failed to load in some runtimes; never work around a repo's validator.
• Don't paste failed eval prompts verbatim into the description (overfitting); generalize the missing verb/noun instead.
• Over-triggering fix = add targeted "Not for …" noun phrases from the actual false-positive overlap; don't delete positive triggers.
• Model upgrades shift routing — note that evals should be re-run after the next model release.

Files

• references/skill-authoring.md — anatomy, frontmatter rules, description formula, body structure, gotchas, anti-patterns.
• references/evals.md — evals.json format and the trigger/quality protocol.