AGENTS.md generator

How to generate AGENTS.md and CLAUDE.md

Three steps, all on this page. Nothing is uploaded, and there is no account — the generator is a small script running in the tab.

1. Describe the project. Name, type, stack, and the commands an agent has to get right: install, build, test, lint. Then the rules your code reviews keep repeating, one per line. Both files update as you type.
2. Pick the agents you actually run. Claude Code, Codex, OpenClaw, Pi. The MCP section is written once per agent in the file that agent reads, and the table underneath tells you where that agent will look for it.
3. Copy both files to your repository root. AGENTS.md and CLAUDE.md each have their own copy button. Commit them together, because nothing keeps them in sync for you unless you take the one-line import option.

Which agent reads which file

AGENTS.md and CLAUDE.md are two names for one idea — a Markdown file of project instructions that a coding agent loads before it does anything — and no agent reads both of them by default. That is why this page hands you two files rather than one. The table was checked on 4 September 2026 against four agents installed side by side, by reading the context loader inside each shipped build rather than trusting a docs page.

Four things follow from that table, and none of them show up in a plain template.

• Claude Code does not read AGENTS.md. Its context loader looks for CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md and nothing else; the name AGENTS.md appears nowhere in it. Where the name does turn up in the shipped build, it is being copied: a Codex import that writes ~/.codex/AGENTS.md into ~/.claude/CLAUDE.md and a project AGENTS.md into CLAUDE.md, and a setup routine that reads an existing AGENTS.md as source material while it drafts your CLAUDE.md. A copy taken once is not a file being read every session.
• Codex will not read CLAUDE.md unless its user says so. Its config exposes project_doc_fallback_filenames, and the default is an empty list. Someone can add CLAUDE.md to it in their own ~/.codex/config.toml — but that is a setting on their machine, not something your repository can ship to a contributor.
• Pi is the only one that takes either. Per directory it tries AGENTS.override.md, then AGENTS.md, then CLAUDE.md, and stops at the first file it finds. So a repo with both gives Pi the AGENTS.md — the CLAUDE.md never loads there.
• OpenClaw does not look in your repository at all. Its instruction file is a workspace bootstrap file, next to SOUL.md and IDENTITY.md in ~/.openclaw/workspace/. Dropping AGENTS.md into a checkout does nothing for it; you paste the content into the workspace file instead.

The skills column is the part that is shared. Claude Code keeps skills under its own directory, while Codex, OpenClaw and Pi all read the open ~/.agents/skills path — which is why clize install writes two blocks, one per directory, and why installing Clize once covers all four agents even though their instruction files do not.

Two files, one source of truth

Maintaining the same paragraph twice is how the two files start disagreeing, usually about a build command that changed in one of them. There are three honest ways out, and the generator supports the first two.

Keep both files in full. This is the default output above, and it is the only option that works identically for every agent, on every machine, with no local configuration. The cost is real: you have to change both in the same commit. Both generated files end with a section that says so, so the next person editing one is told the other exists.

Make CLAUDE.md a one-line import. Claude Code understands @path/to/file lines in CLAUDE.md and inlines the file they name, so a CLAUDE.md whose body is @AGENTS.md gives Claude Code the same instructions with only one file to edit. Tick the import box in the panel and the CLAUDE.md pane collapses to that. The catch is that the @ line is Claude Code syntax, so the substance has to live in AGENTS.md — which is exactly where the other three agents want it anyway.

Or fix it on the reading side. A Codex user can add CLAUDE.md to project_doc_fallback_filenames; a Pi user gets the fallback for free. Neither travels with the repository, so treat it as something you do for your own checkout, not as a policy you can rely on for contributors. If you are weighing the two hosts more broadly, the differences between Claude Code and Codex go well past a filename.

What belongs in the file, and what does not

The instruction file is prepended to the agent's context on every session, so every line you add is a line it pays for on every task. That makes the editing rule simple: write down what the agent gets wrong, delete what it can look up.

Worth writing down: commands that are not guessable from the manifest (a non-standard test runner, a required flag, a codegen step that has to run first); rules your reviews keep repeating (no default exports, never touch generated directories, migrations are never run locally); repo etiquette (branch naming, commit style, what a PR needs before review); and environment facts that fail silently, such as a service the tests need running.

Not worth writing down: a file-by-file map of your source tree, which the agent can read faster than you can maintain; generic advice like write clean code and handle errors; standard commands the manifest already declares; and long reference material, which belongs in a linked document or a skill instead of in the context of every turn.

The line between an instruction file and a skill is worth holding: the instruction file is always loaded and describes this repository, while a skill is loaded on demand and describes a capability the agent can use anywhere. Long procedures drift into the second category quickly. Clize ships its own capabilities that way rather than as prose — see the command reference for what that looks like in practice.

The MCP section: one server, four different commands

If your project expects an MCP server, saying so in the instruction file saves a contributor a round trip — but the registration command is not the same across agents, and that is the sort of detail a generic template quietly gets wrong. Verified on 4 September 2026:

claude   mcp add clize -- clize-mcp
      codex    mcp add clize -- clize-mcp
      openclaw mcp add clize --command clize-mcp

Claude Code and Codex take the stdio command after a -- separator. OpenClaw does not use a separator at all: the command goes behind --command, and pasting the Codex form there fails. Pi is the one agent with no verified single-line form, so the generator writes a line telling the reader to register it through Pi's own MCP configuration rather than inventing a command that might not exist.

For Clize itself none of this is manual. clize install writes the skills into both directories, and clize install --mcp also registers the server with every agent it finds, using each one's own syntax. MCP is opt-in: without the flag the skill is installed and registration is skipped. Host-by-host walkthroughs live at MCP setup for Claude Code and the Codex CLI equivalent, and OpenClaw has its own page because it is the host most often left out of these lists.

$ npm i -g @clize/clize && clize install
$ clize install --mcp    # register the MCP server too