holocron/plugins/kyberforge/.apm/skills/instructions-author/SKILL.md

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	version category source_keys 0.1.0 factory apm-docs-site apm-cli-0-28-0-experiments claude-code-memory-docs

Gotchas

• Claude Code drops description; only Copilot and Cursor keep it. Write a body that explains itself.
• Quote every applyTo. An unquoted **/*.py fails to parse, compile skips the file, and apm install still deploys it with no paths:, so it loads in every session and nothing errors.
• apm compile --validate always exits 0 and hides the missing-description, missing-applyTo and empty-body warnings. It is not a lint gate.
• Once rules sit in .claude/rules/, apm compile --target claude writes no CLAUDE.md and still exits 0; an exit-code check verifies nothing.
• A source must be flat in .apm/instructions/ and end .instructions.md; anything else is ignored or never installed.

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. Capture rtk git log --oneline -1 before touching the filesystem; Step 3 needs it.

Step 2 — Contract

Gates on every file, whichever flow wrote it:

• One topic per file. Two topics are two files.
• Scope. Omit applyTo only for a rule that must load in every session, and tell the user it then costs context at every launch.
• 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. Bullets, paths in backticks, nothing assuming another file is loaded, under 200 lines.

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 with paths:.
• Bump the owning package's apm.yml version — 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.

Commit verification. Once verification is clean, run rtk git add and rtk git commit. 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 lost if the tree is cleaned up. Report done only once the hash has changed.