Agent Skills vs AGENTS.md, CLAUDE.md and Cursor Rules

Short answer: AGENTS.md, CLAUDE.md and Cursor rules set to Always Apply are read into the agent's context at the start of every session, so they suit short facts that are always true for a project. An agent skill puts only its name and description in context until a task matches, then loads its full SKILL.md, so it suits a procedure for one kind of job.

Our guide to agent skills vs MCP servers vs prompts covers the four main ways to steer an agent. This page goes deeper on the rules side: which file each tool reads, when it reads it, what that costs, and how to move a rule into a skill. Everything here was checked against each vendor's docs as of Oct 30, 2026.

What each one is

AGENTS.md

A plain Markdown file of instructions for coding agents: build steps, test commands, conventions. It has no required fields or headings. The format is now stewarded by the Agentic AI Foundation under the Linux Foundation, and agents.md says it is used by over 60,000 open-source projects. Codex, Cursor, GitHub Copilot, Devin, Windsurf and Gemini CLI are among the tools listed as supporting it.

You can put more AGENTS.md files in subfolders. The one closest to the file being edited wins, and a direct instruction in chat overrides them all.

CLAUDE.md

Claude Code's instructions file. A project one sits at ./CLAUDE.md or ./.claude/CLAUDE.md, a personal one at ~/.claude/CLAUDE.md, and an uncommitted personal one at CLAUDE.local.md. A CLAUDE.md can pull in other files with @path imports.

Claude Code also has rules files in .claude/rules/. A rule with a paths field in its frontmatter loads only when Claude works with matching files.

Cursor rules

Project rules live in .cursor/rules and must use the .mdc extension. Three frontmatter fields, description, globs and alwaysApply, decide which of four types a rule is: Always Apply, Apply Intelligently, Apply to Specific Files or Apply Manually.

Cursor also has User Rules, set in Customize, which apply to all your projects. Team and Enterprise plans add Team Rules, which admins can make required. Cursor reads AGENTS.md too, as a simpler alternative to .cursor/rules.

Other tools' instruction files

GitHub Copilot reads .github/copilot-instructions.md for the whole repository and .github/instructions/NAME.instructions.md files with an applyTo glob for specific paths. It also reads AGENTS.md (the nearest one wins), or a single CLAUDE.md or GEMINI.md at the repo root.

Gemini CLI reads GEMINI.md from ~/.gemini/, from your workspace and its parent folders, and from folders a tool touches. Setting context.fileName in settings.json lets it read AGENTS.md as well.

Agent skill

A folder with a SKILL.md file, plus optional scripts, references and templates. The frontmatter holds a name and a description saying what the skill does and when to use it. Our What Are Agent Skills guide covers the format.

When each one loads

What each one costs in context

Anything loaded at session start is paid for in every session, whether the task needs it or not. That is why each vendor asks you to keep these files short:

Claude Code: target under 200 lines per CLAUDE.md. Longer files use more context and reduce how well Claude follows them. Imports help organise a long file but don't cut its cost, because imported files load with the file that imports them.

Cursor: keep each rule under 500 lines and split large rules into smaller ones.

Codex: the combined AGENTS.md chain is capped by project_doc_max_bytes, 32 KiB by default. Once that is reached, Codex stops adding files.

A skill costs about 100 tokens for its name and description until it is used, by Anthropic's figures. Its SKILL.md body (Anthropic suggests under 5,000 tokens) loads only when triggered, and bundled files load only when read. Our skills vs MCP guide covers each tool's limit on the skill list.

One catch: cheap until used doesn't mean free afterwards. In Claude Code, an invoked skill's text stays in the conversation for later turns. After auto-compaction, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each, within a 25,000-token total.

When to use which

A fact that is true for every task, such as the build command, package manager or naming style: put it in AGENTS.md, CLAUDE.md or an Always Apply rule.

Guidance for one part of the codebase, such as one file type or folder: use a path-scoped rule (paths in .claude/rules, globs in Cursor, applyTo in Copilot) or a nested AGENTS.md or CLAUDE.md in that folder.

A multi-step procedure for one kind of task, or long reference material: make it a skill. Claude Code's docs say to create one when a section of CLAUDE.md has grown into a procedure rather than a fact.

