gupsammy/claudest/repair-skill

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.

1. ${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.

1. ${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 uses? Dead entries add noise.

Gaps:

• Does the skill invoke other skills or spawn agents without Skill or Task in allowed-tools?
• Does the skill require user decisions mid-workflow but lacks AskUserQuestion in allowed-tools?
• Does the skill read a file path from $1 but uses a Read tool call instead of @$1

inline injection? A tool round-trip is being wasted. Minor.

• Could real-time data (git status, env vars, file tree) be injected using dynamic content

syntax (bang + backtick-wrapped command) instead of a tool call? Major when the skill's workflow begins with infallible probes (git branch, file tree, env vars) that never need error handling; Minor for commands that may fail or need exit-code branching.

Before (wastes tool round-trips): ```

1. Run git log --oneline -5 using Bash
2. Run git diff --name-only using Bash
3. Analyze the results...

``` After (injected at invocation, zero tool calls). Replace those Bash calls with:

• Recent commits: !\git log --oneline -5\
• Changed files: !\git diff --name-only\

Then continue with prose like "Analyze the results..."

> Note: The backslashes escape the backticks so this documentation > doesn't execute — in a real skill, write !\cmd\ without the backslashes.

Dimension 3 — Intensional vs Extensional Instruction

A rule stated with its reasoning generalizes to every input. An example that implies a rule requires the reading model to reverse-engineer the rule — two reasoning hops instead of one, covering only the shape of that example.

Violations:

• Does it show a good/bad contrast and leave the principle implicit? The principle should

be stated first; the contrast confirms it, not carries it.

• Is a "Common Mistakes" or "Bad/Good examples" section doing the work that a single

principle sentence could do more efficiently? Major.

• Would removing the examples leave the rule intact and still actionable? If yes, the

examples are redundant. If no, the rule hasn't been stated yet — state it.

Gaps:

• Are there instruction blocks that tell Claude what to do but not why? Adding the

reasoning makes the instruction generalize to edge cases not covered by the current examples. Major per uncovered block.

Dimension 4 — Agentic vs Deterministic Split

Load `${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md` before auditing this dimension. It contains the five signal patterns for recognizing a script candidate, CLI design conventions, common archetypes (init, validate, transform, package, query), and the delegation pattern for using create-cli to design the interface.

Skills mix LLM-guided reasoning (agentic) and script execution (deterministic). The split should be deliberate — see the Degrees of Freedom table in skill-anatomy.md.

Violations:

• Code blocks that are repeated or identical across invocations — these are

deterministic operations being re-generated each time. They belong in scripts/. Inlining costs context tokens on every run; scripts execute without being loaded.

• Prose that describes a deterministic sequence — if the steps are always the same

regardless of input, a script is more reliable than asking the model to reproduce them.

• Scripts that exist but aren't referenced in SKILL.md — Claude won't use them.

A script without a reference in SKILL.md specifying when and how to invoke it is invisible to the skill workflow. Major.

• Vague script references — "run the validation script if needed" is not actionable.

References must state the trigger condition, the exact invocation, and how to interpret the output. Minor.

Gaps — apply the five signal patterns from `script-patterns.md` to each workflow step:

• Signal 1 (Repeated Generation): Does any step produce the same structure with

different parameters across invocations? → Parameterized script candidate. Major.

• Signal 2 (Unclear Tool Choice): Does any step require combining multiple standard

tools in a fragile sequence to accomplish something naturally expressible as a single function? → Script the procedure. Major.

• Signal 3 (Rigid Contract): Does any step have an input/output shape clear enough

to write --help text for right now? → CLI candidate; delegate design to create-cli.

• Signal 4 (Dual-Use Potential): Would any step be useful to run independently from

the terminal, outside the skill workflow? → Design as proper CLI from the start.

• Signal 5 (Consistency Critical): Does any step need to produce identical output

for identical inputs — not "similar" but reproducible? → Script, not LLM generation.

• Judgment steps with no criteria — "analyze the situation" is agentic but unanchored.

Agentic steps need explicit criteria for what to consider and what constitutes a good outcome. Major per uncovered step.

Dimension 5 — Verbosity and Context Efficiency

Every token in SKILL.md is loaded into context when the skill triggers. Audit for tokens that consume budget without improving outcomes, and for content that belongs in references/ instead.

Refer to the size invariants table in skill-anatomy.md to calibrate severity.