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

Files

Defame1297 60be7b3232 refactor(skills): mandate metadata.version on every skill's frontmatter

Only 12 of 39 skills carried metadata.version, and adoption tracked
which plugin a skill lived in rather than any stated rule: core,
gitea and lint were consistent adopters, bin and kyberforge were
consistent non-adopters, git was split with one outlier. There was
no documented convention, and skill-author's own bump logic was
already written as if presence were conditional.

metadata.version is now required on every skill. The 19 skills here
that never carried one (bin, kyberforge, gitea-files) are seeded at
1.0.0, not 0.1.0 -- that value stays reserved for a skill's actual
creation point under skill-author's existing convention. The
skill-frontmatter pre-commit hook now fails a SKILL.md missing the
field, the same class of failure as a missing name/description.

Full rationale in the new ADR. The git-plugin skills that also need
this field follow in the next commit, bundled with issue #113's rtk
normalization since both touch the same files.

Refs: #127
ADR: 0022
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP

2026-09-07 20:36:24 +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 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 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.6 KiB Raw Blame History