Skills or instruction files: what goes where?
CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions or a skill: what is always loaded, what loads on demand, and how to split your guidance.
Updated on
An instruction file (CLAUDE.md, AGENTS.md, a Cursor rule, Copilot instructions) is read by the agent before it works. A skill stays in the background until a task needs it. That difference in loading decides what you put in each.
Always loaded, loaded on demand
Instruction files act as the project's permanent memory. In Claude Code, CLAUDE.md is read at the start of every session; in Codex, the AGENTS.md chain is built once per run. Everything in them takes up context, even when the task has nothing to do with it.
A skill loads in two steps. In Claude Code, the agent first sees each skill's description; the full text loads only when the skill is used. The documentation puts it this way: a skill's body loads only when it is used, unlike CLAUDE.md content. A two-hundred-line procedure costs almost nothing until you need it. For other agents, check the behavior on the agent's page; the logic of the format is the same.
Comparison
| Criterion | Instruction file | Skill |
|---|---|---|
| Loading | Always (at launch, or when matching files are in play for a scoped rule) | Description visible up front, full text when the task matches |
| Typical content | Build and test commands, conventions, architecture, prohibitions | Multi-step procedure, checklist, templates, examples |
| Shape | A Markdown file, no imposed structure | A folder with a SKILL.md (name, description) and supporting files |
| Context cost | Paid every session | Almost nothing until the skill is used |
| Trigger | Automatic | By the agent from the description, or by hand |
Each agent's files
| Agent | Main file | Targeted instructions |
|---|---|---|
| Claude Code | CLAUDE.md (project, user, local); AGENTS.md is read when there is no CLAUDE.md | .claude/rules folder, with a paths field to limit a rule to certain files |
| Codex | AGENTS.md (global in ~/.codex, then from the project root down to the current folder) | AGENTS.override.md, or an AGENTS.md in a subfolder |
| Cursor | Rules in .cursor/rules (.mdc); AGENTS.md at the root is accepted | Four modes: always, by description, by file globs, or on mention |
| GitHub Copilot | .github/copilot-instructions.md; AGENTS.md is accepted | .instructions.md files in .github/instructions, with an applyTo field |
Scoped rules in Cursor and Claude Code sit in between: they remain instructions, but only apply when matching files come into play.
What goes where
Put in the instruction file what is true for the whole project and what the agent cannot guess:
- the commands to run tests, the linter, the build;
- naming conventions and folder structure;
- known pitfalls (a required environment variable, a folder not to touch).
Put in a skill what is a method, not a fact:
- a multi-step audit with its checklist;
- a release or review procedure;
- a document template and its examples.
Claude Code's documentation gives the signal: create a skill when you keep pasting the same instructions into the chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.
Keep the file short
Aim for under 200 lines per CLAUDE.md, according to Claude Code's documentation: beyond that, the file uses more context and the agent follows it less reliably. Cursor recommends keeping each rule under 500 lines. Codex stops adding instruction files once they reach 32 KiB combined (the project_doc_max_bytes setting).
A file that keeps growing can be handled in three moves:
- Move procedures into skills.
- Move what concerns only part of the code into a scoped rule.
- Delete what the agent works out on its own by reading the code.
One file shared across agents
AGENTS.md is read by Codex, Cursor and GitHub Copilot, and Claude Code reads it when the repository has no CLAUDE.md. If you use several agents, a common AGENTS.md saves you from maintaining several copies. In Claude Code, a CLAUDE.md can also import it with the @AGENTS.md syntax.
Skills follow the same idea: one skill folder is copied into each agent, only the install folder changes. Each agent's page (Claude Code, Codex, Cursor, GitHub Copilot) gives it. For the difference with a plain prompt, see resource or prompt.
Going further
Sources
Frequently asked questions
Does a skill replace my CLAUDE.md or AGENTS.md?
No. The instruction file holds facts that apply to the whole project (commands, conventions, pitfalls). The skill holds procedures the agent only needs for certain tasks.
Why not put everything in CLAUDE.md?
Because it is read at the start of every session: the bigger it gets, the more context it takes. Claude Code's documentation advises aiming for under 200 lines per file and not leaving long procedures in it.
Does an instruction file guarantee the agent complies?
No. In Claude Code these files are context, not enforced configuration. To block an action, use a hook, not an instruction.