SkillsPicker

Home / Guides

AGENTS.md vs SKILL.md

Short answer: AGENTS.md is the project brief. The agent reads it at the start of a task, every task. Put build commands, test commands, code style and repo layout there. SKILL.md is one playbook for one job, such as a release or a database migration. The agent sees its name and description at start and reads the rest when the job comes up. One repo can have one AGENTS.md (or a few nested ones) and many skills.

Facts below come from agents.md, the Agent Skills spec, and the docs for Codex, Claude Code, GitHub Copilot and Cursor, read on October 28, 2026.

Want skill picks for your own repo? Scan your repo free. Paste your GitHub repo URL. You see the match count and 2 picks. The full list is $9 once, up to 30 ranked picks for that scan.

The difference in one table

AGENTS.md SKILL.md
What it is One Markdown file of project instructions A folder with SKILL.md, plus optional scripts/, references/, assets/
Where it lives Repo root, plus nested files in subfolders A skill folder, such as .agents/skills/<name>/ or .claude/skills/<name>/
Front matter None. Plain Markdown, any headings YAML with name and description (both required)
When it loads At the start of each task or session Name and description at start. The body loads when the task matches or you call it
Context cost The whole file, on every task About 100 tokens per skill until it loads, per the spec
Scope Everything under its folder. The nearest file wins One task
Can bundle files No Yes: scripts, templates, reference docs
Spec agents.md, stewarded by the Agentic AI Foundation under the Linux Foundation agentskills.io

What AGENTS.md is

The agents.md site calls it "a README for agents". It is plain Markdown with no required fields. The site lists these common sections:

Commit message rules, PR rules and deploy notes belong here. The site puts it this way: anything you'd tell a new teammate.

In a monorepo, put an AGENTS.md in each package. Per the agents.md FAQ, the closest file to the edited file wins, and a prompt you type in chat overrides all of them. The site says the main OpenAI repo had 88 AGENTS.md files at the time of writing.

A real example: apache/airflow ships an AGENTS.md with sections for environment setup, commands, repository structure, architecture boundaries, security model, coding standards, testing standards, and commits and PRs.

What SKILL.md is

A skill is a folder with a SKILL.md file at its top level. The file opens with YAML front matter. name (lowercase, hyphens, up to 64 characters, matches the folder name) and description (up to 1024 characters, says what the skill does and when to use it) are required. The body holds the steps.

The spec describes three load stages:

  1. Metadata (about 100 tokens): name and description load at start for every skill.
  2. Instructions (under 5000 tokens recommended): the SKILL.md body loads when the skill activates.
  3. Resources: files in scripts/, references/ and assets/ load when the task needs them.

That is the key gap between the two files. A 300-line AGENTS.md costs 300 lines on every task. Ten skills of 300 lines each cost ten short descriptions until one of them is needed.

For every field, see our SKILL.md format guide.

What goes where

Content Put it in Why
pnpm install, pnpm test, lint command AGENTS.md Needed on most tasks
Code style: strict TypeScript, quote style, naming AGENTS.md Applies to every edit
Repo layout: where handlers, tests, docs live AGENTS.md Saves the agent a search each time
"Do not edit dist/" or "ask before new dependencies" AGENTS.md A standing rule, not a task
Release steps: changelog, version bump, tag, publish SKILL.md Many steps, used once in a while
Database migration routine with a check script SKILL.md Needs a bundled script
PDF or spreadsheet work with a template SKILL.md Needs bundled assets
A routine you want in more than one repo SKILL.md in your home skills folder Skills install per user. AGENTS.md belongs to one repo

The Claude Code docs give the same test for CLAUDE.md: keep it to facts Claude should hold in every session, and if an entry "is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule".

A good pattern: keep AGENTS.md short and add one line that names your skills, for example "Release steps live in the release skill." The agent knows the skill exists without the steps in context.

How each agent reads AGENTS.md

Codex

Codex reads AGENTS.md before any work. Per the Codex docs:

For Codex code review on GitHub, add a ## Code Review Rules section to the AGENTS.md nearest the code. Codex skills live in .agents/skills/. See our Codex skills guide.

Claude Code

Claude Code's own file is CLAUDE.md. Per the memory docs, Claude Code v2.1.277 and later reads AGENTS.md as project instructions, with one catch:

