Language reference
This reference is for developers who write, generate or check instruction documents. It describes the first edition of the language, instruction/1, as instruction.md's reader implements it: every keyword, block, attribute and key, and the exact text a model receives. The normative text is the specification.
A minimal document
An instruction is a UTF-8 Markdown file. This one is complete and valid:
---
spec: "1"
---
# Support replies
You answer Acme's customers by email.
MUST: greet the customer by name. - Front matter. The
---lines at the top hold YAML.spec: "1"names the edition. Front matter is optional: without it, the document is read as edition 1. - Body. Everything else is Markdown, shared by the people who read it and the agent that follows it. A heading and a sentence are ordinary Markdown.
- A rule. A line that starts with a rule keyword and a colon, here
MUST:, is a rule. The others are listed on Rules and blocks.
Check it and read what a model receives, offline, with the CLI (npm i -g instruction.md):
instruction validate support-replies.md
instruction deliver support-replies.md ok support-replies.md
# Support replies
You answer Acme's customers by email.
MUST: greet the customer by name. instruction validate exits 1 when a document has an error, and prints warnings without failing (--strict fails on them too). instruction deliver prints the delivered text, reading the bases and includes it names from files beside it. For a document that names none, it is the same text spec_deliver returns. For a released version, instructions_versions_read with resolve: true returns it; an instruction:// resource serves the source as written, not this text.
The parts of a document
A document has up to four regions. Only the body reaches the agent.
| Region | Where | Delivered | Page |
|---|---|---|---|
| Front matter | From the first line, between two lines of exactly --- |
Never | Front matter, notes and comments |
| Body | Everything between the front matter and the backmatter | Yes, in the delivered text | Rules and blocks |
| Comments | <!-- … --> anywhere in the body, outside code |
Never | Comments |
| Backmatter | After a blank line and a plain ---, when the next line that isn't blank or a YAML comment starts with a known key such as owners: |
Never | Backmatter |
Here is a document with all four, and the text an agent receives from it:
---
spec: "1"
title: Support replies
language: en
---
# Support replies
<!-- Reviewed with the support leads in November. -->
You answer Acme's customers by email.
MUST: greet the customer by name.
NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors.
---
owners: [support-leads]
review: { next: "2027-05-01" } # Support replies
You answer Acme's customers by email.
MUST: greet the customer by name.
NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors. The front matter, the comment and the backmatter are gone. The rule, its condition and its reason are delivered in their canonical form. The full text profile is on What an agent receives.
What the language has
The first edition defines 65 block kinds, 15 keywords (rule words and advisories) and 19 inline kinds, all listed in its registry (registry.json). These pages describe them topic by topic.
- Rules and blocksRule keywords, block kinds, their attributes, conditions and how each is delivered.
- Front matter, notes and commentsEvery front-matter and back-matter key, sources and citations, and what is never delivered.
- ParametersDeclaring parameters, their types and sources, and supplying their values.
- Includes, inheritance and extensionsIncluding, extending and patching other instructions, live or pinned.
- Inline references, links and annotationsInline references, wiki links, embeds, footnotes and annotations, and their delivered form.
- Tools, skills, agents and servicesDeclaring MCP servers, tools, skills, agents and services in an instruction, and how integration policy applies to them.
- Allowances and walletsWallets and spending allowances: their fields, how they narrow, and when an agent applies them.
- What an agent receivesThe delivered text and the resolved form an agent receives, their digests, and where to get them.
- Diagnostics and fixesEvery diagnostic the language service reports, its severity, and the fix it offers.
- Upgrade from Specification 1.1What changed from Specification 1.1, and how to upgrade documents one at a time or in bulk.
- Workflow nodesThe complete native Instruction Workflow node registry, including triggers, flow control, data transforms, models, tools, agents and human gates.
Tools that read the language
The same reader is behind every tool, so they agree on what a document means.
| Where | Check | See what a model receives | Other |
|---|---|---|---|
The CLI (instruction) |
instruction validate <file...> [--json] [--strict] [--quiet] |
instruction deliver <file> [name=value ...] [--resolved] |
instruction fmt, instruction tree, instruction digest, instruction render --view delivered |
| The MCP server | spec_validate (any text), instructions_validate (a stored draft) |
spec_deliver (any text), instructions_versions_read with resolve: true (a released version) |
spec_format, spec_outline, spec_fixes, spec_explain, the spec://kinds resources |
| The editor | The Problems list, as you type | Quick fixes | |
| VS Code | Diagnostics as you type | Quick fixes (VS Code) |
A release runs the same check as spec_validate and instructions_validate: a draft with an error can't be released, and warnings don't stop it. instruction validate runs it too, except for one check that only the server makes: a source that holds the host's host-integrations lines (The host's lines). The CLI's commands are on CLI commands, the tools on Tool reference and every diagnostic on Diagnostics and fixes.
The specification
The specification is the normative text. These pages follow it and say where instruction.md's reader adds to it. The sections these pages cover:
| Topic | Specification | Reference page |
|---|---|---|
| Front matter, backmatter, YAML, comments | §3 | Front matter, notes and comments |
| Directives, attributes, identities | §5 | Rules and blocks |
| Rules, policies, examples | §6 | Rules and blocks |
| The block registry, layout, media, code | §7, §8, §9 | Rules and blocks |
| People, skills, MCP, agents, allowances | §10 | Tools, skills, agents and services, Allowances and wallets |
| References | §11 | Inline references, links and annotations |
| Parameters | §12 | Parameters |
| Composition | §13, §15 | Includes, inheritance and extensions |
| Resolution and the delivered text | §14 | What an agent receives |
| Diagnostics | §18 | Diagnostics and fixes |
The specification's Markdown source is at /specification/1/specification.md, and the conformance vectors that pin the delivered text are in its repository.
Editions
A document names its edition with spec in its front matter. This reader knows one, "1"; the integer 1 reads as "1", and a document without spec is read as "1". Any other value is an unsupported-format error, so a document written for a later edition is refused rather than misread.
instruction.md reads only the first edition. A line still written in Specification 1.1, such as a :::when variant or a ::!kind block, is an error (instruction.md/legacy-syntax) with a fix that converts the document. See Upgrade from Specification 1.1.
Related
- What an instruction can say: the same language in plain words.
- Rules and blocks
- Front matter, notes and comments
- What an agent receives
- The specification, first edition