holocron/docs/adr/0029-prompts-are-thin-user-triggered-steering-messages.md

# Prompts are thin, user-triggered steering messages; procedure belongs in a skill

**Status: accepted (2026-09-28).** Refs #94. Sets the house rule that `primitive-author` enforces
when it writes a `.prompt.md`, and that `factory-audit` checks in its prompt flow.

A **Prompt** (the term is in `CONTEXT.md`) is a single-intent, user-triggered message with
parameters. It is the text a user would otherwise type again and again. It carries no procedure
beyond steering existing skills or agents by name. Once it holds reusable know-how, bundled files,
or anything the model should find on its own, it is a **Skill** in the wrong container.

This is stricter than apm. apm frames a prompt as a program: its docs state that "a prompt is a
program for an LLM" (microsoft.github.io/apm/concepts/what-is-apm/, "Secure by default"; the same
sentence is in the apm-cli 0.28.0 package README), and 0.28.0 scaffolds one as a numbered-steps
workflow (`apm_cli/workflow/discovery.py`). On every harness this repo targets, a prompt with a full
workflow in it is a worse skill:

- **Claude Code.** Custom commands have been merged into skills. "Both create `/deploy` and work
  the same way", and both are model-invocable by default (code.claude.com/docs/en/skills.md).
  apm 0.28.0 keeps only `description`, `allowed-tools`, `model`, `argument-hint` and `input` for
  Claude (`_PRESERVED_COMMAND_KEYS`) and drops `disable-model-invocation`. A deployed prompt is
  therefore a model-visible skill with fewer frontmatter keys, and it cannot be made user-only.
- **Copilot / VS Code.** "Prompt files are deprecated for Agent Host sessions and aren't loaded by
  Agent Host", and VS Code offers a migration that converts existing prompt files to agent skills
  (code.visualstudio.com/docs/agent-customization/prompt-files). They still load in the Local agent,
  which that page says will be removed in a future release.
- **Codex.** Codex receives no prompts at all.

The one job a prompt does better than a skill is a short, parameterised "do this now, using X and Y"
message, where `input:` → `$arguments` is the whole point.

## Description contract

A prompt's `description` is one plain, human-facing sentence that names the skills or agents it
steers. For example: "Review the current PR with `gitea-prs` and `factory-audit`, then summarise."
It has no "Use when…" trigger clause and no `Not X -> Y` boundary clause. This is the same shape
`factory-audit` already applies to `disable-model-invocation: true` skills. Without a trigger clause,
the router has little reason to pick the prompt over the skills it wraps. So when the model routes,
it tends to reach the real capability.

**Unverified:** how strongly Claude avoids routing to a description with no trigger clause. The
contract lowers the chance of the model invoking the prompt, but does not prevent it. If it does
happen, the cost is bounded: the prompt is a thin wrapper that calls the right skills anyway.

## Enforcement

- **`primitive-author`.** The prompt reference opens with a boundary gate. A request that carries
  procedure is redirected to `skill-author`.
- **`factory-audit`, script checks.**
  - `description` is present and non-empty (FAIL).
  - It is 250 characters or fewer (SUGGESTION).
  - It has no "Use when" trigger clause (SUGGESTION).
  - It has no `Not X -> Y` boundary clause (SUGGESTION).
- **`factory-audit`, judgment step.** A body that clearly carries reusable procedure is a FAIL. A
  borderline body is a SUGGESTION. There is deliberately no line-count or heading heuristic: the
  call is made by reading the content, because any threshold misfires.

## Consequences

- **`factory-audit` gains a prompt mode.** `*.prompt.md` is a Step 0 dispatch row with its own
  `references/prompt-flow.md`, and `scripts/lib-checks-primitive.sh` carries the three description
  checks above plus the judgment step (ADR-0025, amendment 2026-09-28). A prompt that was fine under
  apm's framing — a trigger clause, a boundary clause, a numbered workflow — now draws findings.
- **`primitive-author` refuses procedure-bearing prompts.** Its prompt reference opens with the
  boundary gate, so a "make me a command" request that carries reusable know-how is redirected to
  `skill-author` before any file is written. That makes skill-vs-prompt a checked boundary rather
  than an authoring preference.
- **Codex gets no prompts from this repo.** apm deploys none to Codex, so anything a prompt steers
  must also be reachable there through the skill it names. Keeping procedure in the skill is what
  makes that true; a fat prompt would be content Codex users silently never see.
- **Reversing this is cheap in files, not in routing.** No prompt exists in the repo yet, so the rule
  constrains new work only. Loosening it later means re-deciding the description contract, and every
  prompt written under it would need a trigger clause added.

## Considered options

- **Fat workflow prompts as peers of skills (rejected).** This follows apm's framing. But every
  "make me a command" request becomes a coin flip between two near-identical containers. The prompt
  also carries worse metadata on Claude and does not arrive on Codex.
- **The full ADR-0020 description contract for prompts (rejected).** A trigger clause and a boundary
  clause would make prompts route well. That actively invites the model to invoke the prompt, which
  contradicts "user-triggered".
- **Skill-by-default with prompts as a grudging exception (superseded during the grill).** This
  framed a prompt as a weaker skill competing for the same job. Giving it a distinct role, a thin
  caller over skills, is a boundary that can be checked, which "prefer skills" is not.