Your repo has Claude reads
AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your folder or above AGENTS.md
AGENTS.md and a CLAUDE.md or CLAUDE.local.md CLAUDE.md files, not AGENTS.md
A CLAUDE.md that imports @AGENTS.md Both, through the import

To read both files, open /config and set Project instructions to claude-md-and-agents-md. Claude Code does not read AGENTS.override.md, AGENTS.local.md, or anything under a .agents/ folder as instructions.

The setup that works on every version is a CLAUDE.md next to AGENTS.md that holds the import plus any Claude-specific lines:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The docs say to keep each CLAUDE.md under 200 lines. Claude Code skills live in .claude/skills/ and ~/.claude/skills/. See how to install Claude Code skills.

GitHub Copilot

Per the Copilot docs, Copilot on GitHub reads three kinds of instructions:

Copilot reads skills from .github/skills/, .claude/skills/ or .agents/skills/ in the repo, and from ~/.copilot/skills/ or ~/.agents/skills/ for your user, per the Copilot skills page. For code review, Copilot reads instructions and skills from the PR's head branch, so you can test a change to either in the same PR.

Cursor

The Cursor rules docs list AGENTS.md as the plain Markdown option, with nested files for subfolders such as frontend/AGENTS.md. Per the Cursor skills docs, Cursor skills live in .agents/skills/ or .cursor/skills/, and Cursor loads .claude/skills/ and .codex/skills/ on top of those. For rules vs skills in Cursor, see Cursor rules vs agent skills.

Gemini CLI

The agents.md FAQ shows how to point Gemini CLI at AGENTS.md in .gemini/settings.json:

{ "context": { "fileName": "AGENTS.md" } }

For Gemini skills, see Gemini CLI skills.

One repo that works in all four agents

your-repo/
├── AGENTS.md                 # build, test, style, layout (Codex, Copilot, Cursor, Claude Code)
├── CLAUDE.md                 # @AGENTS.md plus Claude-only lines
├── packages/api/AGENTS.md    # API package rules, nearest file wins
└── .agents/skills/
    └── release/
        ├── SKILL.md          # name: release
        └── scripts/bump.sh

Codex, Copilot and Cursor read .agents/skills/. Claude Code reads .claude/skills/. Copilot and Cursor read .claude/skills/ in addition to .agents/skills/, so a skill there covers three of the four. The open skills CLI (npx skills add) writes each skill to the folder the agent expects. Its agent table lists .claude/skills/ for Claude Code and .agents/skills/ for Codex, Cursor and GitHub Copilot.

To write a new skill from chat, try Anthropic's skill-creator skill. Its description says it creates, edits and measures skills.

Common mistakes

Find skills for your repo

SkillsPicker indexes open-license SKILL.md skills from public GitHub repos and ranks them for your stack. See skills for Codex, skills for Claude Code, skills for Copilot, skills for Cursor, or browse skills by stack. For skills vs tool servers, see Claude skills vs MCP.

FAQ

What is AGENTS.md? An open Markdown file of instructions for coding agents, kept in your repo. The agents.md site calls it a README for agents. It has no required fields.

Is AGENTS.md the same as SKILL.md? No. AGENTS.md is project context that loads on every task. SKILL.md is a task playbook that loads when the task comes up, and it needs name and description front matter.

AGENTS.md vs CLAUDE.md: which should I use? Use AGENTS.md for instructions you share across agents. Claude Code reads it when there is no CLAUDE.md. If you need Claude-only lines, add a CLAUDE.md that starts with @AGENTS.md.

AGENTS.md vs copilot-instructions.md? Copilot reads both. .github/copilot-instructions.md is Copilot's own repo-wide file. AGENTS.md works in Copilot and in Codex, Cursor and Claude Code, so it is the better pick for a shared file.

Where do skills go if I use AGENTS.md? In a skills folder, not in AGENTS.md. Codex, Copilot and Cursor read .agents/skills/. Claude Code reads .claude/skills/.

Can AGENTS.md list my skills? Yes. A line that names a skill and says when to use it helps the agent find it. Keep the steps in the skill.

Checked 2026-10-28. Prices and policies change. Confirm on the source before you buy.

Sources

More guides