Defame1297andClaude Code
c52e351954
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
1.6 KiB
1.6 KiB
source_keys
| source_keys | ||
|---|---|---|
|
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.