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

Shell
npm install -g instruction.md
instruction --version

Everything offline (validate, format, deliver, digest) works without an account.

2. Write a document

Shell
instruction init support-agent --template agent

That scaffolds support-agent.md. A minimal one looks like this:

support-agent.md
---
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

Shell
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

Shell
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

Shell
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

Shell
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