/repair-skill

name: repair-skill
description: >
  This skill should be used when the user asks to "fix my skill" or "audit this skill".
  Make sure to use this skill whenever the user mentions skill quality, structural issues,
  broken skills, or skill diagnostics — even if they don't explicitly say "repair-skill".
  Not for adding features or improving effectiveness — use improve-skill. Not for agents
  — use repair-agent.
argument-hint: <path-to-skill-directory-or-SKILL.md>

Skill Repair

Audit and improve an existing skill against a gold standard. Unlike create-skill (which generates from scratch), this skill diagnoses violations *and* identifies gaps — what is broken, what is missing, and what would raise quality. The output is a structured improvement plan covering all dimensions.

Phase 1: Load the Skill

Read `$ARGUMENTS` as the path to a skill directory or SKILL.md file.

• If a directory: read `SKILL.md`, then list and note which of `references/`, `examples/`,

`scripts/`, `assets/` exist and which are referenced from SKILL.md

• If a file: read it directly, then discover sibling resource directories

If the path is missing or ambiguous, use AskUserQuestion to resolve before proceeding.

**Load all three reference files before Phase 2:**

1. `${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/skill-anatomy.md` — gold standard for correct anatomy, three-level loading model, directory type definitions, degrees of freedom, naming conventions, body conventions. Required for Dimensions 5, 6, and 7. 2. `${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/frontmatter-options.md` — complete frontmatter field catalog, valid values, tool list, tool selection framework. Required for Dimensions 1 and 2. 3. `${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/audit-calibration.md` — known false-positive patterns that look like violations but are not. Prevents over-flagging on D2 (allowed-tools absent), D4 (Task/Skill prose), and D5 (orientation vs routing).

Proceed to Phase 2 when: SKILL.md is read, sibling directories are cataloged, and all three reference files are loaded.

Phase 2: Audit

Run each dimension independently. For each finding record: the dimension code, what is wrong or missing, which principle it violates or which gold standard it falls short of, and the specific change required. Proceed to Phase 3 when all 7 dimensions are evaluated.

**Finding types:**

• **Violation** — something present that contradicts a rule
• **Gap** — something absent that would improve the skill against the gold standard
• **Improvement** — something that works but could be meaningfully tightened

**Severity:**

• **critical** — breaks triggering or wastes significant context on every invocation
• **major** — degrades generalization, reliability, or workflow correctness
• **minor** — polish; the skill works but isn't as good as it could be

---

Dimension 1 — Frontmatter Quality

The description is the only part of a skill that is always in context. Every token here costs budget across every session. Audit for violations *and* gaps:

**Violations:**

• **Person and framing:** Is the description third-person ("This skill should be used

when...")? First-person or imperative framing reads as an instruction to execute, not a triggering condition to evaluate. *Critical if wrong.*

• **Scalar type:** Does the description use `>` (folded scalar)? The `|` literal scalar

preserves newlines and can produce unexpected whitespace when parsed. *Minor.*

• **Trigger phrase authenticity:** Are quoted phrases verbatim user speech — the exact

tokens a user would type? Paraphrases ("hook creation tasks") have lower routing match rates than natural language ("create a hook"). *Major if paraphrased.*

• **Token density:** Does the description restate the skill name, explain what skills are,

or include meta-commentary? Every such token is budget waste. *Minor per instance, major if systemic.*

**Gaps:**

• **Trigger phrase coverage:** Are there 3–5+ varied phrases? Single-phrase descriptions

miss synonym space. Does coverage include the naive phrasing a user would use who has never heard of this skill? *Major if sparse.*

• **Missing `argument-hint`:** Does the skill read `$ARGUMENTS` or `$1`/$`$2` without an

`argument-hint` field? The hint is shown in autocomplete — its absence means users don't know what to pass. *Minor.*

• **Name validity:** Is the skill name lowercase, hyphens only, max 64 chars? Verb-led for

commands? Namespaced when it aids routing clarity? These constraints ensure filesystem compatibility, command-line ergonomics, and unambiguous routing. *Minor if wrong.*

• **Trigger accuracy:** Mentally generate 3 prompts that should trigger this skill and 3

that should NOT (from adjacent domains). Does the description cover the should-triggers and exclude the shouldn't-triggers? Sparse coverage or broad false-trigger surface is a routing quality gap. *Major if coverage is sparse.*

• **Token budget:** Is the description over 100 tokens? Per-session cost scales with

description length across all installed skills. Over 150 tokens is a violation (major); 100–150 is a gap (minor) — tighten by prioritizing trigger phrases over prose.

• **Negative triggers absent:** For skills in crowded domains (multiple skills with

overlapping concerns), does the description include explicit "Not for X" exclusions? Negative triggers sharpen the routing decision boundary. *Minor.*

---

Dimension 2 — Execution Modifiers

Modifiers left at their defaults are not errors — omitting them is correct when defaults apply. Audit for *mismatches* (violations) and *missing configuration* (gaps).

Refer to `frontmatter-options.md` for the complete field catalog, model selection table, and tool selection framework.

**Violations:**

• Does the skill have unrestricted `Bash` when a scoped pattern (`Bash(git:*)`) would work?
• Does the skill have tools in `allowed-tools` it never use