chemenu/types/instruction.md

type, name, description, schema, root, base_dir

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

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

# {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.