0 Fork 0

Files

T

Defame1297andClaude Code c52e351954 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

2.9 KiB

Raw Blame History

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.

2.9 KiB Raw Blame History