gabrielmoreira Improve an Existing Agent
Use when an agent (subagent definition under .claude/agents/ or ~/.claude/agents/) is misbehaving, drifting, or could be tighter. The workflow is: gather evidence → diagnose → edit the prompt → verify → ship.
When to Use
Trigger this skill when any of the following are true:
- An agent is producing wrong, verbose, or off-task output.
- An agent is calling the wrong tools, or too many of them.
- The agent's
descriptiontriggers the wrong tasks (or doesn't trigger at all). - You want to tighten scope, add examples, or fix a recurring failure.
Do Not Use
- Creating a brand-new agent — use the agent-creation skill instead.
- Editing the system prompt of Claude itself.
- You have no concrete examples of the failure — gather them first.
Prerequisites
Before editing the agent file, collect all of the following. If any are missing, stop and gather them before proceeding.
- The agent file — path to the
.mdunder.claude/agents/or~/.claude/agents/. - At least 2–3 concrete failures — transcripts, prompts, or outputs showing the problem.
- Expected behavior — what should have happened in those cases.
- Scope check — is the agent being invoked for tasks it shouldn't handle, or vice versa?
Editing prompts blind produces churn. Do not skip the evidence-gathering step.
Procedure
Step 1: Read the current agent
# From the project root (Windows / PowerShell)
Get-Content .claude\agents\<name>.md
Or for a user-level agent:
Get-Content $HOME\.claude\agents\<name>.md
Note the existing structure: frontmatter (name, description, tools), system prompt body, any examples or constraints.
Step 2: Diagnose
Map each failure to a root cause. Common patterns:
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent triggers on wrong tasks | description too broad or vague |
Tighten description; add explicit "do not use" cases |
| Agent skips tasks it should handle | description too narrow or missing trigger keywords |
Add example triggers to description |
| Wrong tool calls | tools: list too permissive, or prompt doesn't guide tool choice |
Restrict tool list; add tool-selection guidance |
| Verbose / off-format output | No output format specified | Add explicit output contract with example |
| Hallucinated file paths or APIs | Prompt encourages guessing | Add "verify before recommending" instruction |
| Drifts mid-task | No checkpoint / no stop condition | Add explicit completion criteria |
Step 3: Edit the prompt
Make the smallest change that fixes the observed failures. Avoid sweeping rewrites.
Patterns that work:
- Tighten
description— include 2–3 example user phrases that should trigger it, and 1–2 that should not. - Add a "Do not" section — explicit anti-patterns are more effective than aspirational instructions.
- Add a worked example — input → expected output, in the exact format you want.
- Restrict tools — remove any tool the agent doesn't need; fewer options = less drift.
- Specify output shape — bullet list / JSON / sectioned report — pick one and show it.
Anti-patterns to avoid in the edit:
- Adding "be careful" or "make sure" without saying what to check.
- Long preambles about the agent's role — Claude already knows it's an assistant.
- Vague metrics ("high quality", "accurate") — replace with concrete checks.
Step 4: Verify
Re-run the agent on the original failure cases. For each case:
- Does it now produce the expected behavior?
- Did the change regress any previously-working case? Run 1–2 known-good cases too.
If you can't reproduce the original failures interactively, write the test inputs into a scratch file and run the agent against them one at a time.
Step 5: Commit
If the agent file lives in a git repo, commit with a message that names the symptom fixed:
git add .claude\agents\<name>.md
git commit -m "tighten reviewer agent description to skip docs-only diffs"
No commit if the file is in ~/.claude/agents/ and not tracked.
Pitfalls
- Editing without evidence. Without real failure examples, this skill produces guesses. Always gather 2–3 concrete failures first.
- Sweeping rewrites. Large prompt rewrites introduce regressions. Make the smallest change that fixes the observed failure.
- Vague instructions. "Be careful" and "make sure" without specifying what to check are no-ops. Replace with concrete, checkable instructions.
- Over-permissive tool lists. Extra tools cause drift. Remove any tool the agent doesn't need.
- Model limitations vs. prompt issues. Prompt edits don't fix model limitations — if the failure is the model misreading clear instructions, a model swap may help more than a prompt tweak.
- Expectation mismatch. Some "failures" are actually user expectations the agent was never designed to meet. Widening scope is a design decision, not a bug fix.
Verification
Confirm the improvement is complete by checking each item:
- Failure cases resolved — re-run the agent on each original failure input and confirm it now produces the expected behavior.
- No regressions — run 1–2 previously-working cases and confirm they still pass.
- Diff reviewed — the change to the agent file is the smallest possible and targets the diagnosed root cause.
- Committed (if applicable) — the agent file is committed with a message naming the symptom fixed.
Output contract
When invoked, this skill should produce:
- A summary of failures found and their root cause.
- A diff (or before/after snippet) of the agent prompt.
- Verification results on the original failure cases.
- Any remaining concerns or follow-ups.
Limitations
- Prompt edits don't fix model limitations — if the failure is the model misreading clear instructions, a smaller/larger model swap may help more than a prompt tweak.
- Without real failure examples, this skill produces guesses.
- Some "failures" are actually user expectations the agent was never designed to meet; widening scope is a design decision, not a bug fix.
Related Skills
- Agent creation — for building a brand-new subagent from scratch rather than improving an existing one.