A few months ago I caught myself writing the same lines three times over. "We use pnpm, not npm." "Tests run with make test, not pytest." "Don't touch migrations without asking." In Claude Code that went into one file, in Codex another, and when I opened Antigravity it had its own place for the very same sentences. Same context, three different filenames.

The deeper I dug, the more it resembled something from a different discipline entirely: onboarding a new teammate. You don't hand a new hire the whole wiki on day one. You tell them the few things they need to keep in their head at all times, and you let them open the specific manual when a task calls for it. That is exactly what these files do, only for an agent.

CLAUDE.md is how Claude Code remembers a project between sessions. Every session starts with an empty context window, and CLAUDE.md is the text loaded at the top of each conversation — build commands, conventions, "always do X" rules. The files are hierarchical: a user level (~/.claude/CLAUDE.md), a project level at the repo root, files deeper in the tree, and a personal CLAUDE.local.md that stays out of git. Claude Code walks up the tree from your working directory and concatenates everything it finds — additive, not overriding — and it supports @import references to other markdown files. The details are in the Claude Code memory docs.

The nuance worth holding onto: this is context, not law. Claude reads CLAUDE.md as guidance and follows it most of the time, but doesn't execute it mechanically — so if something must happen before every commit, the honest move is a hook, not a line of markdown. There's also a second, complementary system, auto memory, where the agent keeps its own notes across sessions. One file you write; the other it writes.

AGENTS.md attacks the same problem from the other end: instead of one file per tool, a single open format for all of them. Plain markdown, no required fields, no frontmatter — a "README for agents." It caught on — 60,000+ projects, read by 30+ agents, and the format is now stewarded by the Agentic AI Foundation under the Linux Foundation. In a monorepo the nearest file wins; an explicit chat prompt overrides whatever is written.

The three tools line up like this. Claude Code is native to CLAUDE.md, but AGENTS.md slots in easily — often through a single @import line, or by keeping one AGENTS.md and symlinking. OpenAI's Codex reads AGENTS.md as its primary mechanism: a global ~/.codex/AGENTS.md plus a repo-root file, with AGENTS.override.md for local exceptions; Codex's own repository ships 88 of them. Google's Antigravity — the agent-first IDE that came out of the Windsurf acquisition — checks AGENTS.md first, then GEMINI.md, then its built-in defaults, with workspace rules in .agents/rules/.

# AGENTS.md
 
## Setup
- Use pnpm, not npm.
- Run `make dev` to start the local stack.
 
## Tests
- Run `make test` before every PR.
 
## Conventions
- No default exports.
- Touch DB migrations only after asking.

Skills are a different axis altogether. CLAUDE.md and AGENTS.md tell the agent what the project is — context that stays loaded. A Skill tells the agent how to do one specific thing, and loads only when needed. This is Anthropic's Agent Skills format: a folder with a SKILL.md (YAML frontmatter carrying name and description) plus optional scripts, references, and templates.

The mechanism is called progressive disclosure, and it's the cleanest illustration of the whole idea. At startup the agent loads only each Skill's name and description — a few dozen tokens. The full body enters context only when the description matches the task; the scripts and extra files only when a specific step asks for them. The format is identical across tools — only the paths change: ~/.claude/skills/ for Claude Code, .agents/skills/ for Codex and Antigravity, .gemini/skills/ for Gemini CLI.

---
name: release-notes
description: Use when the user asks to draft release notes from a git log.
---
 
# Release notes
 
Group commits by type, lead with user-facing changes,
keep each line under 80 chars.

This is where psychology and engineering meet, which is my favourite kind of overlap. A context window is working memory, and working memory is finite — for the model as much as for a person. You can't hold 200 rules equally "lit up" at once; the more you pile on, the more adherence blurs, which is exactly why the official advice is to keep CLAUDE.md tight. From the engineering side it's an old friend: load order, concatenation versus override, scoping — the same configuration hierarchy we already run in code (env over file over defaults), just written in plain language.

CLAUDE.md and AGENTS.md are the handbook a new colleague keeps in their head. Skills are the folders on the shelf they pull down only when the task demands it. Good onboarding — for people and for agents alike — isn't dumping everything at once; it's arranging what should be within reach, and when.