AGENTS.md vs .cursorrules vs Claude Skills: 2026 Comparison

If your team has more than one engineer using AI coding agents, you've already discovered the configuration problem: every tool wants its own instructions file, and the rules drift apart within weeks. In 2026, three formats dominate the conversation — AGENTS.md, .cursorrules (and its successor .cursor/rules/), and Claude Code Skills. Each solves a different layer of the problem, and choosing wrong means duplicated work, broken context, and AI agents that ignore your conventions.

This guide compares all three head-to-head and shows you the 2026 best practice: a layered setup using AGENTS.md as the cross-tool standard, Skills as reusable capabilities, and a memory layer like BuildBetter CLI to make those configurations actually work across teammates and across agents. We'll also cover migration steps, anti-patterns, and where the open BB-Skills ecosystem fits.

Quick Answer: Which Should You Use in 2026?

If your team uses more than one AI coding tool, lead with AGENTS.md. If you're all-in on Claude Code, combine AGENTS.md with Claude Skills. If you're Cursor-only, migrate from .cursorrules to .cursor/rules/.

Here's the decision in one paragraph: AGENTS.md is the emerging open standard, adopted by OpenAI Codex, Cursor, Sourcegraph Amp, Aider, Zed, Google Jules, and 20+ other tools. .cursorrules is Cursor-specific and now legacy — replaced by the .cursor/rules/*.mdc directory format. Claude Code Skills are Anthropic's modular, invokable capability system, perfect for reusable workflows but Claude-ecosystem only.

• Multi-tool teams (Cursor + Claude Code + Copilot): AGENTS.md as the source of truth.
• Claude-first shops: AGENTS.md + Skills (the two are complementary, not competing).
• Cursor-only teams: Migrate from .cursorrules to .cursor/rules/ for scoped, glob-pattern rules.
• OSS maintainers: AGENTS.md — it's portable, version-controlled, and agent-agnostic.

The 2026 best practice is layered: AGENTS.md handles ambient project context ("how we code"), Skills handle invokable workflows ("how we ship a release"), and MCP handles live data access. They're three layers, not three competitors.

What Is AGENTS.md?

AGENTS.md is an open specification for providing instructions to AI coding agents in a single markdown file at the repo root. Think of it as a README for machines: humans read README.md, agents read AGENTS.md.

Launched in 2025 and backed by OpenAI, Cursor, Sourcegraph, Aider, Zed, and others, AGENTS.md has been adopted by 20,000+ open-source repositories as of early 2026. The format is intentionally minimal — plain markdown, no frontmatter required, no proprietary syntax.

Typical AGENTS.md sections

• Project overview — what this repo does in 2-3 sentences.
• Setup commands — install, build, dev server.
• Code style — formatter, linter, naming conventions.
• Testing instructions — how to run unit, integration, and E2E tests.
• PR and commit guidelines — title format, required checks.
• Security considerations — secrets handling, dependency policies.
• Deployment notes — staging, production, rollback.

The strongest argument for AGENTS.md is cross-vendor adoption. Simon Willison endorsed it as "one file, plain markdown, version controlled, agent-agnostic" — exactly the right level of abstraction. As Sourcegraph's team puts it: keep AGENTS.md task-oriented ("how to test", "how to deploy") rather than philosophical ("write clean code"). Agents respond to specifics.

What Is .cursorrules (and Why It's Being Replaced)?

.cursorrules was Cursor's original single-file format for project-specific AI rules. It's been functionally deprecated in favor of the .cursor/rules/*.mdc directory.

Cursor — with 1M+ daily active developers and $500M ARR in 2025 — moved to a directory-based system because a single file couldn't express the granularity teams needed. The new format uses MDC (Markdown Components) files with YAML frontmatter and supports four rule types:

• Always — always loaded into context.
• Auto Attached — triggered by file glob patterns (e.g., apply React rules only to **/*.tsx).
• Agent Requested — the LLM decides when to pull the rule in.
• Manual — invoked explicitly via @mention.

If you have a legacy .cursorrules file, it still works for backward compatibility, but new projects should use .cursor/rules/. The migration path is straightforward: split your rules by domain (frontend, backend, tests), give each a glob pattern, and decide which should always load vs. auto-attach.

The bigger limitation: .cursorrules and .cursor/rules/ are Cursor-only. They don't port to Claude Code, Codex, Copilot, or any other agent. If your team uses more than one AI coding tool — and most do in 2026 — Cursor-specific rules become a maintenance tax.

What Are Claude Code Skills?

Claude Code Skills are Anthropic's system for packaging reusable agent capabilities, introduced in October 2025. A Skill is a folder containing a SKILL.md file plus optional scripts, templates, and resources. Claude Code dynamically loads relevant skills based on task context using "progressive disclosure."

