Quickstart

Publish an instruction, then read it back the way an agent does. About five minutes.

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{name=verify-identity}
Verify the customer's identity before discussing an account.
:::

3. See what an agent will receive

instruction deliver support-agent.md

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 tells you if anything in the document would be refused.

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 a public URL at instruction.md/<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.

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.

Connect a real agent.
Concepts: refs, versions, visibility, proposals.
Sign your versions so consumers can verify them.