SKILL.md vs CLAUDE.md vs AGENTS.md: When to Use Which

The One-Line Answer

CLAUDE.md is project context for Claude Code. AGENTS.md is the same thing but cross-tool. SKILL.md is task-level capability that loads on demand. They solve different problems. Use all three.

If you only have time to maintain one file, make it AGENTS.md — it is the closest thing to a universal standard for AI coding agents in 2026, recognized by Codex CLI, Copilot CLI, Gemini CLI, Cursor, and Claude Code itself. But "one file" is a false economy. The real power comes from layering them correctly.

This article explains exactly what goes where, which tools read which files, and how to avoid the performance traps that trip up most developers.

The Comparison Table

Key takeaway from this table: CLAUDE.md and AGENTS.md serve the same purpose — persistent project context injected into every conversation. The difference is tooling compatibility. SKILL.md is fundamentally different: it is loaded conditionally, only when the task matches the skill's description. This on-demand loading is why skills exist as a separate concept, not a subsection of your CLAUDE.md.

The .cursorrules column is included for completeness. Cursor still supports it, but has migrated to .cursor/rules/ with .mdc files for granular, file-pattern-based rules. If you use Cursor alongside CLI agents, maintain .cursor/rules/ separately — its format is Cursor-specific and does not translate to other tools.

CLAUDE.md: Your Project's README for AI

CLAUDE.md is the file Claude Code reads at the start of every session. Think of it as onboarding documentation — not for a new hire, but for an AI agent that has zero memory between sessions.

What Goes In

• Architecture overview — framework, database, auth provider, major dependencies
• Code conventions — naming patterns, error handling style, import conventions
• Hard constraints — things the agent must never do (modify migrations, use certain libraries, break specific APIs)
• Build and test commands — how to run tests, lint, build

What Does Not Go In

• Task-specific workflows (those belong in SKILL.md)
• Long reference documentation (link to it instead)
• Information the agent can infer from the codebase (tsconfig.json already tells it you use TypeScript)
• Linter rules (your linter enforces those deterministically; CLAUDE.md does not)

The ETH Zurich Finding

In February 2026, researchers at ETH Zurich (Thibaud Gloaguen et al.) published "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" — the first rigorous study of whether these context files actually help. The results surprised many developers:

• LLM-generated context files reduced task success rates by about 3% compared to no context file at all.
• Human-written context files improved success by only about 4%.
• Including context files increased inference costs by over 20%.

The core problem: detailed codebase overviews are largely redundant with existing documentation, and overly restrictive instructions make it harder for agents to solve real tasks. The agent already reads your code — restating what the code says wastes context window and adds noise.

The practical implication: keep CLAUDE.md lean. Under 100 lines. Every line should pass this test: "Would removing this cause the agent to make a mistake it cannot recover from?"

A Working Example

## Project Overview
E-commerce API serving 50k DAU. Monorepo with API server and admin dashboard.

## Architecture
- Runtime: Node.js 22, TypeScript strict
- Framework: Fastify 5
- Database: PostgreSQL 16 via Drizzle ORM
- Auth: Custom JWT with refresh token rotation
- Queue: BullMQ on Redis

## Conventions
- Error handling: Result<T, E> pattern (see src/lib/result.ts)
- All endpoints validated with Zod schemas in src/schemas/
- Database queries go in src/repositories/, never in route handlers
- Tests: Vitest for unit, Supertest for integration

## Hard Constraints
- Never modify files in src/db/migrations/
- Never use default exports except in route files
- All new endpoints need integration tests before merge

## Commands
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build
- Migrate: pnpm db:migrate

That is 30 lines. It tells the agent everything it needs to work productively without restating what the code already shows.

AGENTS.md: Cross-Tool Project Context

AGENTS.md serves the same purpose as CLAUDE.md — persistent project context — but with broader tool compatibility. Originally popularized by OpenAI's Codex CLI, AGENTS.md is now an open standard stewarded by the Agentic AI Foundation under the Linux Foundation, with adoption across 60,000+ open-source repositories.

Which Tools Read It

As of March 2026, AGENTS.md is recognized by:

• Codex CLI (OpenAI) — reads it before every task
• Copilot CLI (GitHub) — auto-discovers and loads it
• Gemini CLI (Google) — supports it natively
• Cursor — reads it alongside .cursor/rules/
• Claude Code (Anthropic) — reads it as supplementary context

Claude Code reads both CLAUDE.md and AGENTS.md. Codex CLI reads AGENTS.md but not CLAUDE.md. This asymmetry creates a practical strategy:

