Working with AI agents

Page content:

An AI agent can write a Postdoc site the way a person does: its pages are Markdown, its layouts are HTML, and nothing has to be compiled by hand. What an agent can't do on its own is see whether a page works. These commands tell it, without a person looking, and each answers in a form a program can read.

Tell the agent how the project works

A project made with postdoc init has an AGENTS.md at its root, which many agents, such as Codex, read before they start. It says where pages, layouts and public files go, which commands to run, and what to check before a change is done. Claude Code reads CLAUDE.md instead, so the project has one of those too, with a single line that imports the other: @AGENTS.md. Change them to suit your project.

For a project of your own, put the same in your AGENTS.md or CLAUDE.md, along these lines:

AGENTS.mdmd
## Before you call a change done

1. `npx postdoc check` passes.
2. You've looked at the pages you changed with `npx postdoc screenshot`, at a wide and a narrow width, and in dark mode.
3. `npx postdoc test --pages` on those pages passes.

A quick check after each change

sh
npx postdoc check

In a second or two, without a browser or a build, it compiles every page, drafts included, and follows every link between them. It reports:

  • settings of 0.3.0-preview4 that Postdoc still reads, such as directories.content, as warnings, which don't fail the check
  • an output folder that holds the project's own files, which a build would delete
  • pages that can't be compiled: a missing layout, front matter or a storymap that isn't valid, an error in a layout
  • links to pages that don't exist, and to ids that their page doesn't have, such as a heading that was renamed
  • pictures that aren't files of the site

It exits with 1 when it finds a problem. With --json, it prints them as JSON instead:

json
{
  "pageCount": 44,
  "linkCount": 1778,
  "problems": [
    {
      "kind": "link",
      "page": "/index.html",
      "url": "/guide/a.html#postdoc-nope",
      "message": "links to /guide/a.html#postdoc-nope, but /guide/a.html has no element with the id \"postdoc-nope\""
    }
  ],
  "warnings": []
}

Look at a change

An agent sees a page in a screenshot. Run the dev server on a port of the agent's own, so it doesn't take the place of one you have running, and take screenshots of the pages it changed:

sh
npx postdoc run --port 5180
npx postdoc screenshot /guide/install.html --url http://localhost:5180 --width 1280,390 --theme light,dark

--port fails rather than moving to the next port when the one asked for is taken, so the agent knows where its server is. postdoc screenshot waits until each page has finished rendering, switches dark mode on the way the page checks do, and prints the path of each PNG file it writes. --selector takes a picture of one element, and --full-page of the whole page. Without --url, it builds the site and serves the build. It needs Chrome, and Nightwatch in the project.

Check the pages in a browser

postdoc test takes minutes for a whole site, so an agent checks the pages it changed:

sh
npx postdoc test --pages '/guide/install.html' --widths 1280,390 --report checks.json

The report has each problem with the page, the width and the check that found it, and the problems grouped, so one in a footer is one entry with the pages it's on:

json
{
  "pages": ["/guide/install.html"],
  "widths": [1280, 390],
  "skipped": [],
  "checked": 2,
  "complete": true,
  "problems": [
    {
      "page": "/guide/install.html",
      "width": 1280,
      "check": "keyboard",
      "message": "Keyboard: Links that go nowhere. Use a button for an action, or link to an address (1)",
      "elements": ["footer a.social (\"Twitter\"): href=\"#\""],
      "link": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#onclick_events"
    },
    {
      "page": "/guide/install.html",
      "width": 390,
      "check": "keyboard",
      "message": "Keyboard: Links that go nowhere. Use a button for an action, or link to an address (1)",
      "elements": ["footer a.social (\"Twitter\"): href=\"#\""],
      "link": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#onclick_events"
    }
  ],
  "groups": [
    {
      "check": "keyboard",
      "message": "Keyboard: Links that go nowhere. Use a button for an action, or link to an address (1)",
      "elements": ["footer a.social (\"Twitter\"): href=\"#\""],
      "link": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#onclick_events",
      "pages": [{ "page": "/guide/install.html", "width": 1280 }, { "page": "/guide/install.html", "width": 390 }],
      "browsers": []
    }
  ]
}

Keep your build

postdoc build, postdoc preview and postdoc test build into the output folder, out/ by default. --out-dir builds somewhere else, so an agent's build leaves yours as it is:

sh
npx postdoc build --out-dir /tmp/site

Pages that agents can read

Builds write an llms.txt at the root of the site, which lists its Markdown pages, and a copy of each one beside its HTML, such as /guide/install.md beside /guide/install.html. An agent reads those more easily than the pages, and so does any tool that wants the text without the layout. The copies are the pages as they were written, without their front matter.

postdoc.config.jsjs
export default {
  llms: {
    // A line about the site, at the top of llms.txt. Defaults to appSettings.description.
    description: 'Docs for Acme, the rocket-powered roller skates.',

    // Set to false to leave them out.
    enabled: true
  }
};

Nothing waits for an answer

Commands don't ask questions that an agent can't answer. Without a terminal, postdoc init stops with an error if it isn't given --name, rather than wait for one. Every command exits with an error code when it fails, and so does a build that had to leave a page out because it couldn't be compiled. The banner that commands start with is only shown in a terminal, so postdoc check --json can be piped straight into another program.

Edit this page on GitHub