The fundamental difference from rules: Skills are invokable verbs; AGENTS.md and rules are ambient adjectives. AGENTS.md describes what your project is. Skills describe what your agent can do.

Examples of Skills

• A PDF generation skill that takes structured data and produces formatted output.
• A code review skill that runs your team's checklist against a diff.
• A deployment skill that knows your release runbook.
• A changelog generation skill that parses commits and writes user-facing notes.

Anthropic's Claude Code reached 115,000+ developers within four months of launch, making Skills a critical configuration primitive for a fast-growing audience. The catch: Skills are Claude-ecosystem only. They don't run in Cursor, Copilot, or Codex.

This is exactly the gap BB-Skills fills. BB-Skills is an open-source library of AI coding skills designed to work across Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Windsurf, and Amazon Q — so your team's playbook (/bb-specify, /bb-plan, /bb-review, /trust-but-verify, /generate-tests) goes with you regardless of which agent any teammate prefers.

Head-to-Head Comparison Table

When to Use Each (Decision Framework)

Use AGENTS.md if: your team uses 2+ AI coding tools, you want a future-proof standard, or you contribute to OSS. It's the single highest-leverage file you can add to a repo in 2026.

Use .cursor/rules/ if: Cursor is your only AI coding tool and you need granular, file-pattern-scoped rules (e.g., different conventions for apps/web vs. apps/api). Don't use it as your primary config if you also have Claude Code or Copilot users.

Use Claude Skills if: you need reusable, parameterized workflows that the agent can invoke. Skills shine for verbs — "generate the changelog," "run the security review," "scaffold a new service."

Combine them. The 2026 best practice is AGENTS.md for repo-wide context plus Skills (Claude Skills or open-source BB-Skills) for specific capabilities. Anthropic's official guidance treats CLAUDE.md/AGENTS.md, Skills, and MCP as three complementary layers.

Anti-patterns to avoid

• Duplicating rules across formats. If the same convention lives in AGENTS.md, .cursorrules, and CLAUDE.md, they will drift. Pick one source of truth and symlink the rest.
• Over-specifying instructions. Every token in AGENTS.md is loaded on every agent invocation. Aim for 500-2,000 tokens.
• Writing wishlists instead of executable specs. If a human can't follow it without ambiguity, neither can an agent. "Write clean code" is useless. "Run pnpm lint --fix before commit" is actionable.
• Ignoring token cost. Long AGENTS.md files eat context windows. Link to deeper docs rather than inlining them.

Migration Guide: Consolidating to AGENTS.md

If you have rules scattered across .cursorrules, CLAUDE.md, .github/copilot-instructions.md, and ad-hoc README sections, here's the consolidation path:

Step 1: Audit existing files

Search the repo for every agent-instruction file. Common locations: .cursorrules, .cursor/rules/, CLAUDE.md, .github/copilot-instructions.md, .aider.conf.yml, custom prompt files in docs/.

Step 2: Create AGENTS.md

Use the canonical sections: project overview, setup commands, code style, testing instructions, PR rules, security, deployment. Keep it under 2,000 tokens.

Step 3: Symlink or reference tool-specific files

For Claude Code, symlink CLAUDE.md → AGENTS.md. For Cursor, keep .cursor/rules/ only for Cursor-specific scoped rules that AGENTS.md can't express (e.g., glob-targeted rules for specific directories).

Step 4: Test with each agent

Open a PR and ask each agent to perform a task that should follow your conventions. Verify the rules are honored. This is where a memory layer helps — BuildBetter CLI records every coding session across agents, so you can replay how each one interpreted your AGENTS.md.

Step 5: Document and link

Add a CONTRIBUTING.md for human-facing detail and link from AGENTS.md. Delete the deprecated files (or leave a one-line stub pointing to AGENTS.md).

Real-World Examples from Production Repos

AGENTS.md for a TypeScript monorepo

# AGENTS.md

## Setup
- pnpm install
- pnpm dev (starts all apps)

## Code style
- TypeScript strict mode, no any
- Prettier + ESLint enforced via pre-commit
- Imports: @/ alias for src/

## Testing
- Unit: pnpm test (Vitest)
- E2E: pnpm test:e2e (Playwright)
- Run affected only: pnpm test --filter=...origin/main

## PRs
- Title: type(scope): description (Conventional Commits)
- Require: passing CI, 1 review, no decrease in coverage

.cursor/rules/ structure

• .cursor/rules/frontend.mdc — glob: apps/web/**, React/Tailwind conventions.
• .cursor/rules/backend.mdc — glob: apps/api/**, Fastify and Drizzle patterns.
• .cursor/rules/tests.mdc — glob: **/*.test.ts, Vitest patterns.

