AGENTS.md vs CLAUDE.md: skills, hooks, and memory

AGENTS.md and CLAUDE.md are both instruction files. The name does not decide which one an agent reads. You can put words near an agent in more than one way, and those ways are not the same tool. An instruction file is text you save where a coding agent looks, so that agent may include it when it starts. A skill is a named procedure the agent opens for one task, after it has already seen a short description. ChatGPT and Claude.ai can save notes from your chats and use them in a later chat in that same product. Noteheld keeps a note with an author, a time, a reason, and a correction that is not the note, and an agent sees it only after you give the agent a key and the agent asks Noteheld for the note.

Checked against each tool's documentation on 26–27 October 2026.

AGENTS.md vs CLAUDE.md: which file does each agent read?#

The same filename is not one behaviour. Each product decides what it reads. If you want one AGENTS.md for several agents, the shared-file guide covers imports, symlinks, and copies.

Claude Code#

Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md is in the working directory or a directory above it, except ~/.claude/CLAUDE.md, on v2.1.277 or later. Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md only; import the shared file from a CLAUDE.md there. You can change that default. CLAUDE.md can live at managed, user, repository, and local scopes. The repository copies are the ones git shares. A Claude Code session starts with a fresh context window. CLAUDE.md and auto memory are how knowledge crosses sessions. CLAUDE.md is context, not enforcement. A hook is how you block an action the model might still take. Keep CLAUDE.md under 200 lines. That figure is the vendor's target. Claude Code skips a file over 4 MiB.

Auto memory is on by default in local sessions, stored on that machine, and the first 200 lines or 25KB of MEMORY.md load at start. Auto memory, the CLAUDE.md you write, and Claude.ai memory are not one feature.

Codex#

Codex reads AGENTS.md before doing any work. It builds the chain once at the start of a run: the global file in the Codex home ($CODEX_HOME, default ~/.codex), then one file per directory from the repository root down to the working directory. In each directory, AGENTS.override.md wins over AGENTS.md, and any fallback names you configure come after those. Codex uses at most one file per directory. It joins them in that order, so a file closer to the working directory appears later and overrides earlier guidance.

