feat(kyberforge): add instructions-author skill for .apm/instructions files

Scaffolds and revises apm instructions files, with a throwaway-package verification recipe because `apm compile --validate` always exits 0 and Claude Code drops `description`. Routed from forge and linked from apm-workflow's compile reference. Bumps kyberforge to 2.1.0 and the catalog to 0.5.2. Fixes #148 Co-Authored-By: Claude Code <[email protected]> Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
2026-10-01 06:46:39 +00:00
1 parent 529ed31cef
commit c52e351954
@@ -0,0 +1,31 @@
+---
+source_keys:
+  - apm-docs-site
+  - apm-cli-0-28-0-experiments
+---
+
+# Improving an existing instructions file
+
+Return to `SKILL.md` Step 3 once the edits are made.
+
+## Step 1 — Read the file and the signals
+
+Read the file whole. Signals are grill output, audit findings, inline feedback, or a session describing a rule that loaded when it should not, or failed to load. Apply what the signals name and nothing else.
+
+## Step 2 — Diagnose by symptom
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A scoped rule loads in every Claude session | `applyTo` is unquoted or malformed, so install deployed no `paths:` | Quote it, then confirm with `references/verify.md` |
+| Compile warns "Failed to parse" | Broken frontmatter YAML | Repair the YAML; do not delete the field |
+| The rule is in `CLAUDE.md` but not `.claude/rules/` | The file is nested under `.apm/instructions/` | Move it up to the flat directory |
+| The rule appears nowhere | The name lacks `.instructions.md` | Rename it |
+| Claude ignores guidance written in `description` | Claude Code drops `description` | Move the substance into the body |
+| A hand-written rule vanished after install | The stem collided with a deployed name | Restore it from version control and rename the source stem |
+| The same rule reaches the agent twice | Cursor, Windsurf, Kiro, Codex and OpenCode get both a native file and an `AGENTS.md` copy | State it to the user; it is apm behaviour, not a defect in the file |
+
+Cases not in the table: read `references/target-mapping.md`.
+
+## Step 3 — Split or trim
+
+A file covering two topics, or longer than 200 lines, becomes several files. Do the split only when a signal names it.