The Strategy: AGENTS.md as Canonical Source

Maintain AGENTS.md as your single source of truth for project context. Keep CLAUDE.md minimal — use it only for Claude Code-specific instructions (like compaction behavior or permission hints) and have it reference AGENTS.md for everything else.

# CLAUDE.md

Read AGENTS.md for project architecture and conventions.

## Claude Code-Specific
- When compacting, preserve the full list of modified files
- Prefer subagents for research tasks over inline exploration

# AGENTS.md

## Project Overview
E-commerce API serving 50k DAU. Monorepo with API server and admin dashboard.

## Architecture
- Runtime: Node.js 22, TypeScript strict
- Framework: Fastify 5
- Database: PostgreSQL 16 via Drizzle ORM
...
(same content as the full CLAUDE.md example above)

This approach eliminates duplication. Teams using multiple AI tools get consistent behavior. Teams using only Claude Code lose nothing — Claude Code reads both files.

Nested AGENTS.md Files

Both AGENTS.md and CLAUDE.md support directory-level nesting. A frontend/AGENTS.md can contain frontend-specific conventions that only apply when the agent works on files in that directory. Use this for monorepos where different packages have different conventions.

SKILL.md: Specialized Capabilities on Demand

This is where things get interesting. SKILL.md is fundamentally different from CLAUDE.md and AGENTS.md. The key difference: skills are loaded only when relevant.

When you start a Claude Code session, CLAUDE.md and AGENTS.md are injected into the context window immediately. Every token in those files counts against your context budget for the entire session, regardless of what you are working on.

Skills work differently. Each skill has a description field in its YAML frontmatter. Claude Code reads all skill descriptions (short strings, cheap) and loads the full skill instructions only when the current task matches a description. This is why you do not stuff everything into CLAUDE.md — specialized knowledge should live in skills so it loads on demand, keeping your baseline context lean.

For a deeper understanding of the skills system and how to build effective skills, see the Agent Skills Guide.

Anatomy of a SKILL.md

Every skill lives in its own folder under .claude/skills/. The folder must contain a SKILL.md file with YAML frontmatter and markdown instructions.

.claude/skills/
  database-migration/
    SKILL.md
  api-endpoint/
    SKILL.md
  pr-review/
    SKILL.md

Here is a concrete example — a database migration skill:

---
name: database-migration
description: >
  Use this skill when creating, modifying, or reviewing database migrations.
  Triggers on: new migration files, schema changes, Drizzle ORM modifications,
  database column additions or removals, index changes.
---

## Database Migration Workflow

### Before Creating a Migration
1. Read the current schema in src/db/schema.ts
2. Check existing migrations in src/db/migrations/ for naming conventions
3. Verify no pending migrations exist: run `pnpm db:status`

### Creating the Migration
1. Modify the schema in src/db/schema.ts first
2. Generate the migration: `pnpm db:generate`
3. Never write migration SQL by hand — always use the generator
4. Review the generated SQL for correctness

### After Creating a Migration
1. Run `pnpm db:migrate` on the dev database
2. Run integration tests: `pnpm test:integration`
3. If tests fail, do NOT modify the migration file — drop and regenerate

### Naming Convention
- Format: NNNN_descriptive_name.sql
- Examples: 0042_add_user_preferences.sql, 0043_create_audit_log_table.sql

### Hard Rules
- Never modify an existing migration file that has been committed
- Never delete a migration file
- Always test migrations against a fresh database: `pnpm db:reset && pnpm db:migrate`

This skill contains 30+ lines of migration-specific knowledge. If this lived in CLAUDE.md, it would consume context on every session — even when you are working on frontend components. As a skill, it loads only when you ask Claude Code to create a migration or when it detects migration-related files in your task.

What Makes Skills Unique

Three capabilities set SKILL.md apart from context files:

1. Script execution. Skills can include executable scripts that Claude Code runs as part of the workflow. A deployment skill might include a pre-deploy checklist script. Neither CLAUDE.md nor AGENTS.md can do this.

2. Auto-triggering by description. The description field in frontmatter tells Claude Code when to activate the skill. Write descriptions that are slightly "pushy" — Claude Code tends to under-trigger skills rather than over-trigger them.

3. Access control. Skills support disable-model-invocation: true (only the user can trigger it), user-invocable: false (only Claude Code triggers it for background knowledge), and allowed-tools (restrict which tools Claude Code can use within the skill). This granularity does not exist in context files.

The Layering Strategy

Here is how to use all three files together for maximum effect with minimum context waste:

