Defame1297
af8b46cd57
Regenerate plugins/*/skills/ from plugins/*/.apm/ after the previous four commits, via scripts/sync-plugin-content.sh --all. The mirror is generated output (ADR-0017) that check-plugin-content-sync's pre-push hook diffs against .apm/; nothing here is hand-edited. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
66 lines
4.6 KiB
Markdown
66 lines
4.6 KiB
Markdown
---
|
|
name: agent-author
|
|
description: >
|
|
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`.
|
|
allowed-tools: Bash Read Write Edit
|
|
metadata:
|
|
version: "1.0.0"
|
|
category: factory
|
|
source_keys:
|
|
- 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 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.
|