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

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
agent-author	Use when the user wants a new agent definition created, or grill, audit or inline feedback applied to an existing one. Not read-only review -> `factory-audit`. Not skills -> `skill-author`. Not hooks, instructions or prompts -> `primitive-author`.	Bash Read Write Edit	version category source_keys 1.0.4 factory context7-websites-code-claude claude-code-plugins-docs claude-code-subagents-docs

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 a factory-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, factory-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 factory-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 factory-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. Skip, and say so, if this branch already bumped it: git diff $(git merge-base HEAD <remote-default-branch>) -- <package>/apm.yml shows a changed version: line, and one bump covers a branch. 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.