Primary navigation

Custom instructions with AGENTS.md

Supply ZeroTwo with additional guidance and background about your project

ZeroTwo reads one instruction file from your project and one from your global ~/.zerotwo/ folder before Work and Code tasks start, so every task begins with the same ground rules.

How ZeroTwo discovers guidance

Each location is checked for three file names, in this priority order: ZEROTWO.md, AGENTS.md, CLAUDE.md. The first file that exists with non-empty content is used in full, and the others in that location are ignored. Files are never merged within a location. The two locations are the global folder ~/.zerotwo/ and the root of the project folder, and when both have a file, both are shown to the agent, global first. ZeroTwo reads only the project root, so it does not walk down through subfolders collecting nested files.

A line that contains only @path is replaced by that file's contents. Paths can be relative to the including file, start with ~/, or be absolute. Cloud runs apply the same three names to the repository cloned into the sandbox.

Create global guidance

Put personal defaults in ~/.zerotwo/AGENTS.md (or ZEROTWO.md), such as running tests after a code change or asking before adding a dependency. This file is separate from Settings > Personalization > Companion > Custom instructions, which is a profile field that applies to chat in general. Settings > Import can copy global instructions from another agent into ~/.zerotwo/AGENTS.md, but only when that file does not exist yet.

Layer project instructions

Add a root AGENTS.md with repository norms. To write one, run /init in a Code or Work task in the desktop app. It asks the agent to analyze the codebase and create an AGENTS.md at the repository root, or to improve an existing AGENTS.md or CLAUDE.md in place. If a ZEROTWO.md exists at the root, it takes priority over AGENTS.md, so rename or merge the two to avoid hiding one.

This layout shows which files are used. Highlighted files are loaded, and the nested one is not read because only the project root is checked.

  • ~/.zerotwo/
    • AGENTS.mdGlobal defaults, shown first
  • my-project/
    • AGENTS.mdProject norms, shown second
    • services/
      • AGENTS.mdNot read (root only)

Verify your setup

Ask the agent to summarize the instructions it was given, and confirm that the global and project files both show up. ZeroTwo watches instruction files and refreshes them while a session is open, so a restart is not needed after an edit.

Troubleshoot discovery issues

  • Nothing loads: confirm the file sits at the project root, or in ~/.zerotwo/ for global guidance, and that it is not empty.
  • Wrong guidance: check for a higher-priority file such as ZEROTWO.md, which hides AGENTS.md and CLAUDE.md.
  • An include does not expand: the @path must be alone on its line and the target must be readable; a missing target is left as written.

Next steps