Defame1297andClaude Code
d576695bb9
- instructions-author: keep two Gotchas, move the rest to the Step 2 contract and verify.md; add references/content.md on what belongs in an instructions file and tighten the template bullets to match - instructions-author, skill-author, agent-author: remove the commit verification step; committing is out of scope for author skills - skill-author 1.0.6, agent-author 1.0.4 (ADR-0022 patch bumps) Refs #148 Co-Authored-By: Claude Code <[email protected]> Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
2.8 KiB
2.8 KiB
name, description, compatibility, allowed-tools, metadata
| name | description | compatibility | allowed-tools | metadata | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| instructions-author | Use when creating or revising an apm instructions file (`.apm/instructions/*.instructions.md`). Not read-only review -> `factory-audit`. Not skills -> `skill-author`. Not agents -> `agent-author`. Not AGENTS.md -> `agentsmd-author`. | Requires the apm CLI; behaviour verified against apm 0.28.0. | Bash Read Write Edit |
|
Gotchas
- Claude Code drops
description; only Copilot and Cursor keep it. Write a body that explains itself. - Quote every
applyTo. An unquoted**/*.pyfails to parse, compile skips the file, andapm installstill deploys it with nopaths:, so it loads in every session and nothing errors.
Step 1 — Dispatch
| Condition | Flow | Reference |
|---|---|---|
| No file at the target path | 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, audit findings, inline feedback, a session describing a rule that loaded when it should not or failed to load. With none, ask whether the user meant to create a new file or has feedback to apply.
Read only the reference for the resolved flow.
Step 2 — Contract
Gates on every file, whichever flow wrote it:
- One topic per file. Two topics are two files.
- Scope. Omit
applyToonly for a rule that must load in every session, and tell the user it then costs context at every launch. - Source. Flat in
.apm/instructions/, named<stem>.instructions.md. Anything nested or misnamed is ignored or never installed. - Stem. It becomes the deployed filename, and install overwrites a hand-authored rule of the same name on most targets without a prompt. Check for a collision before choosing it.
- Body. Concrete, checkable bullets, paths in backticks, nothing assuming another file is loaded, under 200 lines. Whether the content belongs in an instructions file at all: read
references/content.md.
If a field, glob or location is in question, read references/schema.md. If the question is which target keeps which field, or what compile does, read references/target-mapping.md.
Step 3 — Validate and close
- Verify with a real compile and a throwaway deploy: read
references/verify.md. Resolve every warning and confirm a scoped rule deploys withpaths:. - Bump the owning package's
apm.ymlversion— minor on create, patch on improve — because consumers compare it to detect updates.
factory-audit has no instructions checks yet, so nothing else gates the file; report only what the verification showed.