Layer 1: AGENTS.md (always-on, cross-tool) Project architecture, code conventions, hard constraints, build commands. Keep it under 100 lines. This is your universal project context that every AI tool reads.

Layer 2: CLAUDE.md (always-on, Claude Code-specific) Minimal. Reference AGENTS.md for shared context. Add only Claude Code-specific instructions like compaction behavior, subagent preferences, or permission hints. Under 20 lines.

Layer 3: Skills (on-demand, task-specific) Specialized workflows loaded only when relevant. Database migrations, PR review processes, deployment checklists, API endpoint patterns, test writing conventions. Each skill can be detailed (up to 500 lines) because it only enters context when needed.

The result: Your baseline context is lean (under 120 lines across CLAUDE.md + AGENTS.md), but you have deep capability available on demand through skills. This is the architecture that performs well — it respects the ETH Zurich finding (keep always-on context minimal) while still providing rich, task-specific guidance when the agent needs it.

This workspace-level configuration management — keeping context files, skills, and tool configs in sync across your development environment — is exactly where Termdock's workspace sync shines. When you switch between projects, your entire context setup (terminals, environment variables, git state) switches with you.

Decision Flowchart

When you write a new instruction for your AI agent, ask these questions in order:

"Is this relevant to EVERY task in this project?" Yes -> AGENTS.md (or CLAUDE.md if Claude Code-only) No -> Keep reading.

"Is this a specialized workflow with multiple steps?" Yes -> Create a SKILL.md in .claude/skills/ No -> Keep reading.

"Does it need to run scripts or execute commands as part of the workflow?" Yes -> SKILL.md. This is the only option that supports script execution. No -> Keep reading.

"Do you use multiple AI coding tools?" Yes -> Put shared context in AGENTS.md. Put Claude-specific instructions in CLAUDE.md. Put task workflows in SKILL.md. No (Claude Code only) -> CLAUDE.md for project context, SKILL.md for task workflows.

"Is this a Cursor-specific editor behavior?" Yes -> .cursor/rules/ with .mdc files. Keep it separate from agent context files.

For everything in between, default to AGENTS.md. It is the broadest-reaching file, and there is no downside to Claude Code reading AGENTS.md instead of CLAUDE.md — Claude Code reads both.

Common Mistakes

Mistake 1: Stuffing Everything into CLAUDE.md

The most common failure mode. Developers write 300+ line CLAUDE.md files with coding standards, architecture docs, workflow instructions, and style guides. The ETH Zurich study showed this directly: longer context files hurt performance. The agent follows some instructions, ignores others, and the inconsistency is worse than having no context file at all.

The fix: Ruthlessly prune. Move specialized workflows to skills. Move cross-tool context to AGENTS.md. What remains in CLAUDE.md should fit in a single screen.

Mistake 2: Not Using Skills at All

Many developers learn about CLAUDE.md and stop there. They never discover that skills exist, or they assume the added complexity is not worth it. This leaves significant capability on the table.

Skills are the difference between an agent that knows your project's architecture (CLAUDE.md) and an agent that knows how to execute your specific workflows (skills). The database migration example above contains institutional knowledge that would take a new developer hours to learn. With a skill, the agent has it instantly — but only when it is relevant.

If you are using Claude Code or any skill-compatible agent, start with 2-3 skills for your most common workflows. See the Agent Skills Guide for a complete walkthrough of building and installing skills.

Mistake 3: Duplicating Content Across Files

CLAUDE.md says "use Vitest for tests." AGENTS.md says "use Vitest for tests." A testing skill also says "use Vitest for tests." Three copies of the same instruction means three places to update when you switch to a different test runner — and inevitably, one gets missed.

The fix: Single source of truth. AGENTS.md holds the canonical project context. CLAUDE.md references it. Skills reference it. When a skill needs project-level information, it says "follow the testing conventions in AGENTS.md" rather than restating them.

Mistake 4: LLM-Generated Context Files

The ETH Zurich study specifically tested this: asking an LLM to generate your context file produces worse results than writing it yourself. LLM-generated files are verbose, generic, and full of restated information the agent can already see in the codebase.

Write your context files by hand. You know your project's quirks, constraints, and conventions better than any LLM can infer. The AI CLI Tools Guide has a working CLAUDE.md template you can adapt — but adapt it, do not generate it.

Mistake 5: Ignoring Cross-Tool Compatibility

If your team uses Claude Code today, it might use Copilot CLI or Codex CLI tomorrow. Building all your agent context into CLAUDE.md creates lock-in. AGENTS.md is the hedge — it works across tools today and will likely gain even broader support as the standard matures under the Linux Foundation.