Defame1297
fd86ee42f4
- annotate the research Must demoted to hook Should 12; narrow Must 5 note - extend Must 6 to scripts run via an interpreter -c string - add a fallback dispatch row and comma-joined --target guidance - fall back when agentsmd-author is not installed - add the apm-workflow boundary; pin upstream apm source URL Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
3.0 KiB
3.0 KiB
source_keys
| source_keys | ||
|---|---|---|
|
Authoring an apm instruction
Reached from SKILL.md Step 1 for an instruction. SKILL.md Step 2 runs the Gate below; Step 3
writes against the checklist.
Gate
An instruction is a scoped rule: it applies when the agent touches files matching its applyTo
glob. On Claude it deploys to .claude/rules/<stem>.md with applyTo renamed to paths:.
- A rule for this repo alone → it belongs in the repo's AGENTS.md, which is the single
always-on source. Stop and hand to
agentsmd-author; if it is not installed, edit the repo's AGENTS.md directly. - No file pattern fits → an instruction without
applyTois always-on in every session of every repo that installs this package, andapm compilecan fold it into the global sections ofAGENTS.mdandCLAUDE.md(CLAUDE.md is skipped when.claude/rules/is populated, AGENTS.md when.github/instructions/is, unless--force-instructions). Say exactly that to the user and continue only on an explicit yes. Legitimate when a package deliberately ships guidance to its consumers; never a default. - Procedure the agent follows step by step → a skill. Stop and hand to
skill-author. - Which harnesses receive it, or other package config → set by the package
apm.ymltargets:, never by the instruction file. Stop and hand toapm-workflow. - A rule scoped to a file pattern → continue.
Checklist
Copy assets/templates/name.instructions.md.template and drop .template only on the final path.
Must:
- The path is
.apm/instructions/<stem>.instructions.md, directly in that directory, not a symlink or hardlink. descriptionis a non-empty string. Onlyapm compilewarns when it is missing;apm installdeploys it silently.- The body is non-empty after trimming whitespace. apm deploys an empty rule silently.
applyTois a non-empty glob or comma-separated list — top-level commas only as separators, alternation inside{}("**/*.{ts,tsx}"), braces and brackets balanced — or absent after the Gate's explicit yes. An emptyapplyTo: ""is neither.- The stem is unique across the package and its dependencies: a
.claude/rules/<stem>.mdcollision is silently overwritten.
Should:
- Write
applyToas a scalar string, not a YAML list. Copilot receives the source verbatim, and its handling of a list is unverified. - Keep frontmatter to
descriptionandapplyTo, plus optionalauthorandversion. No target consumes other keys, and Claude drops them. - Put any rationale Claude needs in the body.
descriptionnever reaches Claude — it survives for Copilot and as index text in Cursor rules and compiled AGENTS.md/CLAUDE.md. - Keep relative markdown links resolvable from the source file.
- Check the glob against the tree: one that matches nothing here fires only in consumer repos that have such files, and one broader than the rule's real scope spends context on every file it touches.