The short answer
CLAUDE.md, AGENTS.md, and Cursor rules sit in context every session, so keep them to facts and boundaries. A Skill loads only when its task comes up, which means it can hold a long procedure without weighing down every chat.
Who reads CLAUDE.md, AGENTS.md, and Cursor rules
Claude Code reads CLAUDE.md, Codex reads AGENTS.md, and Cursor reads its own rules plus both of those files. All three read SKILL.md, but only when it’s needed.
| File | Read by | When |
|---|---|---|
CLAUDE.md | Claude Code, Cursor | Claude Code: at session start, from ~/.claude/CLAUDE.md and the project; a subfolder’s file once Claude works in that folder. Cursor: always applied. |
AGENTS.md | Codex, Cursor | Codex: ~/.codex/AGENTS.md first, then one file per folder from the repo root down to where you started; the closest one wins; 32 KiB in total. Cursor: always applied. |
.cursor/rules/*.mdc | Cursor | One of four modes: Always Apply, Apply Intelligently, Apply to Specific Files, or Apply Manually |
SKILL.md | All three | Only when a request matches it, or you call it by name |
What belongs in CLAUDE.md and what belongs in a Skill
A good rule of thumb: if it fits on one line and should hold in every chat, it’s an instruction. If it takes a page to explain and only matters for one kind of task, it’s a Skill.
| You want to say | Put it in |
|---|---|
| “Use pnpm, not npm.” | Instruction file |
| “Never deploy without approval.” | Instruction file |
| “Run the tests before you commit.” | Instruction file |
| “How we write a release note, step by step.” | A Skill |
| “Build a launch deck in our brand style.” | A Skill |
Every session
Instruction files cost context in every chat, whether you use them or not
When needed
A Skill costs about a sentence until it’s used
How to move a procedure out of CLAUDE.md
A common before and after
A CLAUDE.md slowly grows a 60-line section on how to write release notes. Every chat pays for it, debugging sessions included. Move it into a Skill and only one line stays behind, while the procedure loads only when you ask for release notes.
- Use pnpm. Never deploy without approval.
- For release notes, use the release-notes Skill.- 1
Cut the procedure into
.claude/skills/release-notes/SKILL.md(or.agents/skills/for Codex and Cursor). - 2
Write a description that says when to use it.
- 3
Leave a one-line pointer in the instruction file.
You should see: a shorter instruction file, with the procedure loading only when you ask for release notes.
In Cursor, /migrate-to-skills converts “Apply Intelligently” rules into Skills for you.
Common questions
What is CLAUDE.md?
A Markdown file of instructions that Claude Code reads at the start of every session. Yours lives at ~/.claude/CLAUDE.md; a project’s lives at CLAUDE.md or .claude/CLAUDE.md.
Should I use AGENTS.md or Skills in Codex?
Use both. Put short rules that are always true in AGENTS.md, and procedures that should load only when needed in Skills. The Codex guide covers both.
Are Cursor rules the same as Skills?
No. Rules are .mdc files that get added to conversations; Skills are folders the agent uses when they’re relevant or when you call them. See the Cursor guide.
Sources
Did this guide help?
