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.

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 Codexify, using the same algorithm as Codex.

• 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.

• 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.

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

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. Codexify ports the format and discovery from Codex.

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.

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.

For OpenAI Codex plugins, Codexify reads enabled [plugins."<plugin>@<marketplace>"] entries from Codex's user config.toml, resolves the same active cached package version, and follows the plugin manifest rather than assuming one fixed directory layout. Current Agent Plugin manifests use direct children under skills/; legacy manifests may declare other skill roots, which are searched recursively. Legacy migrated-command skills are included, and [[skills.config]] name/path enablement rules are honored.

Codexify also retains Claude Code plugin discovery, selecting the highest installed plugin version. skills.includePlugins: false disables both Codex and Claude plugin packages. Setting skills.dirs replaces the standalone user roots and disables plugin discovery unless includePlugins: true is set alongside it.

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.

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.

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

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