BB-Skill for changelog generation

A SKILL.md describing how to parse commits since the last tag, group by Conventional Commit type, and produce a user-facing changelog. Invoked via /bb-changelog from any of seven agents.

How Product Teams Should Think About AI Agent Configuration

Engineering productivity is downstream of clear customer signal — agents need to know what to build, not just how to build it. AGENTS.md handles "how we code." It does not, by itself, tell your agents what customers actually need.

This is the gap most engineering orgs underinvest in. You can have a pristine AGENTS.md, beautifully scoped .cursor/rules/, and a library of Skills — and still ship the wrong feature because the spec was written from assumption rather than evidence.

The 2026 pattern emerging at teams like Brex, Rappi, PostHog, and AppFolio: feed validated customer requirements into agent context alongside AGENTS.md. BuildBetter CLI connects customer evidence from BuildBetter.ai directly into the spec workflow. When an engineer runs /bb-specify or /bb-plan, the agent sees not only the team's coding conventions but the actual customer signal that drove the work.

Combined with cross-agent session memory — every coding conversation indexed and resumable across teammates — you get a configuration stack that's grounded in customer evidence rather than guesses. AGENTS.md tells the agent how to write code. BB-Skills tell it which workflows to follow. BuildBetter tells it what customers asked for.

The Future: Where Agent Configuration Is Heading in 2026 and Beyond

Open standards are winning, tool-specific files are fading, and the configuration layer is splitting cleanly into three: ambient context (AGENTS.md), invokable capabilities (Skills), and live data access (MCP).

• MCP integration with AGENTS.md. Model Context Protocol, released by Anthropic in November 2024 and now an industry standard, gives agents live tool and data access. Expect AGENTS.md sections that declare available MCP servers and how to use them.
• Skills marketplaces. Shared, versioned, reviewed capabilities across teams and companies. BB-Skills on GitHub is one early example — open source, contributable, and cross-agent.
• Convergence. The era of .cursorrules, copilot-instructions.md, and .aider.conf.yml as separate sources of truth is ending. Teams want one file the whole stack reads.
• Watch list: agent.json proposals for richer metadata, IDE-native skill registries, and enterprise governance layers for approving which skills run on production codebases.

The 76% of developers using or planning to use AI coding tools (Stack Overflow 2025) means standardization is no longer optional — it's a productivity prerequisite.

Frequently Asked Questions

Can I use AGENTS.md and .cursorrules in the same repo?

Yes. Cursor reads both, but precedence and duplication can cause drift. Best practice in 2026 is to migrate fully to AGENTS.md (which Cursor supports natively) and delete .cursorrules, or keep .cursor/rules/ only for Cursor-specific scoped rules that AGENTS.md can't express.

Does Claude Code read AGENTS.md?

Yes. Claude Code reads CLAUDE.md by default and as of 2025-2026 updates also recognizes AGENTS.md. Many teams use a symlink (CLAUDE.md → AGENTS.md) so a single source of truth serves both.

Is .cursorrules deprecated?

Functionally yes. Cursor recommends migrating to .cursor/rules/*.mdc for new projects. The single-file format still works for backward compatibility but lacks scoping, file-pattern triggers, and rule types available in the directory format.

How long should AGENTS.md be?

Aim for 500-2,000 tokens (roughly 1-3 pages). Every token is loaded on every agent invocation, eating into your context window. Link to deeper docs (CONTRIBUTING.md, ADRs) rather than inlining them.

Do Claude Skills work outside Claude Code?

As of 2026, Claude Skills are Claude-ecosystem only (Claude Code, Claude.ai, Claude Desktop). They're not portable to Cursor, Copilot, or Codex. If portability matters, use BB-Skills, which works across seven agents, or encode the workflow in AGENTS.md.

Should AGENTS.md be committed to git?

Yes. It's project-level guidance, like a README. Version it, review changes in PRs, and treat updates as part of your engineering workflow.

Ship at the Speed of Insight

AGENTS.md, .cursor/rules/, and Claude Skills each solve a piece of the agent configuration puzzle. The hard part isn't picking one — it's making them work together across every teammate, every agent, and every customer signal that should be driving the code you ship.

BuildBetter CLI is the memory and skills layer that makes the whole stack compound. Cross-agent session memory so context never dies. Open-source BB-Skills that carry your team's playbook into Claude Code, Cursor, Codex, Copilot, Gemini, Windsurf, and Amazon Q. Customer evidence pulled from BuildBetter.ai into specs and PR reviews so you build what customers actually asked for.

Install BuildBetter CLI →