Short answer
AGENTS.md is always-on project notes: commands, code style, and test rules that a coding agent reads at the start of work. SKILL.md is an on-demand skill: the main file in a skill folder, loaded only when the task matches. Keep project facts in AGENTS.md. Put one reusable workflow in SKILL.md.
| AGENTS.md | SKILL.md | |
|---|---|---|
| What it is | Project notes for every session | Steps for one job |
| When it loads | At the start of work | When the task matches |
| Typical path | AGENTS.md at the repo root | .claude/skills, .cursor/skills, or .agents/skills |
| Keep it | Short, because it is always in context | As long as the job needs |
Words used in this guide
- Workflow: a set of steps used to finish a task.
- Repository or repo: a project folder whose changes are saved and tracked.
- MCP: a standard way for an AI tool to connect to other tools and information.
What this means
AGENTS.md describes the project
Use AGENTS.md for information an AI coding agent needs every time it works in a repository: build commands, test steps, folder rules, code style, and important limits. It has no required frontmatter. Keep it short, because it is loaded into context at the start of each session.
SKILL.md describes a task
A SKILL.md file lives in its own folder, such as .claude/skills/code-review/SKILL.md. It starts with YAML frontmatter (name and description) and then gives the steps for one job. Agents show only the name and description until the task matches, so many skills cost little context. Every field and limit is in the SKILL.md frontmatter reference.
Which tools read which file
Cursor reads AGENTS.md (root and nested folders) and loads skills from .cursor/skills, .agents/skills, and .claude/skills. Codex reads AGENTS.md and loads skills from .agents/skills. Claude Code loads skills from .claude/skills and, from v2.1.277, reads AGENTS.md when the project has no CLAUDE.md or CLAUDE.local.md.
A project can use both
AGENTS.md tells the agent how the repository works. A skill then provides detailed steps for a task such as code review or release preparation. Do not repeat the same project facts in every skill. For the full decision in Claude Code, including subagents, hooks and MCP, see skills vs MCP vs subagents vs hooks.
Simple steps
- Put shared repository facts and commands in AGENTS.md.
- Choose one repeated task that needs more detailed instructions.
- Create a folder for the skill and add SKILL.md with name and description frontmatter.
- Write the task purpose, inputs, steps, output, and safety limits.
- Test the skill while the project instructions are active.
- Package the skill when several projects need the same version.
Where to go next
- Browse agent skills: Ready-made skills you can install. Each one is a folder with its own SKILL.md.
- How to create an agent skill: Write your own SKILL.md, one step at a time.
- Does Claude Code read AGENTS.md?: When Claude Code picks up AGENTS.md, and what to do when it doesn't.
FAQ
Should SKILL.md contain all project instructions?
No. Keep general repository instructions in AGENTS.md. Put only the information needed for the skill's task in SKILL.md.
Is it AGENTS.md or AGENT.md, SKILL.md or SKILLS.md?
The file names tools look for are AGENTS.md (plural) for project instructions and SKILL.md (singular) inside each skill folder.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. Otherwise, import it from CLAUDE.md with @AGENTS.md. See does Claude Code read AGENTS.md? for the checklist when it doesn't load.
Can one skill work in several repositories?
Yes, when the skill avoids project-specific assumptions or clearly explains the information each project must provide.