---
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.