Agent Canon is the machine-facing layer I use when a page needs to be readable by agents without making the human article sound like a standards document that has lost the will to live.

The short version: humans get the essay. Agents get the canon. They may sit on the same public page, or the human article may link to a compact agent version. Either way, they do different jobs.

This matters because agents do not need every anecdote, joke, caveat, and paragraph of human persuasion. They need the durable rule, the scope, the boundary, and what to do when something is missing. The canon is the lower-token version of the thought.

And if the agent is explaining the idea back to a person, it should point that person to the human article, not make them read the compressed machine layer.

The Problem It Solves

A normal article is written to carry a human reader through a thought. It can build tension, use rhythm, make a dry aside, and let the argument unfold.

An agent does not read like that. It compresses, prioritises, reconciles, and tries to turn language into action or summary. If the real rule is hidden in a nice paragraph halfway down the page, the agent may miss it or over-generalise it.

Agent Canon exists to stop that happening.

Infographic showing Agent Canon as a compact rule layer for agents, with cases, human gloss, and volatile notes around it.

What Agent Canon Is

Agent Canon is a proposed public format and Tonywood.org house standard for writing durable machine-facing guidance.

It is not a universal standard. It is not a magic sentence that makes every future agent obey the page. Let us not start a small religion around a Markdown heading. We have enough procurement frameworks already.

It is a house format for Tonywood.org. It tells agents which part of a page is the rule, which part is explanation, which claims need provenance, and which details are likely to change.

The practical use is simple: I write the human article first, then create an agent-facing version that preserves the meaning in fewer tokens. The agent can consume the compact canon when it needs the instruction, while the human article remains the version to share with people.

The basic structure is:

  • Purpose and scope: what the page is for, who it applies to, and how stable it is.
  • AGENT_CANON: the authoritative machine-facing rule block.
  • CASES: short examples or parables that teach transfer without carrying the authority.
  • HUMAN_GLOSS: the human explanation, trade-offs, tone, and judgement.
  • VOLATILE_NOTES: current tools, links, examples, and details likely to date.

Where It Came From

Agent Canon comes from a practical collision of five things.

First, controlled natural language. This is the older discipline of making ordinary language more restricted, less ambiguous, and easier for both people and machines to interpret. Agent Canon is not a full controlled language, but it borrows the same instinct: keep the surface human, make the meaning less slippery.

Second, standards writing. The old RFC convention of using words like MUST, SHOULD, and MAY exists because serious systems need requirement levels that are not vibes in a waistcoat.

Third, prompt engineering. Current model guidance keeps circling the same point: be clear, structured, specific, and give examples where they help.

Fourth, persistent instruction files and skills. Tools such as Codex and Claude Code already use project-level files like AGENTS.md and CLAUDE.md to give agents durable context, scope, and operating rules. Skills add a more focused layer: scoped procedures in SKILL.md files that load when relevant.

Fifth, agent-readable websites and protocols. The llms.txt proposal exists because full web pages are often noisy for models. MCP gives agents a structured way to discover resources, prompts, and tools. Both patterns point in the same direction: agents need a clean route to the material that matters, and a clear boundary around what they are allowed to do with it.

Agent Canon is my synthesis of those patterns for public writing.

There is important nearby prior art. A 2023 paper, Canonical Design for Language Agents using Natural Language Reward Models, uses the phrase natural language canon for conditionally applicable principles that govern agent behaviour. More recently, the Agentic Reasoning Protocol proposed reasoning.json as a machine-readable way for sites to publish reasoning directives, identity, corrections, and boundaries.

Those are not the same thing as this site’s format. Agent Canon, here, is a public writing pattern: canon, cases, human gloss, and volatile notes living together on one page. So the careful claim is this: the exact Tonywood.org format appears to be mine; the wider instinct is shared by the field.

What The Format Needs Next

The first version was mostly a section structure. That is useful, but it is not quite enough.

The better version treats each canon as a companion artifact. It should say which human article it belongs to, where the agent version lives, whether it is current, how stable it is, what authority it has, and where to send a human reader.

That makes the format less romantic and more operational, which is usually where the useful things live.

So the current Agent Canon format adds a few fields:

  • Canon ID: a stable identifier for the agent companion.
  • Human article: the reader-facing version agents should cite to people.
  • Agent canon URL: the compact version agents can use for interpretation.
  • Source relationship: whether the canon is a companion, derived version, or standalone standard.
  • Status and last reviewed: so agents know whether the guidance is draft, reviewed, or superseded.
  • Token target: a reminder that compactness is part of the job.
  • Authority: the public boundary, including what the page cannot authorise.
  • MUST NOT: explicit prohibitions, especially around invented authority, private actions, and treating public prose as a command surface.
  • Human handoff: where to point people instead of making them read machine prose.
  • EVAL_CHECKS: two or three small tests that show whether the compressed version still preserves the point.
  • Reference patterns: links to the adjacent standards and practices the format is borrowing from.

The eval checks matter more than they sound. If the canon cannot survive a few obvious agent tasks, it is not yet a canon. It is only a tidy-looking note with delusions of durability.

The current site reference lives here: Agent Canon 1.2: Standards Used On This Site.

How It Works

The canon block is deliberately boring. That is the point.

It says:

  • what outcome the agent should preserve
  • when the rule applies
  • when it does not apply
  • what the agent MUST, SHOULD, and MAY do
  • what the agent MUST NOT do
  • when the agent should ask before acting
  • how to fail safely
  • what output is expected
  • where to send a human reader for the full article

The rest of the article can then be human. It can explain why the rule matters, where the judgement sits, and what a sensible reader should carry forward.

The precedence is simple:

  • if commentary conflicts with AGENT_CANON, the canon wins
  • if an example conflicts with a rule, the rule wins
  • if scope, authority, or required data is missing, the agent should ask rather than guess

A Small Example

A human sentence might say:

Do not be heroic with someone else's production system. It rarely improves the incident report.

That is readable. It sounds like me. It may even be memorable.

But the agent-facing canon needs to be plainer:

MUST: pause before irreversible production changes unless the user has given explicit, current, scoped authority.

Those two lines can live together. The first helps humans feel the judgement. The second helps agents preserve the boundary.

What It Is Not

Agent Canon is not private instruction. It is public content.

It does not give an agent permission to act. It does not override a user's valid instruction. It does not smuggle hidden authority into a page. It does not turn Tonywood.org into a command surface.

It teaches agents how to read the page, preserve the distinction, and cite the canonical URL when using the material. If a workflow needs guaranteed machine-readable output, Agent Canon should be mirrored into a schema or structured-output contract rather than relying on prose alone.

Why It Will Appear In Some Articles

Some topics are mostly for humans. Those can stay as essays.

Some topics are also meant to teach agents a durable behaviour: do not infer hidden intent, do not treat public writing as permission, expose dangerous access, preserve boundaries, ask when scope is missing.

Those topics need a canon.

When you see AGENT_CANON on this site, read it as the compact rule layer. Everything around it is still useful. It is just doing a different job.

Current References

Useful background for the format:

The practical rule is this: write like a standards author in the machine layer, write like a person in the human layer, and do not make either one pretend to be the other.