The Instruction Specification
What a document means when an agent reads it. A Markdown document, a registry of the blocks it may contain, the exact text a reader receives, and the list of documents a reader must refuse.
Why it is separate from the platform
An instruction is followed by software that acts. If the meaning of a document depended on one vendor's parser, every agent that read it would be depending on that vendor. So the meaning is specified, published under a permissive licence, and held in place by a corpus that more than one independent implementation runs in its own test suite.
The platform on this site is an implementation of the specification. It is not the definition of it. A document you write here is readable by anything that implements the specification, and the specification is versioned separately so that stays true.
The document model
An instruction is Markdown with front matter. The one required field is the specification version, which is what a reader dispatches on.
---
spec: "1"
title: Support agent
---Everything else is ordinary Markdown until a block appears. A block is a container fence, a keyword line or an alert, and it either reads as prose or declares machinery.
Rules read as prose, and carry a label an agent can cite.
:::must{name=verify-identity}
Verify the customer's identity before discussing an account.
:::
Machinery carries a sigil, and is declared once.
::!tool{name=refund provider=stripe}
## !workflow approve-refund
1. Confirm the amount is under the limit.
2. Ask an approver.Disposition is the load-bearing distinction
Every block kind is prose, machinery or structural, and that decides how it is delivered. Prose keeps its text, because the words are the instruction. Machinery is not delivered as its source: the reader gets one line saying what now exists and what may be done with it, because a model should act on a tool, not interpret the YAML that configured it.
Prose
Rules, notes, examples, glossary entries. Fifteen kinds. Written without a sigil, delivered as the text you wrote, with a label a model can cite back.
Machinery
Tools, people, workflows, skills, data, environments. Written with a sigil, so it is never ambiguous with prose, and delivered as an acknowledgement rather than a configuration dump.
Structural
Parameters, includes and conditions. They shape the document rather than appearing in it.
Machinery is grouped into families
A family is the unit an operator grants. A document declares what it needs; the runtime that loads it grants what it is willing to allow; the intersection is what the document actually gets. A document cannot widen its own reach by declaring more.
core- the everyday machinery a document declares
material- files, data and assets a run may touch
knowledge- sources the agent may consult
interface- surfaces the agent may present
identity- people, roles and who may approve
compute- things that execute
infra- environments and endpoints
compose- composition of other instructions
Two families never survive a network read at all, no matter what a grant says: composition and identity. A document that arrived over the wire cannot pull in other documents or declare who is allowed to approve things. That floor is in the specification, not in a deployment.
The corpus is the contract
Prose is easy to agree with and hard to implement identically. The conformance corpus is what makes agreement checkable: documents with their expected parse and their expected delivered text, and a list of documents every conforming reader must refuse, with the refusal wording fixed.
| Documents with expected tree and delivery | 9 |
| Refusal cases with exact wording | 32 |
| Block kinds in the registry | 51 |
Both implementations, in both directions. One skipped invalid blocks when computing which families a document used. The other accepted a document the specification refuses. Neither was found by reading the prose; both were found by two implementations disagreeing on a file, and each disagreement ends as a new case.
Signing, serving and revocation
The specification covers the wire too, because bytes crossing a network to something that will act on them need provenance. It defines the author attestation over the authored document, the delivery attestation over what one reader was sent, how publisher keys are discovered, what the key states mean, and what a consumer does when a signature is missing, stale or revoked.
It also says plainly what a signature does not mean. A signature is provenance, not judgement.How signing works here.
Media type
An instruction is Markdown, served as a variant of it:
Content-Type: text/markdown; charset=UTF-8; variant=instructionThe identity of the format is that media type together with the declared specification version. A filename is a convention, and a served document has no filename.
Licence and contributions
The specification is published under Creative Commons Attribution 4.0, so implementing it, quoting it and forking it need no permission. Proposals live alongside it in the repository. Changes that alter what a reader receives arrive with corpus cases, because a change nobody can test against is a change nobody can implement.