holocron/plugins/kyberforge/.apm/skills/agent-author/SKILL.md at 3811f5481b7b0ad35a2e16d4cb1bccc62b90ed4c

Files

Defame1297 3811f5481b fix(kyberforge): unblock the scaffold and finish the #125 and ADR-0022 edits

Three related half-applied changes from #130, each leaving the corpus in a state its own
documentation contradicts.

Why:
- `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only
substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022
made mandatory and was blocked at first commit by the very hook this PR added. The commented
example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver.
- `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and
`user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file
this PR had just corrected to say the opposite.
- ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into
create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was
edited in place under a heading that still authorises removing it entirely.

Implementation notes:
- The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional
keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so
this cannot regress.
- `description-quality.md` now asserts only what the vendored Copilot research supports: two fields
with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone.
The unsupported negative it previously stated as fact is gone.
- The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow
actually reads — create.md, where it lived, is unreachable from that path. The compression item
moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers.
- Executable git commands in these three skills now carry the ADR-0023 rtk prefix.

Refs: #125, #127
ADR: 0022, 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP

2026-09-09 05:15:23 +00:00

4.6 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

version

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 rtk 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).

At every scope, five tools reach no subagent whatever tools says — AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers. Never write a body that has the agent ask the user a question or enter plan mode; it describes a turn the runtime cannot give it.

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 rtk git add and rtk git commit — do not stop at staging. Re-run rtk 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.6 KiB Raw Blame History