Files

Defame1297 4a5c3c0cff feat(kyberforge): enforce the ADR-0020 context contract for skills and agents

Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.

Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
  YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
  whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
  agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
  pins that absence

Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.

Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.

Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.

Refs: ADR-0020

2026-08-14 21:13:13 +00:00

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

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 predating ADR-0020 has to meet the description contract 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.

Then return to SKILL.md Step 4.

3.4 KiB Raw Blame History