---
source_keys:
  - claude-code-subagents-docs
---

# Improving an existing agent

Return to `SKILL.md` Step 4 once Step 4 below is done — validation, the version bump and commit
verification are shared with the create flow and are not repeated here.

## Step 1 — Verify inputs

Confirm the agent file (or, at project and user scope, the pair) exists and that at least one
improvement signal is present in the conversation or in a referenced file.

If no signals are present, stop: "This skill applies existing signals to an agent. For a blind
review, run `factory-audit` instead."

`factory-audit` runs the validation in `SKILL.md` Step 4 and is co-installed with this skill; if
it is unavailable, stop and ask the user to install the kyberforge plugin before continuing.

**Partial pair — project and user scope only.** If one provider file exists and the other does
not, scaffold the missing one with `bash scripts/new-agent.sh <name> <root>` (file-by-file no-op)
and continue. Plugin/APM scope is a single file and has no partial state.

## Step 2 — Gather and group signals

Read the current file(s), then collect every signal from the conversation and from any path the
user referenced.

Group signals by **root cause**, not by symptom. Patching per symptom is the default failure mode:
three complaints often trace to one missing instruction. Ask: "What single gap in this agent
causes this cluster?" One root cause, one fix.

```text
Example:
- User feedback: the agent keeps trying to push to the remote
- Session context: no scope boundary in the system prompt
→ Root cause: the system prompt has no git scope constraint → fix: add an explicit boundary
```

## Step 3 — Announce planned changes

Before editing, state which root causes were identified, what evidence supports each, and which
files will change. Then proceed — edits are reversible via git, so no approval checkpoint is
needed.

## Step 4 — Apply changes

Edit whichever file the signals point to.

**Generalize, do not patch.** Fix the underlying gap, not the one example that failed. A fix
scoped to the cases you have seen overfits and performs worse on new input.

**Delegate rather than grow.** An agent body has no word ceiling, but a body that restates a
procedure a skill it can invoke already owns is a `factory-audit` FAIL. When a signal reports a
missing procedure, check first whether an installed skill owns it and name that skill instead of
transcribing it. See `references/contract.md`.

The delegation check is not a length brake — it fires only on procedure an invocable skill already
owns, and says nothing about original prose. That brake is judgment, and it is the only one left:
for every sentence you add, ask "would the agent get this wrong without it?" and delete it if the
answer is no.

**Explain the why.** Reasoning-based instructions outperform rigid directives. A rule written in
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
apply judgment at the edges.

**Retrofit before extending.** Any agent whose description does not meet the contract has to be
brought into compliance before any other edit lands — the gates are hot and carry no baseline file,
so a one-line fix to a non-compliant agent cannot be committed until its description meets
`references/contract.md`.
Treat that retrofit as part of the same change, not a follow-up.

**Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and
confirm the edit introduced no field that scope forbids, and dropped no `disallowedTools` fence
that was already there.

If the edit adds or removes research-sourced content, update `source_keys` in the edited file and
the matching `sources.md` entry — the create flow's Step 3 has the rules.

**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
which says nothing about a check that passed *before* these edits and no longer does. Compare the
closing `factory-audit` against the agent's pre-edit state — a PASS that has become a SUGGESTION, or
a SUGGESTION that has become a FAIL, is damage this flow caused and is in scope for it. Only the
improve flow can make that comparison; the create flow has no prior state to compare against.

Then return to `SKILL.md` Step 4.