# Skill Repair > This skill should be used when the user asks to "repair a skill", "audit a skill", "fix my skill", "improve an existing skill", "review skill quality", "check if my skill is well-written", "diagnose skill problems", "what's wrong with this skill", "improve this skill", "what's wrong with this SKILL.md", or asks what can be improved about an existing skill. - Skill: `tools-only/skill-repair` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds add tools-only/skill-repair` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/skill-repair/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/tools-only/skill-repair --- # Skill Repair Audit and improve an existing skill against a gold standard. Unlike skill-creator (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 both reference files before Phase 2:** 1. `${CLAUDE_PLUGIN_ROOT}/skills/skill-repair/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/skill-repair/references/frontmatter-options.md` — complete frontmatter field catalog, valid values, tool list, tool selection framework. Required for Dimensions 1 and 2. Proceed to Phase 2 when: SKILL.md is read, sibling directories are cataloged, and both 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.* --- ### 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:** - Is `model: opus` set for a task that `sonnet` would handle? Overuse wastes cost. - 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. - Is `context: fork` set without `agent:`, or `agent:` set without `context: fork`? **Gaps:** - Does the skill do heavy analysis that would benefit from `model: opus`? - Does the skill produce heavy output that would pollute main context — missing `context: fork`? - 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? *Minor per instance.* --- ### 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/skill-repair/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. **Violations:** - **Prose that restates the section header** — "## Validation" followed by "In this section we will validate..." is pure redundancy. *Minor per instance.* - **Hedging language** — "you might want to consider", "it could be useful to", "generally speaking". Replace with direct imperatives or remove. *Minor per instance.* - **Code blocks illustrating a principle stateable in one sentence** — a good/bad YAML contrast often collapses to one intensional rule. *Major if pattern is frequent.* - **Repeated guidance across sections** — the same rule in a "Best Practices" section and a "Common Mistakes" section. Consolidate to one location. *Minor.* - **"When to Use This Skill" section in the body** — body loads only after triggering; routing guidance here is never read by the routing decision. Dead tokens every invocation. *Major.* - **Headers deeper than H3** — signals content that belongs in `references/`. *Minor.* - **SKILL.md over ~500 lines** — requires `references/` deferral. *Major.* - **Extraneous documentation files** (`README.md`, `CHANGELOG.md`, `INSTALLATION.md`) in the skill directory — never loaded into context, add noise to the package. *Minor per file.* **Gaps:** - **Would a `references/` file reduce SKILL.md size?** Identify sections only needed for specific sub-tasks and flag them as deferral candidates. *Major if SKILL.md > 300 lines.* - **Would a `references/` file for domain-specific data help?** Lookup tables, option catalogs, field definitions — these are reference data, not instructions. *Major.* --- ### Dimension 6 — Workflow Clarity A skill's process should be sequential, complete, and have explicit exit conditions at each phase. Audit for broken workflow *and* for missing structure that would help. **Violations:** - Is the process structured as numbered phases with clear names? Without explicit phases the model can't track progress or know which step it's in. *Major if unstructured.* - Does each phase have an explicit exit condition? Without one, the model doesn't know when to stop iterating on a phase and may loop or skip prematurely. *Major if missing.* - Are there half-thought steps — phases that describe intent without specifying what to do or how to evaluate the result? *Major per uncovered phase.* - Does the skill handle missing, ambiguous, or malformed input? **Gaps:** - Is there a delivery phase that tells Claude what to produce and in what format? Many skills describe the process clearly but leave the output format implicit. *Major if absent.* - Would a validation checklist at the end of the workflow catch errors that prose instructions miss? *Minor.* - Would an `examples/` directory help users understand what the expected output looks like? *Minor.* --- ### Dimension 7 — Anatomy Completeness Refer to `skill-anatomy.md` for the gold standard directory anatomy and the Gap Analysis Checklist. This dimension asks: does the skill's structure match its complexity tier, and what is absent that would raise it? **Use the Gap Analysis Checklist from `skill-anatomy.md` directly.** For each "yes" answer, record a gap at the appropriate severity. **Violations:** - Does the skill have a `scripts/` directory with scripts not referenced in SKILL.md? *Major — referenced or delete.* - Does the skill have a `references/` directory with files not pointed to from SKILL.md? *Major — referenced or delete.* - Does the naming violate conventions (uppercase, underscores, over 64 chars)? *Minor.* **Gaps — ask for each absent directory:** - **Missing `scripts/`:** Is there a deterministic operation that would be more reliable scripted? Does the same code block appear or would it appear in multiple invocations? - **Missing `references/`:** Does SKILL.md exceed 300 lines? Are there sections only needed for specific sub-tasks? Is there domain-specific reference data? - **Missing `examples/`:** Does the skill produce output users adapt? Are there ambiguous instructions a working example would clarify better than prose? - **Missing resource pointers in SKILL.md:** Are there directories present but not referenced — invisible to Claude unless it guesses to look? --- ## Phase 3: Improvement Report Present findings as a structured report. Split violations from gaps — a violation is something wrong, a gap is something missing that would improve the skill. ``` SKILL IMPROVEMENT REPORT: Current tier: [simple / standard / complex] — [lines] lines, [directories present] VIOLATIONS ────────── CRITICAL [D1] Description uses first-person — routing model reads as instruction, not trigger. Fix: rewrite as "This skill should be used when the user asks to..." MAJOR [D3] Body teaches frontmatter quality by bad/good contrast; principle never stated. Fix: state the rule ("quoted phrases must be verbatim user speech because routing matches on literal tokens") then keep the contrast as confirmation. [D5] "When to Use This Skill" section in body — dead tokens every invocation. Fix: move routing guidance to frontmatter description, delete body section. MINOR [D1] Description uses | scalar instead of >. Fix: change to >. GAPS (what would improve this skill) ───────────────────────────────────── MAJOR [D7] SKILL.md is 420 lines with no references/ directory. Three sections (option catalog, field definitions, examples table) are only needed for specific sub-tasks. Improvement: extract to references/; add load pointer in SKILL.md for each. [D4] File-path validation logic is inlined but must produce consistent output. Improvement: move to scripts/validate-input.py; reference from Phase 2. MINOR [D2] Skill reads $1 as a file path but uses Read tool — @$1 injection would save a tool round-trip. Improvement: replace Read call with @$1 inline injection. [D7] No examples/ directory; skill produces config output users adapt. Improvement: add examples/ with one representative output file. ``` Group violations by severity, then gaps by severity. For each: dimension code, what is wrong or missing, the principle or gold standard it falls short of, the exact fix. Ask: "Apply all critical and major items? Or select specific ones?" --- ## Phase 4: Apply Improvements Apply confirmed items in order: critical violations → major violations → major gaps → minor violations → minor gaps. For each item: - State what is being changed or added and why (principle reference, not just "you asked") - Make the edit or create the file - Confirm the change is consistent with surrounding content ### Explain Your Choices After applying improvements, briefly explain: - **What was changed and why** — reference the principle: "Rewrote description as third-person because first-person framing is parsed as an instruction to execute, not a triggering condition to evaluate" - **What was added and why** — "Created references/options.md and deferred the option catalog because SKILL.md was 420 lines and the catalog is only needed for the configuration sub-task" - **What was left unchanged and why** — "Left `model` unset — workload doesn't justify overriding the default" - **What remains for the user to address** — "The examples/ gap requires domain knowledge to fill; a placeholder directory was created" Phase 4 is complete when all confirmed items are applied, the explanation is delivered, and the validation checklist passes. --- ## Validation After applying all improvements, load `${CLAUDE_PLUGIN_ROOT}/skills/skill-repair/references/quality-checklist.md` and run the quality standards check followed by the item-by-item validation checklist. Report any failing items before delivering final results.