A workflow you only want to run by hand, such as a deploy: a skill with disable-model-invocation: true. Claude Code and Cursor then run it only when you type /name.

Something that must happen every time, whatever the model decides: neither. Claude Code's docs say CLAUDE.md is context, not enforced configuration. To block an action, use a PreToolUse hook.

A team on several tools: keep shared facts in AGENTS.md. Codex, Cursor and Copilot read it directly. Claude Code reads it when there is no CLAUDE.md, or you can put @AGENTS.md at the top of a CLAUDE.md and add Claude-specific notes below it.

How to move rules into skills

In Cursor: /migrate-to-skills

Cursor 2.4 added /migrate-to-skills, which you type in Agent chat. It converts:

Apply Intelligently rules (alwaysApply false or unset, no globs) into standard skills.

User-level and workspace slash commands into skills with disable-model-invocation: true, so they still run only when you call them.

It does not migrate rules with alwaysApply: true or with globs, because those trigger differently from skills. User Rules are skipped because they aren't stored as files. The new skills land in .cursor/skills/, so read them before you rely on them.

In Claude Code: /doctor

Run /doctor. Among its checks, it looks at your CLAUDE.md files and offers to move the always-loaded guidance into skills and nested CLAUDE.md files that load on demand. It reports first and asks before changing anything. /doctor prompt-audit (v2.1.283 or later) checks your CLAUDE.md files, skills and other configuration for outdated or conflicting instructions.

Old .claude/commands/ files don't need converting. Custom commands have been merged into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.

By hand, in any tool

1. Read your rules file and mark sections that are numbered steps, checklists, or only matter for one kind of task.

2. For each one, create a folder named after the job, with a SKILL.md inside.

3. Write a name and a description that says what the skill does and when to use it. The description is all the agent sees before it decides.

4. Move the steps into the body. Put long reference material in a separate file the body links to.

5. Delete the section from the rules file, so the agent doesn't get the same instructions twice.

6. Test it: start a new session, ask for a task that should match, and check that the skill loads.

Which folder the skill goes in depends on the tool. Our folder-path guide lists them, and our triggering guide helps if the skill doesn't load.

If someone has already written the procedure you need, you can start from their skill. Search Skill Store 33 by the task, then check the publisher, licence and verification state on the skill page before you install it.

FAQ

Is AGENTS.md the same as an agent skill?

No. AGENTS.md is a plain Markdown file that coding agents read in full at the start of a session. A skill is a folder with a SKILL.md file. The agent sees only its name and description until a task matches, then reads the rest.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. You can also import it from CLAUDE.md with @AGENTS.md.

Should I convert all my Cursor rules into skills?

No. Cursor's /migrate-to-skills converts only Apply Intelligently rules and slash commands. Always Apply rules, rules with globs and User Rules stay as rules, because they trigger differently from skills.

Do skills replace CLAUDE.md?

No. Claude Code's docs keep CLAUDE.md for facts Claude should hold in every session, such as build commands and conventions. They move multi-step procedures, and guidance that only matters for one part of the codebase, into skills or path-scoped rules.

Let your agent search Skill Store 33

Sources

Claude Code, How Claude remembers your project (CLAUDE.md, .claude/rules, AGENTS.md): https://code.claude.com/docs/en/memory (read Oct 30, 2026)

Claude Code, Extend Claude with skills: https://code.claude.com/docs/en/skills (read Oct 30, 2026)

Anthropic, Agent Skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview (read Oct 30, 2026)

Cursor, Rules: https://cursor.com/docs/context/rules (read Oct 30, 2026)

Cursor, Agent Skills: https://cursor.com/docs/context/skills (read Oct 30, 2026)

OpenAI, Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md (read Oct 30, 2026)

AGENTS.md: https://agents.md (read Oct 30, 2026)

GitHub Docs, Adding repository custom instructions for GitHub Copilot: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions (read Oct 30, 2026)

Gemini CLI, GEMINI.md files: https://geminicli.com/docs/cli/gemini-md (read Oct 30, 2026)

This article was created with the help of AI (AI-Assisted). Every config key and command was checked against the official docs in the Sources list. ReadyAI is accountable for the content.

Keep reading