holocron/plugins/kyberforge/.apm/skills/agent-author/SKILL.md at 311e7cd22c803d725f7f4be215a32afcc8440be9

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.3 KiB

Raw Blame History

name, description, allowed-tools, metadata

name

description

allowed-tools

metadata

agent-author

Use when the user wants to create a new agent definition file from scratch, or apply grill findings, audit findings, or inline feedback to an existing one. Not read-only review -> `agent-audit`. Not skills -> `skill-author`.

Bash Read Write Edit

Gotchas

At plugin/APM scope tools and every Claude-only field are omitted entirely, not merely ignored: apm compile copies frontmatter verbatim to both harnesses, so fencing a read-only agent with tools: is wrong on one of them. disallowedTools is the one restriction that survives (ADR-0016).
That fence is partial. It denies only the tools it names, never Bash, which a plugin-scope agent inherits — a shell redirect still writes. State the read-only boundary in the body too.
An agent body carries no word gate; delegation replaces it. A plugin/APM agent is one file with no sibling references/ directory, so it cannot disclose to itself, only invoke skills — and a body restating a procedure an invocable skill owns is an agent-audit FAIL.
Duplicate name values in one scope: Claude Code discards one silently. Verify uniqueness before shipping.

Step 1 — Dispatch

Condition	Flow	Reference
No agent file at the target path(s)	Create	`references/create.md`
A file exists, at least one improvement signal present	Improve	`references/improve.md`
A file exists, no signals	Stop and ask	—

Signals: grill output, agent-audit findings, inline feedback, session context describing what went wrong. With none, ask: "No improvement signals found. Did you mean to create a new agent, or do you have feedback to apply?"

Read only the reference for the resolved flow. Capture git log --oneline -1 before touching the filesystem; Step 4 needs it.

Step 2 — Scope

Scope decides which fields exist, so resolve it first. scripts/new-agent.sh walks up for a type:-bearing apm.yml and prints the scope it chose — read that output.

Resolved scope	Emits	Read
plugin/APM	one vendor-neutral `.apm/agents/<name>.agent.md`	`references/plugin-scope.md`
project or user	a Claude Code `.md` + Copilot `.agent.md` pair	`references/project-user-scope.md`

Read only the file for the resolved scope; the other describes fields this run cannot use. If precedence, cache isolation or path conventions matter, read references/deployment-modes.md.

Step 3 — Contract

Before writing or editing a description, or restructuring a body, read references/contract.md — the three-part shape, banned content, the delegation rule and the body pattern.

Gates agent-audit enforces at every scope:

Description — a trigger clause, at most one capability clause, and a boundary clause shaped Not <thing> -> <name> that resolves to a real skill or agent. 250 characters SUGGESTION, 400 FAIL, value only: an agent's name and description is preloaded into every session exactly as a skill's is.
Body — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does.
Invocation — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (disable-model-invocation, user-invocable).

Step 4 — Validate and close

Invoke agent-audit on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those.

At plugin/APM scope bump the resolved package's apm.yml version — minor on create, patch on improve — because consumers compare it to detect updates. Project and user scope have no manifest.

Commit verification. Once the audit is clean, run git add and git commit — do not stop at staging. Re-run git log --oneline -1 and confirm the hash changed from Step 1's. A non-empty git diff --stat is not proof: staged-but-uncommitted work is part of no commit and is lost if the tree is cleaned up. Report done only once the hash has changed.

4.3 KiB Raw Blame History