holocron/plugins/kyberforge/skills/agent-author/SKILL.md at b7bec71b8f5fb15187bcd32b1f76e6f6fa7afce9

Files

Defame1297 0f2bb242ad chore(plugins): sync generated content mirrors

Regenerates `plugins/*/skills`, `plugins/*/agents`, both per-plugin `plugin.json` manifests and the
two marketplace mirrors from `.apm/` per ADR-0017, via `scripts/sync-plugin-content.sh --all`.

The manifests matter beyond tidiness here: `plugin.json` carries the plugin version and wins over
the marketplace entry at install time (calculatePluginVersion precedence). Until this ran, the patch
bumps in the preceding commit were inert for anyone installing these plugins.

ADR: 0017
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP

2026-09-09 05:15:53 +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