Instructions for AI, versioned and live.
An open Markdown specification and a platform for writing, versioning, sharing and governing the instructions your AI agents follow, and for updating them while the agents are running.
- What is it?
- A Markdown document an agent reads as its instructions, a specification for what the document means, and a registry that versions it, signs it and serves it over MCP.
- Why would I use it?
- Because the prompt your agent follows is production configuration. It deserves review, versions, a diff, an owner, a signature and an audit trail, and a way to change it without redeploying the agent.
- Open specification, or proprietary service?
- The specification is open and separately published, with a conformance corpus that more than one implementation is held to. The platform is a hosted implementation of it, and it can be self-hosted.
- How do I connect an agent?
- One MCP endpoint. Your agent reads
instruction://owner/name@stableand subscribes. When you publish, it hot-reloads. Connect an agent. - Where is everything else?
- Docs, the specification,plans.
Write Markdown. Agents receive what the specification says they receive.
Rules become labelled instructions. Machinery, meaning the tools, people and workflows a document declares, becomes a line the model can act on rather than YAML it has to interpret. The panel on the right is generated from the document on the left by the code the registry runs.
---
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.
:::
:::never{name=no-refunds-over-limit}
Never issue a refund above ${refund_limit} without an approver.
:::
::!human{name=oncall role=approver}
Exactly what a model receives after delivery (spec §3.5): machinery projected to acknowledgement lines, no variants withheld.
# Support agent
You answer billing questions for Acme.
**MUST:** Verify the customer's identity before discussing an account.
**NEVER:** Never issue a refund above 500 USD without an approver.
[human role "oncall" may be asked]
The same document, read by a person.
This block is the <instruction-md> element, the one you can put on your own page with a single script tag. It is rendering the document above.
Support agent
You answer billing questions for Acme.
Verify the customer's identity before discussing an account.
Never issue a refund above ${refund_limit} without an approver.
!humanoncallinterface · interface
role=approver <script type="module" src="https://instruction.md/render@1.js"></script>
<instruction-md ref="instruction://acme/support-agent@stable"></instruction-md>What the platform adds
Versions and refs
Immutable versions, and named refs like @stable that agents follow. Rolling back is moving a ref, not editing a document.
Hot reload
Publish, and subscribed agents pick it up. A consumer keeps its last good version when a read fails, so a bad network never means no instructions.
Signatures
Versions carry an author attestation, with publisher keys anyone can fetch and verify. Revoke a key and consumers hold rather than apply.
Review before it ships
Proposals with diffs and approvals, and refs that only move for signed or approved versions.
Who is following what
Which agents read an instruction, which version each applied, and how long adoption took.
Sharing that fits teams
Private, internal or public. Organizations, workspaces and per-instruction grants, with an audit record that never contains your content.
Connect in a minute
{
"mcpServers": {
"instruction-md": { "url": "https://mcp.instruction.md/mcp" }
}
}
# then read, and subscribe for updates
instruction://acme/support-agent@stable