SKILL.md vs AGENTS.md
When a task-specific SKILL.md applies versus a repository-wide AGENTS.md, with what we tested on Codex and what is documentation.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
- Words
- 794
How far we checked this page
Signed by Arun Kumar, Sep 27, 2026. Passing one check says nothing about the next.
- FormatNot checkedThe file format was not checked for this page.
- InstallsNot checkedInstallation was not checked for this page.
- LoadsChecked on Codex onlySKILL.md discovery and invocation confirmed hands-on on Codex CLI 0.157.1, at both .agents/skills and .codex/skills project paths. AGENTS.md loading and precedence were not tested by us on any host.
- Codex, checkedcodex-cli 0.157.1 · Sep 27, 2026
- Claude Code, not checkedNo live Claude Code comparison was run.
- Cursor, not checkedCursor was not installed in the test environment.
- HelpsNot checkedA with/without task comparison was not run.
SKILL.md defines a task-specific skill that a compatible agent may discover and load when it’s relevant to the current task. AGENTS.md is a plain-Markdown convention for repository-wide working instructions (setup commands, code style, test conventions) that a host typically reads at the start of a session, with some hosts also loading nested copies later as work reaches those directories. They solve different problems and commonly sit side by side in the same repository. Which one a given host reads, and when, is host- and version-specific, as of September 2026.
Choose SKILL.md when
- The instructions only matter for one kind of task, and shouldn’t take up context on every turn.
- You want a portable format: the Agent Skills specification defines
nameanddescriptionfrontmatter that multiple hosts recognize. - You want optional supporting files (
references/,scripts/,assets/) loaded only when needed.
Choose AGENTS.md when
- The instructions apply to the whole repository, every time an agent works in it: build commands, test commands, code style, directory conventions.
- You want one plain-Markdown file with no required schema, readable by any agent that supports the convention. agents.md lists Codex, Cursor and GitHub Copilot among the hosts that do.
- You need nested, directory-specific guidance: Codex in particular reads project
AGENTS.mdfiles from the repository root toward the working directory.
Worked example
A repository has a root AGENTS.md that says “run the test suite before committing, use two-space indentation,” plus a project skill at .agents/skills/explain-error/SKILL.md for one specific task: reading a pasted traceback and giving a fix.
On Codex CLI 0.157.1, we confirmed hands-on that the skill side works as documented. Asked to list its available skills, Codex’s discovery listing included explain-error alongside its description. A Python AttributeError traceback triggered it: the tool trace showed cat .agents/skills/explain-error/SKILL.md and cat .agents/skills/explain-error/references/checklist.md, and an unrelated prompt (“write a haiku about tea”) did not. Codex’s own docs describe it reading AGENTS.md separately, from the repository root down, with a default combined 32 KiB cap (OpenAI’s AGENTS.md docs); we did not test the AGENTS.md side of this example ourselves.
Claude Code adds a wrinkle worth knowing, from its docs rather than our own test: from v2.1.277 it can read AGENTS.md directly (with documented exceptions for some Bedrock and telemetry-disabled sessions before v2.1.281), but by default a project CLAUDE.md or CLAUDE.local.md takes precedence, and /config offers settings to change that (claude-md-or-agents-md, claude-md-and-agents-md, claude-md, managed-only). Claude Code memory docs.
At a glance
SKILL.md | AGENTS.md | |
|---|---|---|
| Scope | One task | The whole repository |
| Loaded | On activation, when the task matches | Up front at session start, plus nested files as work reaches those directories on some hosts (subject to size caps and host settings) |
| Schema | YAML frontmatter: name, description required (spec) | No required schema, plain Markdown |
| Supporting files | references/, scripts/, assets/ | None standard |
| Codex | .agents/skills/<name>/SKILL.md (also .codex/skills/ on current versions); discovery and invocation confirmed by us | Root and nested AGENTS.md / AGENTS.override.md, 32 KiB default combined cap; documented, not tested by us |
| Claude Code | .claude/skills/<name>/SKILL.md | Read directly from v2.1.277 (documented exceptions before v2.1.281); CLAUDE.md / CLAUDE.local.md takes precedence by default |
| Cursor | .cursor/skills/ or shared .agents/skills/ | Documented as a plain-Markdown alternative to project rules |
What we checked
The AGENTS.md behavior above (Codex’s root-to-nested discovery and its 32 KiB cap, Claude Code’s v2.1.277 fallback and /config precedence settings, Cursor’s documented support) comes from OpenAI’s AGENTS.md docs, Claude Code’s memory docs and Cursor’s rules docs, all checked September 27, 2026. We did not test AGENTS.md loading, precedence, or its size cap ourselves in any host.
What we did test hands-on, on the same date: our explain-error SKILL.md, placed at .agents/skills/explain-error/ and the older .codex/skills/explain-error/ path in separate scratch Codex projects, was discovered by Codex CLI 0.157.1’s skill listing, correctly triggered on a matching prompt (both SKILL.md and references/checklist.md were read, visible in the tool trace), and correctly left alone on an unrelated prompt. Both project-scope paths worked identically on this version, a genuine finding, since the two paths reflect a real conflict between Codex’s current and historical docs. We also found that a broken reference link (references/checklist.md renamed) failed silently: Codex’s trace showed the failed file read, but its final answer gave no sign anything was missing.
What we didn’t check: AGENTS.md, in any host: no marker test, no precedence test, no size-cap test. We also didn’t test SKILL.md loading in Claude Code itself (the CLI couldn’t authenticate non-interactively in our test setup) or in Cursor (not installed).