SKILL.md vs CLAUDE.md vs AGENTS.md: what's the difference?
These three files get lumped together, but they solve different problems. Here's how SKILL.md, CLAUDE.md, and AGENTS.md actually differ — and why most projects use more than one.
Why these three get confused
Search for AI coding config and you'll hit SKILL.md, CLAUDE.md, and AGENTS.md side by side, as if you must pick one. You don't. They aren't three rivals competing for the same slot.
The key split is about loading:
- CLAUDE.md and AGENTS.md are the same category — always-on project instructions loaded in full at the start of every session.
- SKILL.md is a different mechanism — an on-demand, model-invoked capability that loads only when a task matches it (progressive disclosure).
Once you internalize that, the "vs" mostly dissolves. Let's break down each one.
What each one is
SKILL.md
SKILL.md is the entry point of an Agent Skill: a folder containing a SKILL.md file (YAML frontmatter with name + description, then Markdown instructions) plus optional bundled scripts/, references/, and assets/. Anthropic released it as an open, vendor-neutral standard on December 18, 2025 (agentskills.io).
It uses progressive disclosure, three levels:
1. Only the skill's name + description sit in the system prompt at startup. 2. The full SKILL.md body loads only when the model judges the task matches. 3. Bundled files open only if the instructions reach for them.
So a skill costs almost no tokens until it's actually triggered. It's model-invoked, not always-on — and unlike the other two, a skill can ship runnable scripts.
CLAUDE.md
CLAUDE.md is Claude Code's memory-and-instructions file: persistent context (build/test commands, conventions, "always/never" rules) that Claude reads at the start of every session. Files from the working directory up the directory tree are loaded in full regardless of length and injected as a user message after the system prompt. It's guidance, not enforced config — use hooks and permissions for hard rules.
AGENTS.md
AGENTS.md is a tool-agnostic open standard — essentially a "README for AI agents" placed at the repo root. Compliant agents auto-load it every session. It was formalized around August 2025 (led by OpenAI/Codex, with Google, Cursor, and others) and is now read by many coding agents and IDEs. It's the same functional category as CLAUDE.md, just cross-tool instead of Claude-specific.
Comparison table
| Dimension | SKILL.md | CLAUDE.md | AGENTS.md |
|---|---|---|---|
| Loading | On-demand (progressive disclosure) — only name+description upfront | Always-on — loaded in full every session | Always-on — auto-loaded every session |
| Scope | One reusable skill / capability | The whole project (Claude Code) | The whole project (cross-tool) |
| Tools | Open standard: Claude, Codex, Gemini CLI/Antigravity, Cursor, and more | Claude Code only (reads CLAUDE.md, not AGENTS.md) | Cross-tool open standard: 20+ agents (Codex, Copilot, Gemini CLI, Cursor, Jules, Aider, Zed, Warp…) |
| Location | ~/.claude/skills/<name>/SKILL.md, .agents/skills/, ~/.gemini/skills/, etc. | ./CLAUDE.md or ./.claude/CLAUDE.md; ~/.claude/CLAUDE.md; org policy path | Repo-root AGENTS.md (nested files in monorepos; closest wins) |
| Can bundle scripts | Yes (scripts/, references/, assets/) | No | No |
| Best for | Specialized, task-specific procedures you invoke sometimes | Always-needed Claude Code repo facts and rules | Always-needed repo facts, portable across many agents |
Which one when
A quick decision guide:
- Baseline facts every session needs (build commands, conventions, architecture, hard constraints)? Use an always-on file. If you want it portable across Codex, Cursor, Gemini CLI, etc., write AGENTS.md. If you're Claude Code-only, CLAUDE.md is the native path.
- A multi-step procedure or specialized capability you only need for *some* tasks (release checklist, migration runbook, a formatter with a helper script)? Make it a SKILL.md skill so it loads on demand and costs no tokens the rest of the time.
- Long reference material that would bloat context if always resident? Put it in a skill's
references/, not in CLAUDE.md/AGENTS.md. - Need it enforced, not merely suggested? None of these enforce — reach for hooks and permissions.
- Already have an AGENTS.md and use Claude Code? Claude doesn't read AGENTS.md natively (mid-2026), so symlink
AGENTS.md→CLAUDE.mdor import it with@AGENTS.mdinside CLAUDE.md.
The official Claude Code guidance says it well: put always-needed facts in CLAUDE.md; move task-specific procedures into skills.
Use them together
They're complementary, not either/or. A healthy setup looks like:
- AGENTS.md (or CLAUDE.md) for the always-on baseline: how to build, test, and lint; naming conventions; "never touch these files" rules.
- SKILL.md skills for the specialized, on-demand jobs: generating a changelog, running a data migration, scaffolding a component — each with its own instructions and optional scripts.
Because SKILL.md is a plain folder + Markdown format identical across agents, you can copy or symlink the same skill between ~/.claude/skills, ~/.agents/skills, and ~/.gemini/skills and it works unchanged. So your repo carries portable AGENTS.md context, and your skills library carries portable capabilities — one for baseline, one for on-demand.
Create your skill by tool
Start with the Agent Skills pillar, then follow the guide for your agent:
Ready to build one? Use the Skill Builder to generate a working SKILL.md, or browse skills to see real examples.