AGENTS.md vs SKILL.md vs CLAUDE.md vs .cursorrules: Which One Should You Use?

AGENTS.md vs SKILL.md vs CLAUDE.md vs .cursorrules: Which One Should You Use?

Quick Answer: Each file serves a different purpose. AGENTS.md provides project-level context for any agent. SKILL.md packages reusable on-demand expertise. CLAUDE.md sets Claude-specific personal preferences. .cursorrules configures Cursor-specific project behavior. Most developers should use AGENTS.md + SKILL.md together — they're complementary, not competing.

---

Four different configuration files. Four different names. All of them tell an AI coding agent how to behave. If you're confused about which to use, you're not alone — this is the most common question developers ask when setting up AI coding agents in 2026.

Here's the decision tree.

The one-line summary

AGENTS.md: project context for any agent

AGENTS.md is a markdown file at the root of your repository that tells AI agents how your project works. Think of it as onboarding documentation for AI — the same information you'd give a new team member on their first day.

What goes in it:

• Build and test commands (npm run build, pytest -v)
• Project architecture (what lives where, how modules connect)
• Coding conventions (naming, patterns, style rules)
• Git workflow (branching, commit format, PR requirements)
• Security boundaries (what the agent should never touch)

What doesn't go in it:

• Task-specific workflows (use SKILL.md instead)
• Personal preferences (use CLAUDE.md instead)
• Long architectural descriptions (keep it under 150 lines)

Who supports it:

• OpenAI Codex CLI (primary format, reads from ~/.codex/AGENTS.md and repo root)
• Claude Code (reads AGENTS.md as additional context)
• GitHub Copilot (reads from .github/ directory)
• Growing adoption across other agents

Example:

# AGENTS.md

## Build & Test
- Build: `pnpm run build`
- Test: `pnpm vitest run`
- Lint: `pnpm eslint --fix`

## Conventions
- TypeScript strict mode
- Functional components only (no class components)
- Use Zod for validation, not manual checks
- Error handling: Result pattern, never throw in async

## Architecture
- API: Express + Prisma in `packages/api/`
- Web: Next.js in `packages/web/`
- Shared types in `packages/shared/`

## Don't
- Never modify `.env` files
- Never commit secrets
- Ask before adding new dependencies

SKILL.md: reusable, portable expertise

SKILL.md files package task-specific knowledge into portable, on-demand capabilities. Unlike AGENTS.md (which is always-on project context), skills activate only when relevant and deactivate when they're not.

What goes in it:

• Step-by-step procedures for specific tasks
• Checklists and decision frameworks
• Output format requirements
• Examples of good and bad output
• Edge case handling

What doesn't go in it:

• Project-specific build commands (use AGENTS.md)
• Personal coding preferences (use CLAUDE.md)
• Always-on conventions (use AGENTS.md or .cursorrules)

Who supports it:

• Claude Code, Codex CLI, Cursor, OpenClaw, Gemini CLI, GitHub Copilot, and 15+ more agents
• The most portable format — works everywhere

Example:

---
name: code-reviewer
description: Reviews code for bugs, security issues, and style. Use when the user asks to review code or check a PR.
---

# Code Review Protocol

## Check in this order

1. Security (injection, auth bypass, data exposure)
2. Logic errors (null handling, off-by-one, race conditions)
3. Performance (N+1 queries, unnecessary re-renders)
4. Style (naming, structure, patterns)

## For each issue

- File and line number
- Severity: Critical / High / Medium / Low
- What's wrong (one sentence)
- How to fix it (code suggestion)

## Don't
- Don't rewrite the code unless asked
- Don't flag style issues if there are Critical/High bugs

CLAUDE.md: Claude-specific personal preferences

CLAUDE.md is Claude Code's personal configuration file. It lives at ~/.claude/CLAUDE.md (global) or in your project root (project-specific). It's the equivalent of "my personal preferences" — how Claude should communicate with you specifically.

What goes in it:

• Response style preferences (concise, verbose, technical level)
• Language preferences
• Personal coding conventions that apply across all projects
• Tool usage preferences

What doesn't go in it:

• Project architecture (use AGENTS.md)
• Task workflows (use SKILL.md)
• Anything you want to work in non-Claude agents

Who supports it:

• Claude Code only
• Not portable to other agents

Example:

# CLAUDE.md

- Be concise. No filler phrases.
- Show diffs, not full files.
- Use TypeScript. Never suggest JavaScript.
- Default to functional patterns.
- When I say "ship it", commit and push without asking.

.cursorrules: Cursor-specific project rules

.cursorrules is Cursor's project-level configuration file. It provides always-on context that Cursor reads for every interaction within that project.

What goes in it:

• Project-specific coding conventions
• Framework and library preferences
• Component patterns and architecture rules
• Style and formatting requirements

What doesn't go in it:

• Task-specific workflows (use SKILL.md)
• Anything you want to work in non-Cursor agents

Who supports it:

• Cursor only
• Not portable to other agents

Example:

# .cursorrules

You are working on a Next.js 14 app with TypeScript, Tailwind CSS, and shadcn/ui.

Rules:
- Use server components by default
- Client components only when state or interactivity needed
- Use Zod for all form validation
- Tailwind utility classes only, no custom CSS
- All API routes in app/api/

How they work together

These files aren't competing — they're layers in a context stack. Here's how a well-configured project looks:

my-project/
├── AGENTS.md              # Project context (any agent)
├── CLAUDE.md              # Claude-specific preferences
├── .cursorrules           # Cursor-specific rules
├── .claude/skills/        # Claude Code skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── test-generator/
│       └── SKILL.md
├── .cursor/skills/        # Cursor skills (same files)
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── test-generator/
│       └── SKILL.md
└── src/

When you ask Claude Code to review a PR in this project:

1. CLAUDE.md loads your personal preferences (concise output, show diffs)
2. AGENTS.md loads project context (TypeScript, Zod validation, Result pattern)
3. code-reviewer SKILL.md loads the review protocol (check security first, then logic, then style)

The review follows your personal style, understands your project conventions, and applies a structured methodology. No single file achieves this alone.

Decision tree: which file for what

"How should this project be built?" → AGENTS.md

"How should this specific task be done?" → SKILL.md

"How should Claude talk to me?" → CLAUDE.md

"How should Cursor behave in this project?" → .cursorrules

"I want it to work in any agent" → AGENTS.md + SKILL.md (both are portable)

"I only use Claude Code" → CLAUDE.md + SKILL.md

"I only use Cursor" → .cursorrules + SKILL.md

The portability argument

If you use multiple agents — or might switch agents in the future — invest your time in AGENTS.md and SKILL.md. Both are portable. A project with a good AGENTS.md and a set of SKILL.md skills works in Claude Code today and in Codex CLI, Gemini CLI, or whatever agent you switch to tomorrow.

CLAUDE.md and .cursorrules are useful but vendor-locked. The preferences in your CLAUDE.md don't follow you to Codex CLI. Your .cursorrules don't work in Claude Code. That's fine if you're committed to one tool, but it's worth knowing the tradeoff.

The SKILL.md format was designed specifically for this portability problem. One skill, every agent, no conversion, no reformatting.

---

Browse 300+ portable SKILL.md skills at agensi.io/skills. For a deep dive on the SKILL.md format, read the SKILL.md Specification Reference.