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

4.1 KiB

Raw Blame History

source_keys

context7-websites-code-claude

claude-code-subagents-docs

github-plugins-creating

Creating a new agent

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

Prerequisites

Before touching the filesystem, confirm you have:

Agent name (kebab-case, e.g. code-reviewer)
Root directory — a path inside a package for plugin/APM scope, a project root, or ~ for user scope
Agent purpose — one sentence describing the task this agent handles
Trigger condition — when should the runtime delegate to this agent?

If any are missing, stop and ask before proceeding.

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

Design for one job per agent. An agent covering two jobs is delegated to for the wrong one.

Step 1 — Scaffold

bash scripts/new-agent.sh <name> <root>

Examples:

bash scripts/new-agent.sh code-reviewer packages/my-package/   # plugin/APM scope if packages/my-package/apm.yml has a type: field
bash scripts/new-agent.sh deploy-assistant .
bash scripts/new-agent.sh security-reviewer ~

The script resolves scope itself and prints which one it used and every path it wrote — read that output rather than predicting it. It walks up from <root> for the nearest ancestor apm.yml carrying a top-level type: field (instructions/skill/hybrid/prompts), which marks a package root and means plugin/APM scope. An apm.yml with no type: is a marketplace-only manifest: the walk skips it and keeps going. With no such manifest found, <root> being exactly ~ (checked directly, no walk-up) is user scope and anything else is project scope. A bare plugin.json no longer signals plugin scope — that path was replaced outright, not made dual-mode, and falls through to project scope.

The script is file-by-file no-op: it skips any file that already exists, so re-running it to complete a partial pair is safe.

If the script or a template under assets/templates/ has to change to support this agent — a new scope, a new scaffolded field, different output — read references/scripts.md first. Its conventions are asserted by tests/new-agent.bats, and an edit that ignores them fails the suite.

Step 2 — Fill in the file(s)

Take the scope the script reported and read the matching reference — SKILL.md Step 2 has the table. That file carries the field rules and the pre-audit checklist for this scope; the other one describes fields this run cannot use.

Every scaffolded file, at every scope:

Replace each FILL IN: placeholder.
Delete every  template comment from the frontmatter. apm compile copies plugin frontmatter verbatim and HTML comments are not valid YAML, so a leftover comment breaks the file downstream on both harnesses.
Write the description against references/contract.md and the system prompt body against its Body section.

Step 3 — Populate or delete `sources.md`

Plugin/APM scope only — skip at project and user scope, which have no package root to hold the file.

The scaffold writes a commented sources.md skeleton at the package root, alongside apm.yml and not inside .apm/agents/, so that tooling scanning that directory for agent definitions does not treat it as an agent missing its frontmatter (ADR-0010).

If a research sources.md is present in the conversation context, filter it to entries with `extracted` status, work out which agent file each one contributed to, and fill in the skeleton following the commented format already in the file. Paths in Contributing files: are relative to the package root. Each slug must match an H2 heading and must also appear in the source_keys list of every file named under its Contributing files:.

If no research sources are in context, delete sources.md.

Then return to SKILL.md Step 4.

4.1 KiB Raw Blame History