/repair-agent

name: repair-agent
description: >
  This skill should be used when the user asks to "repair an agent", "audit an agent",
  "fix my agent", "review agent quality", "check if my agent is well-written", "diagnose
  agent problems", "what's wrong with this agent", "improve this agent", or "what's wrong
  with this agent file". Not for skills — use repair-skill.
argument-hint: "<path-to-agent-file>"

Agent Repair

Audit and improve an existing Claude Code agent against a gold standard. Unlike create-agent (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 of agent design.

Phase 1: Load the Agent

The agent file at `$ARGUMENTS` is loaded inline:

@$ARGUMENTS

Note the directory from `$ARGUMENTS` to verify it lives in `agents/` (not `skills/`). Identify any `skills:` preloads listed in the frontmatter above.

If the file is a `SKILL.md` or lives in a `skills/` directory, decline and tell the user to use `repair-skill` instead. If the path is missing or ambiguous, use AskUserQuestion to resolve before proceeding.

**Load the following reference files before Phase 2:**

1. `${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md` — gold standard for system prompt structure, voice conventions, size invariants, naming, `skills:` preload pattern, and the gap analysis checklist. Required for Dimensions 3, 5, 6, and 7. 2. `${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md` — complete frontmatter field catalog, valid values, tool selection framework, color semantics, and execution modifiers. Required for Dimensions 1 and 2.

Proceed to Phase 2 when: agent file is confirmed in scope and 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 agent against the gold standard
• **Improvement** — something that works but could be meaningfully tightened

**Severity:**

• **critical** — breaks triggering or causes the agent to malfunction on every invocation
• **major** — degrades trigger accuracy, system prompt reliability, or autonomy safety
• **minor** — polish; the agent works but isn't as good as it could be

---

Dimension 1 — Description Quality

The description is read by the routing model to decide when to spawn this agent. It is the primary trigger mechanism and is always in context. Audit for violations *and* gaps.

**Violations:**

• **Framing:** Does it start with "Use this agent when..."? *Critical if wrong.*
• **Bloated description:** Description should be a concise `>` folded scalar, 50-70 tokens.

No `<example>` blocks — they waste context without improving routing. *Major if examples present or description exceeds ~80 tokens.*

• **Scalar type:** Should use `>` (folded). *Minor if using `|` without XML blocks.*
• **Proactive hint missing:** For agents that fire after events, does the description include

"Recommended PROACTIVELY after..."? *Minor if proactive intent without the hint.*

**Gaps:**

• **Negative trigger:** If adjacent agents exist with overlapping scope, does the description

state when NOT to trigger? *Minor if adjacent agent exists without disambiguation.*

---

Dimension 2 — Frontmatter Modifiers

Refer to `agent-frontmatter.md` for the complete field catalog, tool selection framework, and color semantics. Omitting a field is not an error when the default applies — audit for *mismatches* (violations) and *missing configuration that would improve the agent* (gaps).

**Violations:**

• Does `tools` include unscoped `Bash` for an agent that doesn't need full shell access?

Agents run autonomously with no human in the loop — unrestricted Bash is the highest blast-radius grant. *Major.*

• Is `model: opus` set for a task sonnet handles? Cost scales directly per spawn. *Major.*
• Is `isolation: worktree` set without the agent performing git-state modifications?

Unnecessary isolation adds overhead. *Minor.*

• Does `disallowedTools` block a tool the system prompt requires? *Critical.*

**Gaps:**

• Is `color` absent? Visual identity in the UI helps users track which agent is active

in multi-agent workflows. *Minor.*

• Is `tools` absent for a read-only analysis agent? Least-privilege requires an explicit

allowlist for autonomous agents — omitting it grants full access when restricted access would suffice. *Major for analysis-only agents.*

• Is `maxTurns` absent for a task with a predictable completion horizon? Unbounded agents

can loop on ambiguous input. *Minor for bounded tasks.*

• Is `skills` absent for an agent with domain-specific knowledge needs? Embedding domain

reference directly in the system prompt inflates every spawn; `skills:` defers it. *Major if system prompt exceeds 300 lines of embedded reference data.*

• Is `isolation: worktree` absent for an agent that modifies files in the working tree?

Without isolation, modifications are immediate and irreversible during the run. *Major.*

• Is `memory` absent for an agent that would benefit from cross-session learning? Agents

that review code, audit patterns, or accumulate project knowledge should use persistent memory (`project` recommended default). If `memory` is set, does the system prompt include memory maintenance instructions? Without them, the agent won't proactively update its knowledge base. *Major if the agent's domain involves pattern accumulation.*

• Is `effort` absent for a cost-sensitive or complexity-varying agent? Fast classification

tasks benefit from `effort: low`; d