CLAUDE.md Template and AGENTS.md: Which File Does What? (with Examples)

CLAUDE.md, AGENTS.md, SKILL.md: three files that all hold "instructions for the AI". Who reads which, and when?

This guide sorts out the division of work, gives you a CLAUDE.md template to copy, and shows how to keep AGENTS.md and CLAUDE.md in one source.

CLAUDE.md, AGENTS.md, SKILL.md: who reads what?

The rule of thumb from the Claude Code docs: CLAUDE.md holds facts Claude needs in every session, such as build commands, conventions, project layout and "always do X" rules. A multi-step procedure, or something that only matters for part of the codebase, belongs in a skill or a path-scoped rule.

Important: Claude treats CLAUDE.md as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook or settings rules, which the client enforces.

Where CLAUDE.md lives

Organizations can also deploy a managed file (e.g. /etc/claude-code/CLAUDE.md on Linux and WSL).

Nested: CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory load at launch. All discovered files are concatenated rather than overriding each other. Files in subdirectories load on demand.

Imports with @: @path/to/file pulls in another file. Relative paths resolve relative to the file containing the import, with a maximum depth of four hops. Imports help you organize a long file but don't reduce its context cost.

Quick start: /init generates a starting CLAUDE.md from your codebase. Run /context and check "Memory files" to see which files loaded.

CLAUDE.md template to copy

The docs recommend targeting under 200 lines per file, with instructions concrete enough to verify. This template stays short on purpose:

# Project: <name>

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (run before committing)
- Lint: `npm run lint`

## Code style
- TypeScript for all new files
- 2-space indentation
- Named exports instead of default exports

## Layout
- API handlers live in `src/api/handlers/`
- Shared types in `src/types/`

## Boundaries
- Don't touch `migrations/` without asking
- No new dependencies without asking
- No secrets in code or logs

## More context
- Overview: @README.md

Replace the examples with your real commands. "Run npm test before committing" beats "Test your changes"; that's the docs' own example.

Notes meant only for humans can go in block-level HTML comments (<!-- ... -->). Claude Code strips them before the content is injected into context.

Keeping AGENTS.md and CLAUDE.md in sync

What Claude Code reads by default

Reading AGENTS.md directly requires Claude Code v2.1.277 or later. Type /config and change Project instructions, for example to claude-md-and-agents-md, to have Claude read both.

Watch out with CLAUDE.local.md: to keep it and still have Claude read AGENTS.md, you need that claude-md-and-agents-md setting.

One source, two tools

Cursor supports AGENTS.md in the project root and in subdirectories (Cursor docs). If you use both tools, make AGENTS.md the shared source. For Claude Code you have two options:

1. Import (use this when you have Claude-specific additions):

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

2. Symlink (when you need nothing Claude-specific):

ln -s AGENTS.md CLAUDE.md

The docs recommend the import if anyone who clones the repository works on Windows: creating a symlink there needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled.

For the structure of Cursor rules as .mdc files, see our guide Cursor .mdc Rules Explained. The choice between rules and AGENTS.md is covered in Cursor Rules vs. AGENTS.md.

When a skill instead of a rule?

• Rule (CLAUDE.md, .claude/rules/): applies always, or to certain files. Example: "Components in src/components/ use Tailwind." With paths: frontmatter in a file under .claude/rules/, the rule loads only when Claude works with matching files.
• Skill (SKILL.md): a procedure you need now and then. Example: "Write release notes from the git log." Its content costs context only when the skill runs.

How to build one: SKILL.md Format & Template.

Common mistakes

• Too long: over 200 lines consumes more context and, per the docs, reduces adherence. Move part-specific instructions into path-scoped rules.
• Stale commands: an npm run build that no longer exists misleads Claude. /doctor prompt-audit (v2.1.283 or later) looks for outdated or conflicting instructions.
• Contradictions: if two instructions contradict each other, Claude may pick one arbitrarily. Review user, project and subdirectory files together.
• "Please read AGENTS.md" as a sentence: Claude then sees AGENTS.md only if it decides to open the file. Replace the sentence with an @AGENTS.md import.

Ready-made templates

Ready-made AGENTS.md and CLAUDE.md templates plus 13 rules: the Cursor + Claude Code Rules Pack by Aramac, checked against the Cursor rules format (.mdc, as of October 2026). Personal, non-commercial use only (licence). €19 incl. VAT. Free updates until 16.04.2027.

For recurring workflows there's the separate Claude Code Skills Pack (€29 incl. VAT), validated against the Agent Skills specification (claude plugin validate, Claude Code 2.1.301).

FAQ

What's the difference between AGENTS.md and CLAUDE.md?
Both hold persistent project instructions. CLAUDE.md is Claude Code's format; AGENTS.md is a cross-tool format that Cursor also reads. From v2.1.277, Claude Code reads AGENTS.md by default only when there's no CLAUDE.md.

Does Claude Code read both files at once?
Not by default. Either import AGENTS.md with @AGENTS.md in your CLAUDE.md, or set Project instructions to claude-md-and-agents-md under /config.

Where do I put CLAUDE.md?
For the project in ./CLAUDE.md or ./.claude/CLAUDE.md, for yourself in ~/.claude/CLAUDE.md. Private project notes go in ./CLAUDE.local.md, which you add to .gitignore.

How long should a CLAUDE.md be?
The docs recommend targeting under 200 lines per file. Longer files consume more context and reduce adherence.

When should I use a skill instead of CLAUDE.md?
For a multi-step procedure you only need sometimes. A skill loads its content on demand; CLAUDE.md is in context in full every session.

Sources

• Anthropic, Claude Code docs: How Claude remembers your project
• Anthropic, Claude Code docs: Extend Claude with skills
• Cursor docs: Rules
• AGENTS.md

All checked October 16, 2026.

---

An independent product by Aramac GmbH. Not affiliated with or endorsed by Anysphere (Cursor) or Anthropic. Cursor and Claude are trademarks of their respective owners.