The Spec

6 minutes read

Slipway implements the agent-editable site spec, version 0.1. The spec says what a site publishes so an agent can change it safely: where its content lives, which fields a page accepts, which source line produced each part of a built page, how to find the editing instructions from the live site, and how a person hands a precise edit to an agent.

The spec covers editing only. Whether a site is healthy and readable by agents — broken links, accessibility, llms.txt, Markdown twins — is Seaworthy's question, and no requirement here repeats it.

The normative text is spec/agent-editable/0.1.md. The levels are in levels.md, the machine-readable test list in tests.json, and the checker's output in report.schema.json. This page is a summary; where the two disagree, those files win.

What a site publishes

Part Where it lives What an agent gets
Editing instructions AGENTS.md at the root of the source folder The layout, the rules, the output folder to leave alone, and how to check a change.
Content schemas content-schemas.json at the root of the source folder, with the JSON Schemas it names The keys each configuration file and each kind of page accepts.
Source map /sourcemap.json at the root of the output folder The source file, and the line, behind each built page, heading, and link.
Agent-skills index /.well-known/agent-skills/index.json in the output The skills the live site offers, including the one that describes how to edit it.
Edit prompts data-source on headings, data-edit-prompt on a control A prompt such as Edit docs/intro.md:23, built from the page the person is reading.
Text direction dir on the root element and on mixed-direction runs Whether the page is right-to-left, in the markup rather than only in the author's head.

Editing instructions and schemas

AGENTS.md is for whoever edits the site, not for whoever develops the generator or the theme. It names the folder content lives in, the output folder agents must not edit, and the content-schemas.json index. Its relative paths must still exist, and a "Never" or "Do not" section lists the edits that break the site.

content-schemas.json maps source paths to schemas. Each entry names a glob, a target (front-matter for the YAML block at the top of a file, file for the whole file), and a JSON Schema — a path inside the source folder or an https URL. A file that matches several entries must satisfy all of them. Every configuration file must match a file entry and every content file must match a front-matter entry.

The source map

/sourcemap.json follows the source map format, with its schema in schema/sourcemap.schema.json. At L0 and L1 it lists each page's url and source. At L2 each page also carries sections and links, so an edit can name a heading's line and a link's exact target. Each section's id is a heading id on the built page, and each source and url must resolve to a file.

The agent-skills index and edit prompts

/.well-known/agent-skills/index.json is a JSON object whose skills array lists what the site offers, each with name, description, and url. At least one skill describes editing the site: its SKILL.md gives the site repository's absolute https URL and names AGENTS.md.

A heading listed in the map carries data-source="<source>:<line>", so a control, or any tool reading the page, can build a prompt. The prompt names the source path, the line, and the section's current text, and nothing else from the page. It may copy itself or open a destination the person chooses; it never sends the prompt or page content on its own. A control that needs JavaScript is hidden in the served HTML and shown by its script.

Right-to-left text

A page whose lang is a right-to-left language has dir="rtl" on its root element, and one that is not does not. In the title, each h1, and each link inside a nav, a run of one direction inside text of the other is isolated in a bdi element, an element with dir, or between isolate marks. Both are SHOULD requirements: a failure is a warning, not a lower level.

Levels

The levels are cumulative: a site reaches a level when it meets every MUST of that level and of every level below it. A SHOULD that fails is a warning and never lowers the level. L3 is the highest level.

Level Adds An agent can
L0 AGENTS.md and a page-to-file map find the file behind any page and the rules for editing it.
L1 content schemas write front matter and config that the site accepts.
L2 section-to-line maps and edit prompts edit the exact line a person points at.
L3 the agent-skills index find all of the above from the live site alone.

Every requirement has a stable id such as ae.sourcemap.present, a keyword (MUST or SHOULD), a level, a scope (source, output, or both), a rationale, and a check, which says how a checker decides it without network access. The one exception is the https part of ae.schemas.resolve, which runs only when the checker's network option is on. An id that changes meaning gets a new id; a removed id is never reused. The keywords are read as defined in RFC 2119 and RFC 8174.

Two L2 requirements — ae.edit-prompt.content and ae.edit-prompt.no-send — are review checks. A person decides them, and a checker reports them as not run.

How a checker reports

The doctor runs every automated test on the source folder and, with --build <dir>, on the built output. Each test ends as pass, fail, or not-run. A test that needs the output folder fails when no output folder is given, because the site has not shown that it meets it.

The report follows report.schema.json: spec, version, generator, level (L0 to L3, or null when an L0 MUST fails), notRun, tests, and findings. A finding has the test id, a severity (error for a failed MUST, warning for a failed SHOULD), a message, and when known the file, line, column, key, allowed, and fix. A finding on a built page that the source map covers names the source file instead, at the line of the section it is about, and keeps the built file in output, so an agent edits the source and not the output. A shortened report, at L1 because an L2 MUST fails and the two review checks are not run:

{
  "spec": "agent-editable",
  "version": "0.1",
  "generator": "unknown",
  "level": "L1",
  "notRun": ["ae.edit-prompt.content", "ae.edit-prompt.no-send"],
  "tests": [],
  "findings": [
    {
      "id": "ae.sourcemap.ids",
      "severity": "error",
      "in": "source",
      "file": "docs/intro.md",
      "line": 6,
      "key": "install",
      "message": "is an h2, the map says h1",
      "output": { "file": "docs/intro/index.html" }
    }
  ]
}

--format json prints that report, and --format sarif prints SARIF 2.1.0 for code scanning: each test is a rule, with the test id as ruleId, the severity as the result's level, and the file and line as its location.

Where the files live

Artifact File
The spec, requirement by requirement spec/agent-editable/0.1.md
The levels and how a checker reports one spec/agent-editable/levels.md
One test per requirement spec/agent-editable/tests.json
The checker's report spec/agent-editable/report.schema.json
The content-schema index schema/content-schemas.schema.json
The source map format and schema spec/sourcemap/v0.md and schema/sourcemap.schema.json

The spec and tests.json change together: a test in this repository fails when an id, level, keyword, or scope differs between them. Version 0.1 is a draft and may change without notice until 1.0; a requirement id that exists in 0.1 keeps its meaning in 1.0 or is retired, never reused.

In Slipway's own build

The engine writes /sourcemap.json, a Markdown twin of each page (the same address with .md in place of the HTML file), and an AGENTS.md for the built site. A site that ships one of the root files the engine generates — llms.txt, llms-full.txt, robots.txt, or sitemap.xml — keeps its own copy byte for byte; without one, the generated file is used.

Start with the configuration reference and the front matter keys, then install Slipway and build a page. The doctor checks the result against the spec and prints the level it reaches.

View Markdown

Use with an agent
View Markdown

Open in