---
source_keys:
  - apm-docs-site
  - apm-github-repo
  - apm-cli-0-28-0-experiments
  - claude-code-memory-docs
---

# The instructions source file

Verified against apm 0.28.0. Reached from `SKILL.md` Step 2 when a frontmatter field, a glob or the file's location is in question.

## Location and name

`.apm/instructions/<name>.instructions.md`, flat. The double extension is the discovery key and the stem is the primitive's name; there is no `name` field.

- A plain `.md` in that directory is ignored by both `apm compile` and `apm install`.
- A file in a subdirectory is folded into compiled root files by compile but never deployed by install, so it reaches `CLAUDE.md` and `AGENTS.md` and no native rules directory.
- The stem becomes the deployed filename: `<stem>.md`, `<stem>.mdc`, or `<stem>.instructions.md`, by target.

## Frontmatter

Only `description` and `applyTo` carry meaning. `author` and `version` are parsed and never emitted to any target.

- `description`: one line. The apm docs call it required; the binary only warns. Copilot and Cursor keep it; Claude Code, Windsurf, Kiro, Antigravity and every compiled root file drop it. Cursor auto-generates one from the first body sentence when it is missing.
- `applyTo`: a glob scoping the rule. The apm docs list it as both required and optional; the binary treats it as optional, with a warning. Empty or absent means an unconditional rule.

### `applyTo` grammar

- One glob: `"**/*.py"`.
- Several globs in one string, comma-separated: `"**/*.css,**/*.scss"`. Whitespace around segments is trimmed.
- A YAML sequence is joined into the same comma form.
- Brace alternation is never split: `"**/*.{css,scss},**/*.py"` is two patterns.
- A literal comma in a pattern is `\,`; a literal backslash is `\\`.
- Always quote the value. An unquoted `**/*.py` is a YAML alias error; see `SKILL.md` Gotchas for what apm then does.

## Body

Plain markdown. Official guidance: bullets over prose, one topic per file (`python-style` and `python-testing` are two files), paths in backticks, no greetings or meta-commentary, no assumption that other files are loaded. apm sets no size limit. The downstream tools do: Claude Code recommends under 200 lines per file and Cursor under 500.

## Validation

`Instruction.validate()` yields three findings, all demoted to warnings: missing `description`, missing `applyTo` ("will apply globally") and empty content. A broken relative link in the body is a fourth, also non-fatal.

- A real `apm compile` prints them. `apm compile --validate` prints none and exits 0 even for a file with all three problems.
- `apm install` prints none.
- `apm audit --ci` checks lockfile, deployed-file presence, content hash and hidden Unicode, not instruction content.
- A file whose frontmatter does not parse is skipped by compile ("Failed to parse") but still deployed by install.

No standalone instructions validator exists, so enforcement is this skill's checks and `references/verify.md`.