Skip to main content
AGENTS.md is a plain Markdown file that a coding agent loads at the start of every session. Codex, Cursor, Copilot, VS Code, Zed, Aider and many others read it. It is the one agent surface that costs context in every session, so DeckTalk’s is four short paragraphs and points at the instruction set rather than repeating it. The reason is the shape of the product. The command line is the instruction set, the settings and the page attributes are what it changes, and the agent is the implementer. A fact copied into AGENTS.md is a fact that can disagree with the tool, and a fact the agent reads from decktalk schema cannot.

​
What decktalk init writes

decktalk init DIR writes AGENTS.md only when the directory has none, and it never replaces one that is already there. The project’s title fills the heading.
AGENTS.md
The first paragraph orients. The second names the calls. The third is the one rule the file states, which is about money, and the fourth says where the craft lives. There is no other procedure in it, because a procedure loaded in every session is paid for in every session, and that is what the packaged skills are for. The spend rule is the exception because a harness that loads no skills meets no other guard, and the refusal it would otherwise read names the flag that spends.

​
The four calls that tell an agent everything

Every fact about DeckTalk is published by one of these four calls. The first prints the help as text, and the other three print JSON. Three more names narrow decktalk schema to one document: decktalk schema page prints every page attribute, decktalk schema cues prints the shape of cues.json, and decktalk schema finding, error and event print the three shared models. decktalk schema NAME also takes a command name and prints that command’s result.

​
What an agent should do with it

Read AGENTS.md, then run the four calls, then act. In practice that is one ordering.
  1. Run decktalk status --json to learn the project’s name, its script, its cue file, every section with what is voiced, recorded and cut, and the next field, which is the whole command to run next. It is null when the film is built and measured, and null when the takes directory holds none of the project’s takes, which a warning line on stderr says.
  2. Run decktalk check --json before anything that spends. It judges the written files and the pages, makes no film, and its cost object prices the narration a voiced build would buy. The score is not in it: decktalk score --no-spend --json prices that.
  3. Dispatch on findings[].code, and read location.file and location.line to know what to open.
  4. Load a skill from .agents/skills/ when the change needs craft rather than a flag.
An agent that needs a setting reads decktalk config explain KEY rather than guessing, because the published range is the safe range and the loader refuses a value outside it, naming the file and the line.

​
Adding DeckTalk to an AGENTS.md you already have

A project that already has an AGENTS.md keeps it untouched, so the DeckTalk lines are yours to add. Add a heading of your own and the four paragraphs above under it, and leave the rest alone. The file is read as plain Markdown, so a heading and a paragraph are enough. Keep the same discipline in your own file. Name the calls, and do not copy a flag, a default or a finding code into prose that nothing regenerates.

​
Harnesses that read a different file

Claude Code reads CLAUDE.md rather than AGENTS.md. The usual arrangement is a CLAUDE.md whose whole content is a line pointing at AGENTS.md, so one file stays the source. Gemini CLI reads GEMINI.md by default and reads AGENTS.md when its context file setting names it. AGENTS.md also serves a harness that loads no skills at all. For that harness it is the only DeckTalk instruction in the session, which is why it names the calls rather than describing the pipeline. The reference card is the page to hand such a harness next.

​
The repository’s own AGENTS.md

The DeckTalk repository carries an AGENTS.md of its own, and it describes the tool’s source rather than a project. It opens with the same four calls, and then it carries the command tree in a block between two markers, written as Markdown comments so that a reader never meets them. The opening one reads commands: generated by scripts/build_agents_doc.py and the closing one reads end commands, and the script refuses to run when either is missing. That block is written from the same walk over the parser that decktalk schema prints, so the list of commands in the file cannot drift from the list of commands in the code. Everything around the markers is prose written by hand. uv run scripts/build_agents_doc.py --write writes the block and --check exits 1 when the committed one would change, which is what the repository’s own checks run. uv run scripts/check.py --group generated --write runs it with every other generator, in one command. An agent working on DeckTalk itself edits the prose and never the block.