Black Friday: Lock in your founding rate.Compare plans

Every Premium Skill for $19.9/month. Cancel anytime. See plans

Skip to content

Skills or instruction files: CLAUDE.md, AGENTS.md and Cursor rules

Instruction files are loaded into every session, while a Skill is loaded only when its task appears. Split the two well and your agent stays fast, and your rules stay short enough for people to actually read.

For
People who look after a repository
Covers
Claude Code, Codex, Cursor
Time
6 min read

The short answer

Instruction files (CLAUDE.md, AGENTS.md, Cursor rules) are present in every session, so keep only facts and limits there. A Skill loads once its task shows up, so a lengthy procedure fits in it without slowing every other chat.

Which agent reads CLAUDE.md, AGENTS.md or Cursor rules

CLAUDE.md belongs to Claude Code and AGENTS.md to Codex. Cursor has its own rules and reads both of those too. All three agents read SKILL.md, but only when it is needed.

FileRead byWhen it loads
CLAUDE.mdCursor and Claude CodeClaude Code: at startup it loads ~/.claude/CLAUDE.md plus the project's file, and adds a subfolder's file when it begins working in that folder. Cursor: always.
AGENTS.mdCursor and CodexCodex: ~/.codex/AGENTS.md first, then a file for each level between the repo root and your launch folder; the nearest wins; 32 KiB in all. Cursor: always.
.cursor/rules/*.mdcCursorSet per rule: Always Apply, Apply Manually, Apply to Specific Files or Apply Intelligently
SKILL.mdClaude Code, Codex, CursorWhen a request matches its description, or when named directly

What to put in CLAUDE.md and what to put in a Skill

A quick test: one line that should hold in every chat is an instruction. A page that only one kind of task needs is a Skill.

What you want to tell the agentWhere it goes
“Format the code with Prettier before you commit.”Instruction file
“Never push straight to main.”Instruction file
“Write every reply in British English.”Instruction file
“Our step-by-step way of writing release notes.”A Skill
“Build a pitch deck that matches the brand guide.”A Skill

Every session

Instruction files use context in each chat, needed or not

When needed

Until it runs, a Skill costs about one sentence

Moving a procedure from CLAUDE.md into a Skill

What usually happens

Over a few months a CLAUDE.md gains a 60-line section on writing release notes. Every chat carries it, even a quick bug hunt. Moved into a Skill, it leaves one line behind and loads only when someone asks for release notes.

CLAUDE.md, afterwards
- Format with Prettier before committing. Never push straight to main.
- Writing release notes? Use the release-notes Skill.
  1. 1

    Move the procedure into .claude/skills/release-notes/SKILL.md (Codex and Cursor read .agents/skills/ instead).

  2. 2

    Add a description stating the situations it is for.

  3. 3

    In the instruction file, swap the old section for a one-line pointer.

    You should see: a much shorter instruction file, and the procedure turning up only once release notes are requested.

Cursor can do the conversion for you: /migrate-to-skills turns rules set to “Apply Intelligently” into Skills.

Common questions

What exactly is CLAUDE.md?

Claude Code's instruction file, written in Markdown and loaded as each session starts. Your personal one sits at ~/.claude/CLAUDE.md, and a project keeps its own at CLAUDE.md or .claude/CLAUDE.md.

In Codex, should I pick AGENTS.md or Skills?

Both. Rules that always hold go in AGENTS.md; procedures that should load on demand become Skills. The Codex guide explains each.

Is a Cursor rule the same thing as a Skill?

No. A rule is an .mdc file Cursor adds to the conversation; a Skill is a folder the agent opens when it fits or when you ask. More in the Cursor guide.

Sources

Did this guide help?