---
type: types/type-spec.md
name: instruction
description: Agent-directed procedure held as a flat file under instructions/, loaded by link or on explicit request rather than published as a skill
schema: types/instruction.schema.yaml
root: repo
base_dir: instructions
---

# Instruction

Use `instruction` for a procedure an agent follows: how to operate the tooling, how to recover
from a refused call, how to close out a change. An instruction is *prescriptive* - it tells the
reader what to do, not what is true.

Instances are flat files under `instructions/`. That placement is what keeps them unpublished:
a subdirectory containing a `SKILL.md` is copied into the harness skill directories, while a
flat file is reached only through a link or an explicit request. See
[instructions/CONTRACT.md](../instructions/CONTRACT.md).

## When to Use

- A procedure is repeated across several skills or contracts and should exist once
- An operation is rare enough that a permanently-loaded skill would not earn its context cost
- A refusal, gate, or failure mode needs a documented recovery path

## When NOT to Use

- The procedure is a whole task an agent should be able to invoke by name - write a skill
  (`instructions/<name>/SKILL.md`), whose frontmatter belongs to the harness, not to this type
- The content is a fact about a system rather than an action - that is an `entity` or `concept`
  page under `kb/`
- The content explains *why* a rule exists - that is a `concept` page, linked from the
  instruction

## Frontmatter

| Field | Required | Use |
|---|---:|---|
| `type` | Yes | `types/instruction.md` |
| `name` | Yes | Short identifier, matching the filename stem |
| `description` | Yes | The retrieval wire: the question an agent would ask when it needs this procedure. Not a label for the file |

There is deliberately no `summary` and no `sources`. An instruction is not a knowledge claim: it
is either correct and in use, or it is wrong and gets fixed.

## Authoring Instructions

- Title imperatively - it answers "what does this tell me to do?"
- Frontload: self-contained for an agent with no prior context. Define terms inline.
- Make decision points explicit ("if X, do A; otherwise do B") rather than implied.
- State scope boundaries: when this does *not* apply, and what to do instead.
- Keep reasoning minimal - only enough to decide edge cases. The rest is a concept page.
- Show the exact command. A step an agent has to reconstruct is a step it can get wrong.

## Template

```markdown
# {name}

{One paragraph: what situation this applies to, and what it achieves.}

## When to run

- TODO: the trigger conditions

## Steps

1. **TODO** - what to do:

   ```bash
   TODO: the exact command
   ```

2. **TODO** - the next step, with its decision points stated.

## Decision points

- **TODO: condition?** TODO: what to do instead.

## Scope

TODO: when this does not apply, and what to use instead.
```

---

Relevant Notes:

- This type declares `root: repo`, so `base_dir: instructions` resolves against the repository
  root rather than `kb/`. Instructions are agent-directed material, not compiled knowledge, and
  the `raw/` -> `kb/` provenance rules do not apply to them.
- It declares no `page_ref_fields:`: an instruction links with ordinary markdown paths, not
  wikilinks, because its targets are contracts and other instructions rather than pages.