AGENTS and Skills

AGENTS.md and Skills

Two ways to teach ChatGPT how your project works. AGENTS.md says what's always true of the project. A skill says how to do one recurring task well, and is only read when that task comes up.

---

AGENTS.md

A project's AGENTS.md is how it tells an agent its own conventions — which test command to run, which files not to touch, how commits should look. Codex reads it before the first turn; so does Codex Free, using the same algorithm as Codex.

Discovery

• Single-project mode: discovery walks up from --work-dir to the nearest directory holding a root marker (.git by default), then collects one doc per directory on the way back down — so a monorepo's root conventions arrive before the subdirectory's. If no marker is found above, only the work directory itself is checked.
• Multi-project mode: the selected directory is treated as the exact project root; discovery never reads an access-root parent, so one sibling project's instructions can't leak into another session.

In each directory, AGENTS.override.md wins over AGENTS.md, which wins over anything in projectDoc.fallbackFilenames. Files are concatenated outermost-first under a shared 32 KiB budget (counted in bytes); a file that runs past what's left is cut there and reported as truncated, and whitespace-only files are skipped for free.

How the model receives it

• instructions carries the doc inline, behind Codex's own --- project-doc --- separator. Everything past that marker is the project speaking, and it outranks the agent brief above it.
• get_project_doc returns the identical text for clients that never read instructions, plus the absolute path of every file it came from and whether each was truncated.

Instructions are built per MCP session, so editing AGENTS.md takes effect on the next connection — no restart.

Configuration

The projectDoc block (maxBytes, fallbackFilenames, rootMarkers) — see Configuration. Note the one bounded read-above---work-dir exception in Security Model.

---

Skills

AGENTS.md says what's true always. A skill says how to do one recurring task well — cut a release, review a PR the way this team does, debug the flaky suite — and is only read when that task comes up. Codex Free ports the format and discovery from Codex.

The format

A skill is a directory holding a SKILL.md whose YAML frontmatter names it and says when it applies:

.agents/skills/
└── release/
    ├── SKILL.md
    ├── references/versioning.md
    └── scripts/tag.sh

---
name: release
description: Cut and publish a release of this project
---

1. Check `cargo test` and `cargo clippy` are clean.
2. Bump the version in `Cargo.toml`.
3. Run `scripts/tag.sh`; see `references/versioning.md` for what the tag must look like.

description is required — it's the only thing the model sees before deciding whether the skill is worth reading. name defaults to the directory name. A skill whose frontmatter can't be used is reported by skills_list rather than silently dropped.

Where skills are found (precedence order)

Scope	Directories
repo	.agents/skills, .codex/skills, .claude/skills, in every directory from the project root down to the work directory.
user	~/.agents/skills, ~/.codex/skills, ~/.claude/skills, or whatever skills.dirs names instead.
plugin	Installed Claude Code plugin skills, namespaced <plugin>:<skill> (e.g. idasql:decompiler). Highest installed version wins.

Repo skills come first, so a project decides how a name behaves inside it; a personal skill of the same name is shadowed and skills_list says so.

Progressive disclosure

The catalogue — a name and description per skill — goes into the brief under a ## Skills heading (at init in single-project mode; from get_agent_brief after selection in multi-project). Bodies aren't loaded until a skill is chosen: skills_read fetches one only then. That's what makes a large library affordable on a small context window. The section is omitted entirely when nothing is installed.

Reaching a skill's other files

Reference files, scripts, and assets are read with skills_read and the skill's name, passing the file's path as resource. read_file won't do — it's confined to the active project root, and user/plugin skills live in your home directory. Paths inside a skill are relative to the skill's own directory, and a resource that tries to leave it is rejected. Reading a SKILL.md lists the package's other files.

Configuration

The skills block (enabled, dirs, includePlugins) — see Configuration. Discovery runs per MCP session, so adding a skill takes effect on the next connection.

---

See also

• Context and Memory — the task-in-flight side of "what the model knows."
• How It Works — where both land in the initialize handshake.