Instructions

Project and global instructions loaded at startup.

An AGENTS.md file holds standing instructions for the agent: coding conventions, package managers, framework rules, things to always or never do. zot loads them at startup and prepends them to the system prompt. No file is created or required; zot only includes the ones that already exist.

Load order

Global instructions in $ZOT_HOME/AGENTS.md are loaded first. Then project instructions are loaded from the top-most parent directory down to the current working directory. Later files are more specific and may override earlier ones.

$ZOT_HOME/AGENTS.md (global, applies everywhere)
<repo-root>/AGENTS.md (project-wide)
<subdir>/AGENTS.md (closest to cwd wins on conflicts)

Per directory, zot reads the first of AGENTS.md or AGENTS.MD it finds. Empty files are skipped. Changing the working directory (for example via the swarm) reloads the set for the new cwd.

Only AGENTS.md

zot reads instruction context from AGENTS.md only. It does not load CLAUDE.md or other vendor instruction files. (The Claude- and agent-compatible layouts zot understands are for skills, under .claude/skills/ and .agents/skills/, not for instructions.) If you keep rules in a CLAUDE.md, point an AGENTS.md at it or copy the content over.

Example

AGENTS.md

# Project rules

- Use the package manager that matches the lockfile.
- Never start the dev server; run typecheck, lint, and build instead.
- Keep answers short and substantive.
- Do not use em-dashes in any text you write.

Reach for AGENTS.md when you want rules that travel with a repository and apply to every session. Reach for SYSTEM.md when you want to replace zot's core identity outright.