kayforkind/skill-slice/agent-orchestration-improve-agent

Claude Code and agent skill by kayforkind/skill-slice

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Diagnoses and tightens an existing Claude subagent markdown file under `.claude/agents/` from concrete failure transcripts: trigger description, tool list, and output contract. Use when a named subagent drifts, calls the wrong tools, or produces off-task output. Not for authoring a brand-new agent or a Cursor SKILL.md. Do not use to edit Claude's own system prompt or when no failure examples exist.

Install

npx vskill@latest install kayforkind/skill-slice/agent-orchestration-improve-agent

SKILL.md

The same SKILL.md was published earlier as kayforkind/skill-slice/agent-orchestration-improve-agent.

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 description triggers 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.

  1. The agent file — path to the .md under .claude/agents/ or ~/.claude/agents/.
  2. At least 2–3 concrete failures — transcripts, prompts, or outputs showing the problem.
  3. Expected behavior — what should have happened in those cases.
  4. 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
powershell
# From the project root (Windows / PowerShell)
Get-Content .claude\agents\<name>.md

Or for a user-level agent:

powershell
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:

SymptomLikely causeFix
Agent triggers on wrong tasksdescription too broad or vagueTighten description; add explicit "do not use" cases
Agent skips tasks it should handledescription too narrow or missing trigger keywordsAdd example triggers to description
Wrong tool callstools: list too permissive, or prompt doesn't guide tool choiceRestrict tool list; add tool-selection guidance
Verbose / off-format outputNo output format specifiedAdd explicit output contract with example
Hallucinated file paths or APIsPrompt encourages guessingAdd "verify before recommending" instruction
Drifts mid-taskNo checkpoint / no stop conditionAdd explicit completion criteria
Step 3: Edit the prompt

Make the smallest change that fixes the observed failures. Avoid sweeping rewrites.

Patterns that work:

  1. Tighten `description` — include 2–3 example user phrases that should trigger it, and 1–2 that should not.
  2. Add a "Do not" section — explicit anti-patterns are more effective than aspirational instructions.
  3. Add a worked example — input → expected output, in the exact format you want.
  4. Restrict tools — remove any tool the agent doesn't need; fewer options = less drift.
  5. 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:

powershell
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:

  1. Failure cases resolved — re-run the agent on each original failure input and confirm it now produces the expected behavior.
  2. No regressions — run 1–2 previously-working cases and confirm they still pass.
  3. Diff reviewed — the change to the agent file is the smallest possible and targets the diagnosed root cause.
  4. Committed (if applicable) — the agent file is committed with a message naming the symptom fixed.
Output contract

When invoked, this skill should produce:

  1. A summary of failures found and their root cause.
  2. A diff (or before/after snippet) of the agent prompt.
  3. Verification results on the original failure cases.
  4. 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.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
5

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kayforkind/skill-slice/agent-orchestration-improve-agent/badge)](https://verified-skill.com/skills/kayforkind/skill-slice/agent-orchestration-improve-agent)

Something wrong with this skill or its page? Tell us.