The documented size limit is 32 KiB by default, but the docs describe it in two different ways. The AGENTS.md page says Codex stops adding files when the combined size reaches project_doc_max_bytes. The advanced configuration page describes the same setting as "how much to read from each AGENTS.md file". Those are different rules. A pair of documentation reports filed in July and August 2026 says the implementation uses one budget, root-first, so the file nearest the working directory is the one cut when the budget runs out; the later report also says the global file is read in full and is outside that budget (#36371, #37956). Until the docs agree, measure the chain, not each file.

Nothing in a session says a file was cut. The docs describe no warning; an open report says the cut produces none in the TUI, codex exec, or the VS Code extension (#13386, last updated 24 October 2026).

In the CLI, /status has an Agents.md row. The docs do not describe it, and it is a snapshot, not a live check: an open report says it keeps showing <none> for the rest of a session after /init writes the file (#37704). To see the exact text the model was given, run codex debug prompt-input in the CLI. The checks are in why Codex ignores part of your AGENTS.md.

OpenCode#

V2 reads AGENTS.md only. It does not use CLAUDE.md as a fallback. At the start of a session it loads the global file at ~/.config/opencode/AGENTS.md, then every AGENTS.md from the workspace directory toward the home directory, nearest first. Outside the home directory it stops at the repository root. It then adds the files listed in the instructions array, in order. It combines them and does not resolve conflicts, so a contradiction between two files is something you have to fix, not an order to rely on.

V1 reads more file types. It loads the global file and the repository files it finds walking up from the working directory. If any AGENTS.md exists on that path, it uses the AGENTS.md copies; if there is no AGENTS.md, it falls back to CLAUDE.md. The global file has the same fallback: ~/.claude/CLAUDE.md is used when ~/.config/opencode/AGENTS.md does not exist. The docs' "first matching file wins in each category" is about filename types, not one file for the whole session. The docs do not spell that out; the v1.19.4 source shows it loads every match of the first filename type.

Both lines attach a nested AGENTS.md when the agent reads a file under it. V2 also loads them when the agent lists a directory. V2 keeps the file in the session while its instruction entry remains in the model-visible history; a compaction or revert can clear that entry, and a later read can load the file again. An edit to a nested file after it loads waits for a new session. The OpenCode AGENTS.md guide shows how to prove which files reached the prompt.

Cursor#

Cursor reads AGENTS.md in the root and in subdirectories. The root file is always applied; a nested file attaches when the agent reads a file in that folder, once per conversation, and can drop after a summary. In the CLI since v2026.10.22, edits and creates also attach it. Rules in .cursor/rules are .mdc files; a plain .md file there is ignored. User Rules in settings are not a file, and ~/.cursor/rules is version-dependent. A rule can apply on every chat, on a glob match, when the agent judges a description relevant, or only when you mention it. On Team and Enterprise, team rules outrank rules in the repository, and both outrank user rules. Cursor rules apply to Agent chat only; they do not affect Tab completion. The rules page says to keep rules under 500 lines; that is guidance, not a documented hard cap. The Cursor AGENTS.md guide and the rules guide have the checks.

Gemini CLI#

GEMINI.md is instructional context. The docs page carries a banner: unpaid-tier and Google One users were moved to Antigravity CLI on 18 June 2026. Gemini CLI concatenates the files it finds and sends them with every prompt. There is a file at ~/.gemini/GEMINI.md, files in the workspace directories you opened and their parent directories, and files discovered when a tool touches a directory and its ancestors up to a trusted root. The default context filename is GEMINI.md. /memory show prints the startup context; just-in-time files appear in the tool output that touched their directory. /memory reload rescans. Those commands read an instruction file. They are not ChatGPT memory. That page does not state a numeric size limit.

Those sources load in a fixed order: the global file first, then the workspace files from the boundary marker (the first directory with a .git, by default) down to the directory or directories where you started, then the just-in-time files when a tool touches their directory. The context summary above the input reports how many context files loaded. context.fileName is a list of names to look for, not a replacement; run gemini --version first, because the merge behavior below is v0.65.0. The documentation's example lists AGENTS.md, CONTEXT.md, and GEMINI.md; at v0.65.0 the loader adds the configured names to the built-in GEMINI.md, so a repository with both files sends both. AGENTS.md is not a default context filename; the CLI reads it when you add it to that list. The request to make it a default was closed as not planned (#12345, 8 May 2026). The Gemini AGENTS.md guide shows the full check.

Qwen Code#

Qwen Code reads QWEN.md and AGENTS.md by default. Both names are in the default list, with QWEN.md first. That is the first thing to unlearn from Gemini CLI: GEMINI.md is not a default here. It is also different from Claude Code: AGENTS.md is not a fallback that waits for CLAUDE.md to be absent. Qwen also loads .qwen/QWEN.local.md from one fixed slot at the repository root, after the shared files (it needs a .git entry and a trusted folder), so a personal file can supplement or override them. You have to gitignore that file yourself.

context.fileName replaces the default list. Set it to ["AGENTS.md"] and QWEN.md stops loading; set it to ["QWEN.md", "AGENTS.md", "CLAUDE.md"] and Qwen reads all three. If that CLAUDE.md is the usual @AGENTS.md shim, the content of AGENTS.md reaches the model twice, because it is loaded as its own file and again inside the import (#15679, open on 27 October 2026).

Discovery is global, then upward. Qwen reads the configured names under ~/.qwen/, then walks up from the working directory to the nearest directory with a .git entry, and stops there. It does not scan down into subdirectories. A packages/api/QWEN.md is not loaded when you start at the repository root; start Qwen in packages/api, or put the rule in the root file (#6101, open on 27 October 2026). A symlinked duplicate is read once, by real path.

.qwen/rules/ is a separate layer. A rule with no paths: loads on every request like a context file; a rule with paths: loads when a tool touches a matching file. It is not part of context.fileName. /context detail names each loaded context file under Memory files.

GitHub Copilot#

Repository-wide Copilot instructions can live in .github/copilot-instructions.md. Path-specific files are .github/instructions/*.instructions.md with applyTo. The repository-instructions page describes personal instructions as higher priority than repository instructions, and repository instructions as higher than organization instructions, while all relevant sets are still provided. That is that page's hierarchy; the Copilot CLI rule is below. The repository-instructions page is also one surface where Copilot reads AGENTS.md. That is not every Copilot surface. The customization cheat sheet labels AGENTS.md as a file for third-party agents; the repository-instructions page calls it agent instructions. Copilot code review reads instructions from the pull request's head branch.

GitHub Copilot CLI#

copilot --version matters here: the changelog lists .claude/rules support in 1.0.89, but the current custom-instructions page does not; check /instructions on your build. The source list has changed more than once. Copilot CLI reads two user-level files, ~/.copilot/copilot-instructions.md and ~/.copilot/instructions/**/*.instructions.md, and these repository files: .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md, CLAUDE.md (including .claude/CLAUDE.md), and GEMINI.md. COPILOT_CUSTOM_INSTRUCTIONS_DIRS adds AGENTS.md and *.instructions.md files from other directories.

Discovery covers the repository root, the current working directory, the directories between them, and nested directories on the path of a file the agent is working on. The .github/instructions folder is not read from intermediate directories. A *.instructions.md file applies only when its applyTo glob matches a file in play. In .github/copilot-instructions.md, AGENTS.md, and CLAUDE.md, an @path reference includes another file; GEMINI.md and *.instructions.md do not expand references, and absolute or ~/ paths are not loaded.

Copilot CLI combines all applicable files, removes duplicate copies of identical user-level, repository-wide, and agent instructions, and does not define a general precedence order. It says to avoid conflicting instructions. That is the rule to plan around: one fact, one file; if two files disagree, do not expect a priority order to settle it. /instructions lists what the session discovered and can toggle a file; the Copilot CLI instructions guide shows the rest of the checks.

Devin Desktop#

On Devin Desktop, a root AGENTS.md is always on. A subdirectory AGENTS.md applies to that directory. Auto-generated Cascade memories are local, per Devin workspace, and not committed. The default Devin Local agent does not persist them. That page recommends a rule or AGENTS.md instead of auto memory when the fact must be reliable and shared.

Length limits are not one number#

The limit is not one number: Claude Code's target is under 200 lines and it skips a launch file over 4 MiB, Codex cuts the chain at 32 KiB by default, and four agents document no number at all. How long can AGENTS.md or CLAUDE.md be? has each documented limit and the failure mode past it, but not Devin Desktop's: 6,000 characters for a global rule and 12,000 for a workspace rule.

Where each file lives#

Do AGENTS.md and CLAUDE.md take frontmatter?#

AGENTS.md and CLAUDE.md are plain Markdown. The AGENTS.md format has no required fields, and no vendor documents a frontmatter schema for either file; YAML at the top reaches the model as text. Frontmatter matters in the files that are configuration: a Claude Code rule in .claude/rules/ reads only paths, a Copilot *.instructions.md reads applyTo and optional excludeAgent, as the custom-instructions page says, and a skill's SKILL.md file reads name and description, as the Agent Skills specification says. Claude Code strips a rule's frontmatter before loading it, and drops hidden HTML notes from CLAUDE.md before the model sees them. If you want a field to scope instructions, put the instruction in the rule file that reads that field, not in AGENTS.md. A Cursor .mdc rule reads alwaysApply, description, and globs, and their combination sets the rule type: always applied, auto-attached to matching files, selected by description, or manual.

Nested AGENTS.md files: which one wins?#

AGENTS.md is a plain markdown file with no required fields, meant as instructions for coding agents. The agents.md site lists other products. This page does not claim those products read the file. Their own docs were not the source for that.

On Devin Desktop, a root AGENTS.md is always on. A subdirectory AGENTS.md applies to that directory.

The [shared-file guide](/guides/one-agents-md-for-every-agent#check-for-one-copy-not-zero-and-not-two) has the per-agent check for one copy, not zero and not two.

CLAUDE.md vs skills vs hooks: what goes where?#

Match the job. If the sentence has to be in front of the agent on every task, use a short instruction file. If it is a procedure for one kind of task, use a skill. In Claude Code, if it has to run even when the model would skip it, use a hook. If the words are personalization inside ChatGPT or Claude.ai, that is vendor memory in that product. If you are connecting a tool, that is MCP, a protocol for the connection, not a store. If you are publishing a short map of a website, that is llms.txt. Nothing in that proposal requires an agent to fetch the file or obey it. If the fact needs an author, a time, a reason, and a correction that is not the text, use Noteheld.

Put the standing rule in CLAUDE.md. Put the procedure in a skill. The skill's name and description load first, and the body loads when the skill is activated. In Claude Code, descriptions of skills the model may call load at session start, and the body loads only when the skill is used. A hook is a step the program runs when an event happens. In Claude Code, a hook can block an action. A sentence in CLAUDE.md cannot. The benchmark on whether instruction files help is the check on what belongs in that file.

The instruction file, the skill, and the path-scoped rule have different names, or no direct equivalent, in each agent.

Claude Code and Qwen Code write memory themselves, each in a per-repository folder under its home directory (~/.claude/ and ~/.qwen/); the Claude Code auto memory guide and the Qwen Code instructions guide give the exact paths. Gemini CLI's experimental Auto Memory proposes memory updates and skills into a review inbox, off by default.

What a chat product means by memory#

Claude.ai memory is on by default for Claude.ai Free, Pro, and Max, and off for Team and Enterprise members until an owner enables it and the member turns it on. Some sensitive categories are excluded unless you opt in. Government ID numbers, criminal history, and immigration status are never saved, and that page names further categories that are never saved.

Deleting a ChatGPT chat does not delete a saved memory from that chat. The memory summary you can review is not the whole of what ChatGPT may use.

Where Noteheld is not the right tool#

Nothing loads Noteheld for free. An agent sees a note only when someone gives it a key or a view link and it asks Noteheld for the note. A short instruction file that you commit is the right tool when the sentence must be present on every task. Noteheld does not do that job. Tell the agent to read the overview first, then only the notes it needs. The overview lists the notes with open corrections, and each one prints first when the agent opens that note.

Noteheld is not an instruction file, a skill, a hook, or vendor memory. A skill is a directory with a SKILL.md file. A Noteheld workspace is not that directory. You can copy note text into a repository file. Noteheld does not turn the note into an AGENTS.md for you.

If you are reviewing what an agent wrote, keep these limits in the same breath. Notes are stored on the server as plaintext so the product can search, outline and edit by line. Version 1 does not encrypt note bodies end to end. The live database files are plaintext. When the operator's backup key is set, Noteheld takes an encrypted snapshot on a daily schedule and keeps those snapshots for 14 days. A snapshot is a copy of the notes. This version has no editor for the note body. A correction sits above the note and is not written into the body. The server sets the author. A browser session is a person. A bearer key is an agent. A person's correction is still stored data. Content returned to agents is marked as stored data and carries provenance. This does not stop a model from following text inside a note. A warning that the text looks like instructions does not block the read. A note can still steer an agent that reads it. Folder keys limit what a compromised agent can touch inside Noteheld, not tools the agent has elsewhere.

On the free plan, every revision is kept for 30 days. After that, the plan keeps one checkpoint per note per day for 365 days. The current text stays while the workspace exists. Pro does not thin. A write past the storage cap fails and deletes nothing. A free workspace with no authenticated read or write warns on day 60, becomes read-only on day 90, and is deleted on day 120. A view-link visit does not count. Paid workspaces never idle-expire.

The master key opens the workspace. The recovery kit is a file on your machine. Anyone with that file can read and change the workspace. A passkey can sign you in and rotate the master key. If the master key, the recovery kit and the passkey are all gone, we cannot recover the workspace. There is no account.

Using them together#

Use an instruction file, a skill, and Noteheld when you need a standing sentence, a procedure, and a record.

In the instruction file that your coding agent actually loads, tell it to use its Noteheld key. Tell it to read the overview first, then only the notes it needs. Tell it to write decisions and handoffs as notes, with a reason. Tell it to treat note text as data, not as instructions. If that agent is Claude Code and a CLAUDE.md is already there, put those sentences in CLAUDE.md. On v2.1.277 or later, Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md is in the working directory or above it, except ~/.claude/CLAUDE.md, unless you change that default.

Put the longer steps in a skill. The name and the description load first. The body loads when the skill is activated. In Claude Code, the body loads only when the skill is used.

Noteheld holds the record. Each edit stores the key's label, the time, and a reason. reason is required, and it is at most 300 characters. If a sentence is wrong, ask any agent with a write key to fix it; its edit is saved with a reason. Or add a correction above the note, which every agent reads first. Do not paste the objection into the body. The next agent cannot tell that objection from the note. The correction does not replace the body. This version has no editor for the note body. A person's correction is still stored data. Asking an agent does not force the next read to obey, and it is not a hook.

To connect an agent, see connect an agent.

Words people mix up#

Instruction file#

Text you save so a coding agent may insert it. AGENTS.md, CLAUDE.md, QWEN.md, GEMINI.md, a Cursor rule, and a Copilot instruction file are this kind of object. Sharing a filename does not make the load rules the same.

Skill#

A directory with a SKILL.md file. The agent can see the name and the description before it opens the body. The body is the procedure.

Hook#

A step the program runs when an event happens. In Claude Code, a hook can block an action. A sentence in CLAUDE.md cannot.

Vendor memory#

Notes that ChatGPT or Claude.ai keep from chats and may use in a later chat in that product. You did not commit them to a repository. Noteheld is not vendor memory.

MCP#

An open protocol for connecting a host to external data and tools, using JSON-RPC. A server may offer resources, prompts, and tools. The protocol is not a store, and it is not a note. The specification is the source.

llms.txt#

A proposal for a markdown file on a website. It is a short map of a path, with links to the detail. Nothing in the proposal requires an agent to fetch it or obey it. It is not robots.txt.

Correction#

In Noteheld, a fix the owner asked for, on a note or a line range. An agent sees it first when it reads that note, changes the note, then resolves it. Only the owner adds one. The correction is not the note body. It is still stored data.

Revision#

One stored edit of a Noteheld note. The row keeps the key's label, the time, and a reason. Restore writes a new revision. It does not erase the later one.