kyberforge: add instructions-author skill for .apm/instructions/*.instructions.md #148

New Issue

2026-10-01T06:23:23Z

Claude commented

2026-10-01 06:23:23 +00:00

Part of #94.

Why

kyberforge has skill-author and agent-author but nothing for .apm/instructions/*.instructions.md. Claude's compile step silently drops fields an author would not know about without reading the schema closely: description is dropped entirely for instructions on Claude compile. An author gets no warning.

What to build

A new instructions-author skill, shaped like agent-author:

SKILL.md with a trigger description that states its domain boundary (ADR-0021) and routes review-only requests to factory-audit and skills/agents to their own author skills.
assets/templates/ with a minimal valid instructions file.
references/ covering the compile-time field-dropping behaviour per target, with the schema and what survives where. Source: plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md. Do not restate from memory; cite the research doc through source_keys and references/sources.md.
scripts/new-instructions.sh scaffolder and tests/new-instructions.bats, following agent-author.
A one-line pointer to the new skill in apm-workflow's compile reference (references/compile.md), so the gotchas have one owner.
A row in forge/SKILL.md's routing table.

Not in scope

Auditing instructions files. That is the audit issue for instructions, which depends on this one.
A separate gotchas copy in apm-workflow. This skill owns them.

Acceptance criteria

plugins/kyberforge/.apm/skills/instructions-author/ exists with SKILL.md, assets/, references/, scripts/, tests/.
Scaffolded output passes apm compile for the Claude target and the field-dropping gotcha is demonstrated in a test or fixture.
metadata.version set per ADR-0022; description and body pass ADR-0020 budgets (scripts/skill-size-check.sh).
forge/SKILL.md has a route to it; apm-workflow/references/compile.md points to it.
factory-audit run on the new skill returns PASS.
apm audit --ci clean; bats tests pass.

References

plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md
plugins/kyberforge/.apm/skills/agent-author/ as the structural model
ADR-0020, ADR-0021, ADR-0022

Part of #94. ## Why kyberforge has `skill-author` and `agent-author` but nothing for `.apm/instructions/*.instructions.md`. Claude's compile step silently drops fields an author would not know about without reading the schema closely: `description` is dropped entirely for instructions on Claude compile. An author gets no warning. ## What to build A new `instructions-author` skill, shaped like `agent-author`: - `SKILL.md` with a trigger description that states its domain boundary (ADR-0021) and routes review-only requests to `factory-audit` and skills/agents to their own author skills. - `assets/templates/` with a minimal valid instructions file. - `references/` covering the compile-time field-dropping behaviour per target, with the schema and what survives where. Source: `plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md`. Do not restate from memory; cite the research doc through `source_keys` and `references/sources.md`. - `scripts/new-instructions.sh` scaffolder and `tests/new-instructions.bats`, following `agent-author`. - A one-line pointer to the new skill in `apm-workflow`'s compile reference (`references/compile.md`), so the gotchas have one owner. - A row in `forge/SKILL.md`'s routing table. ## Not in scope - Auditing instructions files. That is the audit issue for instructions, which depends on this one. - A separate gotchas copy in `apm-workflow`. This skill owns them. ## Acceptance criteria - [ ] `plugins/kyberforge/.apm/skills/instructions-author/` exists with `SKILL.md`, `assets/`, `references/`, `scripts/`, `tests/`. - [ ] Scaffolded output passes `apm compile` for the Claude target and the field-dropping gotcha is demonstrated in a test or fixture. - [ ] `metadata.version` set per ADR-0022; description and body pass ADR-0020 budgets (`scripts/skill-size-check.sh`). - [ ] `forge/SKILL.md` has a route to it; `apm-workflow/references/compile.md` points to it. - [ ] `factory-audit` run on the new skill returns PASS. - [ ] `apm audit --ci` clean; bats tests pass. ## References - `plugins/kyberforge/docs/research/docs/microsoft-apm/instructions-primitive-schema.md` - `plugins/kyberforge/.apm/skills/agent-author/` as the structural model - ADR-0020, ADR-0021, ADR-0022

Claude added this to the Kyberforge basics milestone 2026-10-01 06:23:23 +00:00

Claude added the Kind/Feature label 2026-10-01 06:23:23 +00:00

Claude referenced this issue

2026-10-01 06:23:49 +00:00

kyberforge: factory-audit check suite for instructions files #151

Claude referenced this issue

2026-10-01 06:24:04 +00:00

kyberforge: add authoring/audit support for hooks, instructions, and prompt primitives #94

Defame1297 referenced this issue from a commit

2026-10-01 07:09:40 +00:00

docs(kyberforge): refresh apm instructions primitive research for #148

Defame1297 referenced this issue from a commit