Quickstart
Publish an instruction, then read it back the way an agent does. About five minutes, in a terminal. (Rather not use one? Write and publish in the editor instead.)
1. Install the CLI
npm install -g instruction.md
instruction --version Everything offline (validate, format, deliver, digest) works without an account.
2. Write a document
instruction init support-agent --template agent That scaffolds support-agent.md. A minimal one looks like this:
---
spec: "1"
title: Support agent
---
# Support agent
You answer billing questions for Acme.
MUST[verify-identity]: verify the customer's identity before discussing an account.
BECAUSE: an account holds another person's data. 3. See what an agent will receive
instruction validate support-agent.md
instruction deliver support-agent.md environment=staging
This is the whole point of the specification: the bytes are defined, so what you see here is what
every conforming reader receives. instruction validate lists anything in the document
publishing would refuse. The agent template declares a required parameter, environment;
deliver takes its value as name=value and writes it into the text.
4. Sign in and publish
instruction login
instruction push support-agent.md --visibility public --publish --message "first version"
You now have an immutable version and a @latest ref pointing at it. The document has a
canonical id and an address agents follow, instruction://<you>/support-agent.
5. Read it back as an agent
instruction watch instruction://<you>/support-agent@latest --out AGENT.md
That follows the ref: it writes the delivered document, and rewrites it whenever you publish. Stop
it with Ctrl-C. An agent does the same thing over MCP, without polling, by subscribing
(a subscriptions/listen stream, which is how watch hears of it too).
6. Publish a change
instruction push support-agent.md --to <id> --publish --message "tighten the refund rule"
Anything following @latest picks it up. If you want a ref that only moves
deliberately, publish to @stable and have agents follow that instead.
Next
- Connect a real agent.
- Concepts: refs, versions, visibility, proposals.
- The language: what else an instruction can say.
- Sign your versions so consumers can verify them.