SKILL.md vs CLAUDE.md vs AGENTS.md: Which File Does What

The one-sentence difference

Ask what should be true on every task, and what should happen only on some tasks. Everything that is always true — "run tests with npm run test:ci", "never edit the generated files", "use British spelling" — belongs in a rules file that loads every session. That is CLAUDE.md or AGENTS.md.

A procedure you only need sometimes — "how we write a release note", "how to turn a CSV of leads into personalised emails", "our checklist for reviewing a pull request" — belongs in a skill. It would be wasted context on every other task, so the agent should pull it in only when it is relevant. That is SKILL.md.

Most confusion comes from putting procedures in the rules file. The rules file grows to hundreds of lines, every session pays for it in context, and the one instruction that mattered gets lost among the ones that did not apply.

CLAUDE.md: standing instructions for Claude Code

CLAUDE.md is the memory file Claude Code reads automatically. A file in your home folder (~/.claude/CLAUDE.md) applies to every project, a file at the root of a repository applies to that project, and CLAUDE.md files inside subfolders are pulled in when Claude works on files there.

Keep it short and factual: the commands to build, test and lint; the conventions a new teammate would get wrong; the directories that are generated or off-limits. It can also pull in other files with an @path import, which is how you avoid copying the same rules into several places.

• Loaded: every session, automatically.
• Scope: you, a project, or a folder.
• Best for: build and test commands, code style, project-specific "never do this" rules.

AGENTS.md: the same job, tool-neutral

AGENTS.md is an open format for exactly the same kind of standing instructions, written so any coding agent can read it rather than one vendor's tool. OpenAI's Codex is among the agents that use it, and support has spread to others — check your tool's documentation for whether it reads the file natively.

It is plain Markdown at the root of the repository. Larger repositories can add further AGENTS.md files inside subprojects; the format's guidance is that the file nearest to the code being changed takes precedence, so a package can override the root rules.

If your team uses several agents, AGENTS.md is the natural single source of truth. For a tool that only reads its own file, point that file at it — a CLAUDE.md that contains the line @AGENTS.md imports it — rather than keeping two copies in sync by hand.

• Loaded: every session, by agents that support it.
• Scope: a repository, or a folder inside one.
• Best for: teams using more than one coding agent.

SKILL.md: a procedure loaded on demand

An Agent Skill is a folder with a SKILL.md file at its root. The file starts with a short YAML header — a name and a description — followed by the instructions. The name uses lowercase letters, numbers and hyphens; the description says what the skill does and when to use it.

The loading model is what makes skills different. The agent sees only each skill's name and description until a task matches one; then it reads the full SKILL.md, and it opens any extra files the skill points to — templates, reference notes, scripts — only when a step needs them. That is why a skill can be long and detailed without costing anything on unrelated tasks.

Skills work in Claude's apps, in Claude Code and through the API. In Claude Code, personal skills live in ~/.claude/skills/ and project skills in .claude/skills/, each in its own folder.

• Loaded: only when a task matches the description.
• Scope: one capability or workflow.
• Best for: repeatable procedures with steps, checklists, templates or scripts.

Which one should hold your instruction?

Run each instruction through three questions. The answers decide the file.

• Does it apply to nearly every task in this project? → the rules file (CLAUDE.md or AGENTS.md).
• Is it a multi-step procedure you only need for one kind of task? → a skill (SKILL.md).
• Does it apply to you on every project, not to the repository? → your personal CLAUDE.md in your home folder.
• Would a new teammate need it on day one? → the rules file. Would they look it up when the task comes up? → a skill.
• Is it more than a screen long? → almost certainly a skill, or split it into one.

A worked example: one repo, all three files

Picture a web app repository. The root AGENTS.md says: install with npm ci, run tests with npm run test:ci before finishing, never edit files in src/generated, and write commit messages in the imperative mood. The root CLAUDE.md is one line, @AGENTS.md, so Claude Code reads the same rules as every other agent on the team.

Release notes are written once a fortnight, so that procedure is a skill: .claude/skills/release-notes/SKILL.md, with a description like "Write customer-facing release notes from merged pull requests. Use when asked for release notes or a changelog." Inside, it lists the steps — gather merged PRs, group them by customer impact, drop internal refactors, apply the house tone — and points to a template file for the final format.

On an ordinary bug fix, the agent reads the rules and never loads the release-notes procedure. When someone asks for release notes, the description matches and the full procedure arrives exactly when it is useful.

Common mistakes

• A 400-line CLAUDE.md. If most of it is procedures, move them into skills and keep the rules file to what is always true.
• Vague skill descriptions. "Helps with documents" never matches reliably; "Turn meeting notes into a decision log with owners and dates — use when given raw meeting notes" does.
• Duplicated rules in CLAUDE.md and AGENTS.md that drift apart. Keep one file and import it from the other.
• Secrets in any of these files. They are read into the model's context and usually committed to the repository.
• Rules that describe wishes instead of checks. "Write good tests" does nothing; "every new function needs a test in the matching __tests__ folder" can be followed and verified.

Generate them instead of starting from a blank file

PromptVibe's Agent Rules Studio drafts CLAUDE.md, AGENTS.md, .cursorrules and Copilot instruction files from your stack and conventions, and the Skill Generator turns a workflow you describe into a SKILL.md with a clear name and a description written to match the right tasks. The free Prompt Generator Skill is a ready-made example of a complete skill you can install and read.

Related articles