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
This commit is contained in:
Defame1297andClaude Code committed
1 parent
529ed31cef
commit
c52e351954
20 files changed
+719
-16
No files matched your search
@@ -0,0 +1,39 @@
|
||||
---
|
||||
source_keys:
|
||||
- apm-docs-site
|
||||
- apm-cli-0-28-0-experiments
|
||||
---
|
||||
|
||||
# Creating a new instructions file
|
||||
|
||||
Return to `SKILL.md` Step 3 once Step 3 below is done.
|
||||
|
||||
## Before touching the filesystem
|
||||
|
||||
Confirm, and ask the user for anything missing:
|
||||
|
||||
- [ ] The one topic the file covers. Two topics are two files.
|
||||
- [ ] Which files it governs, as a glob, or that it must load in every session.
|
||||
- [ ] A kebab-case stem. It becomes the deployed filename.
|
||||
|
||||
## Step 1 — Check the stem
|
||||
|
||||
Install overwrites a hand-authored file at `.claude/rules/<stem>.md`, `.cursor/rules/<stem>.mdc`, `.windsurf/rules/<stem>.md`, `.kiro/steering/<stem>.md` and `.agents/rules/<stem>.md` without a prompt. List those paths in the consuming project and choose another stem on any hit.
|
||||
|
||||
## Step 2 — Scaffold
|
||||
|
||||
```bash
|
||||
bash scripts/new-instructions.sh <name> <path-inside-the-package>
|
||||
```
|
||||
|
||||
The script walks up for a `type:`-bearing `apm.yml`. With none it exits 1 and names `/apm-workflow configure`; run that first, then retry. It never overwrites an existing file.
|
||||
|
||||
## Step 3 — Fill in
|
||||
|
||||
Replace every `FILL IN:` and delete the template's comments.
|
||||
|
||||
- `applyTo`: quoted. Omit it only for a rule that must load in every session, and say so to the user; it costs context at every launch.
|
||||
- `description`: one line. Write the body as if it were absent, because Claude Code never sees it.
|
||||
- Body: bullets, one topic, paths in backticks, nothing that assumes another file is loaded.
|
||||
|
||||
For glob syntax or a field question, read `references/schema.md`.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
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`.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
source_keys:
|
||||
- apm-docs-site
|
||||
- apm-github-repo
|
||||
- apm-cli-0-28-0-experiments
|
||||
- claude-code-memory-docs
|
||||
- github-copilot-custom-instructions-docs
|
||||
- cursor-rules-docs
|
||||
---
|
||||
|
||||
# Sources
|
||||
|
||||
## apm-docs-site
|
||||
|
||||
- **URL:** https://microsoft.github.io/apm/
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md)
|
||||
- **Description:** Official apm documentation, the instructions-and-agents authoring page plus targets and compile pages: frontmatter requirements, per-target deploy paths, compile behaviour and flags.
|
||||
- **Contributing files:** SKILL.md, references/schema.md, references/target-mapping.md, references/create.md, references/improve.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-github-repo
|
||||
|
||||
- **URL:** https://github.com/microsoft/apm
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md)
|
||||
- **Description:** apm's own Python source read for the Instruction model, discovery globs and per-target integrators.
|
||||
- **Contributing files:** references/schema.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-cli-0-28-0-experiments
|
||||
|
||||
- **URL:** https://pypi.org/project/apm-cli/0.28.0/
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-gotchas.md)
|
||||
- **Description:** The installed apm-cli 0.28.0 package plus throwaway install, compile and audit experiments confirming validation severity, unquoted-glob handling, discovery asymmetry, dedup and overwrite behaviour.
|
||||
- **Contributing files:** SKILL.md, references/schema.md, references/target-mapping.md, references/verify.md, references/create.md, references/improve.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-memory-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/memory
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-target-mapping.md)
|
||||
- **Description:** Claude Code memory documentation: `.claude/rules/` loading, the `paths` field as the only field read, invalid YAML ignored, size guidance.
|
||||
- **Contributing files:** SKILL.md, references/schema.md, references/target-mapping.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## github-copilot-custom-instructions-docs
|
||||
|
||||
- **URL:** https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-target-mapping.md)
|
||||
- **Description:** GitHub Copilot repository custom instructions: `.github/instructions/*.instructions.md`, `applyTo` and `excludeAgent`, the separate repo-wide file.
|
||||
- **Contributing files:** references/target-mapping.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## cursor-rules-docs
|
||||
|
||||
- **URL:** https://cursor.com/docs/context/rules
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md (digest: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-target-mapping.md)
|
||||
- **Description:** Cursor project rules: the `.mdc` requirement, `description`, `globs` and `alwaysApply`, rule types, size guidance.
|
||||
- **Contributing files:** references/target-mapping.md
|
||||
- **Status:** `extracted`
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
source_keys:
|
||||
- apm-cli-0-28-0-experiments
|
||||
- apm-docs-site
|
||||
- claude-code-memory-docs
|
||||
- github-copilot-custom-instructions-docs
|
||||
- cursor-rules-docs
|
||||
---
|
||||
|
||||
# What each target receives
|
||||
|
||||
Verified against apm 0.28.0 and throwaway installs. Reached from `SKILL.md` Step 2 when the question is which target keeps which field. Source-file syntax is in `references/schema.md`.
|
||||
|
||||
## Two output paths
|
||||
|
||||
`apm install` writes one native file per instruction into each target's rules directory. `apm compile` writes root context files that concatenate instruction bodies, grouped by `applyTo`. Treat install as the primary path for Claude Code and Copilot, and compile as the path for targets with no native instructions directory.
|
||||
|
||||
## Install: deployed path and transform
|
||||
|
||||
| Target | Deployed path | Transform |
|
||||
|---|---|---|
|
||||
| copilot | `.github/instructions/<n>.instructions.md` | Verbatim copy |
|
||||
| claude | `.claude/rules/<n>.md` | `applyTo` becomes a `paths:` list; `description` dropped; no frontmatter at all without `applyTo` |
|
||||
| cursor | `.cursor/rules/<n>.mdc` | `applyTo` becomes `globs`; `description` kept; no `alwaysApply` written |
|
||||
| windsurf | `.windsurf/rules/<n>.md` | `trigger: glob` plus `globs`, or `trigger: always_on`; `description` dropped |
|
||||
| kiro | `.kiro/steering/<n>.md` | `inclusion: fileMatch` plus `fileMatchPattern`, or `inclusion: always`; `description` dropped |
|
||||
| antigravity | `.agents/rules/<n>.md` | `trigger: glob` plus `globs`, or no frontmatter; `description` dropped |
|
||||
| grok-build | `.grok/rules/<n>.instructions.md` | Verbatim copy |
|
||||
| codex, gemini, opencode and the rest | none | Reach instructions only through compile |
|
||||
|
||||
Windsurf, Kiro, Antigravity and Cursor do not deploy at user scope.
|
||||
|
||||
## Field survival
|
||||
|
||||
| Field | Claude | Copilot | Cursor | Windsurf, Kiro, Antigravity | Compiled root file |
|
||||
|---|---|---|---|---|---|
|
||||
| `applyTo` | as `paths` | verbatim | as `globs` | as each target's glob key | grouping only |
|
||||
| `description` | dropped | kept | kept | dropped | dropped |
|
||||
| `author`, `version` | dropped | kept only because the file is verbatim | dropped | dropped | dropped |
|
||||
|
||||
For Claude Code the body's first line or heading is the only descriptive text that survives, so the body must explain itself.
|
||||
|
||||
## Ownership and overwrite
|
||||
|
||||
- Claude, Cursor, Windsurf, Kiro and Antigravity treat each deployed file as apm-owned: install replaces a hand-authored file at the same path without a prompt. Copilot skips an unmanaged file ("local files exist, not managed by APM") until `apm install --force`.
|
||||
- Removing or renaming a source makes the next install delete the file it deployed.
|
||||
|
||||
## Compile
|
||||
|
||||
- `--target claude` writes `CLAUDE.md`; Gemini writes `GEMINI.md` and `AGENTS.md`; every other target writes `AGENTS.md`.
|
||||
- Compile skips instructions already deployed natively, for Claude, Copilot and Antigravity only. With rules populated, `--target claude` exits 0, prints "produced no output files" and writes nothing. `--force-instructions` (alias `--no-dedup`) overrides.
|
||||
- Cursor, Windsurf, Kiro, Grok, Codex and OpenCode have no dedup: compile writes `AGENTS.md` that repeats rules the tool already loads natively.
|
||||
- A compile with no instruction primitives exits 0.
|
||||
|
||||
## Native format facts
|
||||
|
||||
- Claude Code reads `.claude/rules/**/*.md` recursively. `paths` is the only field it reads, as a list or a comma-separated string; other fields are ignored. A rule without `paths` loads at every launch. Frontmatter that fails to parse is ignored and the rule loads without `paths`.
|
||||
- Copilot path-specific files need `applyTo` as a quoted comma-joined string; `excludeAgent` is the only other documented key. Repository-wide instructions are the separate `.github/copilot-instructions.md`.
|
||||
- Cursor ignores a plain `.md` in `.cursor/rules`. A rule with only a `description` is "Apply Intelligently", not always-on.
|
||||
|
||||
## Unverified
|
||||
|
||||
Cursor's handling of a YAML-list `globs`, Copilot's handling of unknown frontmatter keys, and runtime behaviour on Windsurf, Kiro and Antigravity. Say so rather than asserting any of them.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
source_keys:
|
||||
- apm-cli-0-28-0-experiments
|
||||
---
|
||||
|
||||
# Verifying a file in a throwaway package
|
||||
|
||||
Reached from `SKILL.md` Step 3. Run step 2 outside the repo: `apm install` writes `apm_modules/`, `apm.lock.yaml` and a rules directory, and install overwrites hand-authored rule files without warning.
|
||||
|
||||
1. From the package root, a real compile, never `--validate`:
|
||||
|
||||
```bash
|
||||
apm compile --dry-run --target claude
|
||||
```
|
||||
|
||||
Resolve every warning it prints: missing `description`, missing `applyTo`, empty content, broken link, "Failed to parse".
|
||||
|
||||
2. For a scoped rule, deploy it where nothing else can be overwritten:
|
||||
|
||||
```bash
|
||||
d=$(mktemp -d)
|
||||
printf 'name: scratch\nversion: 0.1.0\ntype: instructions\ntargets:\n - claude\n' > "$d/apm.yml"
|
||||
mkdir -p "$d/.apm/instructions"
|
||||
cp <package-root>/.apm/instructions/<name>.instructions.md "$d/.apm/instructions/"
|
||||
(cd "$d" && apm install && cat .claude/rules/<name>.md)
|
||||
```
|
||||
|
||||
3. The deployed file must open with `paths:` listing the intended globs. No frontmatter block at all means `applyTo` was missing or did not parse: the rule would load in every session.
|
||||
|
||||
4. To check the compiled root file instead, compile in that same clean directory *before* installing, or pass `--force-instructions`; after an install, `--target claude` writes nothing.
|
||||
|
||||
Delete the directory afterwards. Report only what was observed; Cursor's list-form `globs` and the Windsurf, Kiro and Antigravity runtimes stay unverified.
|
||||
Reference in new issue
Block a user