Files

Defame1297 edcc57c0d6 docs: trim skill READMEs and ADR/changelog narration

Two related simplification-audit findings, bundled because they edit
some of the same skill-audit files and splitting would fragment
single-file diffs.

Finding 10: delete 48 per-skill/reference README.md files (they
restated SKILL.md in narrative form and no agent ever loads them) plus
2 scaffold templates. Drop the README criterion from skill-audit's
file-structure.md and finding-criteria.md, and the README-generation
step from skill-author's new-skill.sh; update new-skill.bats to match.
Plugin-root READMEs are kept intentionally, out of scope.

Finding 12: strip historical ADR-0020/ADR-0023 citations and
changelog-style narration from model-facing skill content across
kyberforge and git plugin skills. Delete skill-author's one-time
retrofit.md migration guide and its references. Some ADR-0023 tags
were not narration but check-rtk-prefix's required opt-out marker for
intentionally-bare git commands -- those were restored, not stripped.

Mirror re-synced and full pre-commit/pre-push suite verified green.

Refs: SIMPLIFICATION-AUDIT.md findings 10, 12

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD

2026-09-12 18:38:09 +00:00

4.2 KiB

Raw Blame History

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 agent-audit instead."

agent-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.

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 an agent-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 agent-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.

4.2 KiB Raw Blame History