AGENTS.md vs skills: what goes where
AGENTS.md (or CLAUDE.md) is always-on context: every session reads it before work starts. A skill is an on-demand procedure: the agent sees only its name and description until a task matches, then loads the full SKILL.md. Put what every task needs in AGENTS.md, and multi-step procedures only some tasks need in skills.
What is the difference between AGENTS.md and a skill?
When they load. An AGENTS.md is read in full at the start of every session, so every line costs context on every task. A skill is a folder with a SKILL.md; the agent carries only its frontmatter description until a task fits, then reads the body and any files beside it.
There is no skills.md file. The format is the Agent Skills spec: one directory per skill, named after the skill, holding a SKILL.md. Claude Code's docs draw the same line: rules load every session or when matching files open; task-specific instructions that needn't be in context all the time should be skills.
AGENTS.md vs CLAUDE.md vs skills: where does each instruction go?
| Put it in | When | Example |
|---|---|---|
| AGENTS.md | Every task needs it, and you want every agent to see it | Install, build and test commands; the layout; conventions a reviewer enforces |
| CLAUDE.md | Same as AGENTS.md, for Claude Code; best as an @AGENTS.md import plus Claude-only lines | "Use plan mode for changes under src/billing/" |
| A skill | A procedure some tasks need, with steps, scripts or reference files | Adding a migration, cutting a release, reproducing a flaky test |
| A path-scoped rule | Rules for one part of the tree, loaded when the agent touches it | .claude/rules/*.md with paths:, .github/instructions/*.instructions.md with applyTo, .cursor/rules/*.mdc with globs |
| A nested AGENTS.md | A package's own commands in a monorepo | packages/web/AGENTS.md |
The test: if an agent would get the task wrong without the line, and it applies to most tasks, it goes in AGENTS.md. If it is step 4 of a 9-step procedure, the whole procedure is a skill.
What is the SKILL.md format?
name(required by the spec): 1 to 64 characters, lowercase letters, digits and hyphens, not starting or ending with a hyphen, no--, and the same as the parent folder's name.description(required by the spec): 1 to 1,024 characters saying what the skill does and when to use it. The agent matches tasks against it, so name the trigger.- Optional:
license,compatibility(up to 500 characters),metadata(string to string) and the experimentalallowed-tools. - Body: plain Markdown instructions. The spec suggests keeping SKILL.md under 500 lines and the instructions under about 5,000 tokens; move long reference material into files beside it.
.agents/skills/add-migration/SKILL.md
---
name: add-migration
description: Create and test a database migration. Use when a change adds or alters a table, column or index.
---
# Add a migration
1. Run `pnpm db:new <short-name>`; it writes `db/migrations/<timestamp>-<short-name>.sql`.
2. Write the up and down SQL. Never edit a migration that has shipped.
3. Run `pnpm db:migrate && pnpm db:rollback && pnpm db:migrate` to prove it reverses.
4. Regenerate types with `pnpm db:types` and commit them with the migration.Skill folder layout
.agents/skills/
add-migration/
SKILL.md # frontmatter + steps
scripts/check.sh # optional files the steps refer to
cut-release/
SKILL.mdStrictness varies. Codex requires name and description. Claude Code treats every field as optional but recommends description, and truncates description plus when_to_use at 1,536 characters. OpenCode loads a skill without a description but doesn't advertise it to the agent.
Where does each agent look for skills?
| Agent | In the repo | In your home directory |
|---|---|---|
| Claude Code | .claude/skills/, and .claude/skills/ inside subdirectories | ~/.claude/skills/ |
| Codex | .agents/skills/ in every directory from the working directory up to the repo root | ~/.agents/skills/; also /etc/codex/skills |
| Cursor | .agents/skills/, .cursor/skills/; also .claude/skills/ and .codex/skills/ | The same names under ~ |
| GitHub Copilot | .github/skills/, .claude/skills/, .agents/skills/ | ~/.copilot/skills, ~/.agents/skills |
| Gemini CLI | .gemini/skills/ or .agents/skills/ (.agents/ wins) | ~/.gemini/skills/ or ~/.agents/skills/ |
| OpenCode | .opencode/skills/, .claude/skills/, .agents/skills/, from the working directory up to the project root | ~/.config/opencode/skills, ~/.claude/skills, ~/.agents/skills |
| OpenHands | .agents/skills/; legacy .openhands/skills/ and .openhands/microagents/ | — |
VS Code's Copilot harness lists only .github/skills/ and ~/.copilot/skills/; its Local harness also reads .claude/skills and .agents/skills.
.agents/skills or .claude/skills?
Pick by who works on the repo. .agents/skills/ is the cross-tool convention: Codex, Cursor, Copilot, Gemini CLI, OpenCode and OpenHands read it. The Agent Skills spec leaves location to each tool, and Claude Code doesn't read it: its docs name only .claude/skills/ and say nothing under .agents/ is loaded. .claude/skills/ reaches Claude Code, Cursor, Copilot and OpenCode, but not Codex or Gemini CLI.
Our census of the 388 GitHub repos on the board on 2026-11-16 finds skills under .agents/skills/ in 69 repos and under .claude/skills/ in 53; only 11 have both. On the scored board, 71 of 402 repos (18%) have at least one root .agents/skills/<name>/SKILL.md.
What should stay in AGENTS.md once you have skills?
- The commands every task runs: install, build, test one file, lint.
- The map: which directory holds what, and what not to edit.
- Conventions that apply to every change.
- One line per key skill, so agents without skill support know the procedure exists and where its steps are.
Moving procedures out is how a long AGENTS.md gets short again. The median AGENTS.md or CLAUDE.md on our board is 6,942 characters; files far past that usually carry procedures that would load more cheaply as skills.
Questions people ask
- Is there a skills.md file?
- No. Each skill is a folder holding a
SKILL.md, such as.agents/skills/cut-release/SKILL.md. There's no single skills file at the root. - Does Claude Code read .agents/skills?
- Not according to its docs, which list
~/.claude/skills/,.claude/skills/(including in subdirectories) and plugin skills, and say nothing under.agents/is read. For Claude Code, use.claude/skills/. - CLAUDE.md vs skills: which for a release checklist?
- A skill. CLAUDE.md loads every session, so a checklist used once a month costs context every day. The skill's description tells Claude when to load it.
- Do skills replace AGENTS.md?
- No. An agent loads a skill based on its description; AGENTS.md carries what applies to every task, including the commands a skill's steps assume.
- What are the rules for a skill name?
- Per the spec: 1 to 64 lowercase letters, digits and hyphens, no leading, trailing or doubled hyphen, matching the folder name. Cursor's and VS Code's docs require the folder match too.
- How long can a SKILL.md be?
- The spec recommends under 500 lines and under about 5,000 tokens of instructions, with longer material in separate files the skill points to.
descriptionis capped at 1,024 characters.
From the docs: agentskills.io/specification (new tab) · agentskills.io/adding-skills-support (new tab) · code.claude.com/skills (new tab) · code.claude.com/memory (new tab) · learn.chatgpt.com/build-skills (new tab) · cursor.com/skills (new tab) · docs.github.com/customization-cheat-sheet (new tab) · geminicli.com/skills (new tab) · opencode.ai/skills (new tab) · docs.openhands.dev/skills (new tab)
Check your agent skills · Check your AGENTS.md · CLAUDE.md guide · One file for every agent · What each agent reads · All guides