CLAUDE.md vs SKILL.md vs Agents.md: Which Standard Should You Use?
CLAUDE.md, SKILL.md, and agents.md compared. What each does, when to use which, and how they work together.
Quick Answer: CLAUDE.md is a project-level config file for Claude Code specifically. SKILL.md is a portable skill format that works across 20+ AI agents. Agents.md is a proposed universal standard for agent configuration. Most developers should use SKILL.md for shareable capabilities and CLAUDE.md for project-specific Claude Code configuration. They work together.
Three different file standards now compete to define how AI coding agents behave. Andrej Karpathy popularized CLAUDE.md in early 2026. Anthropic formalized SKILL.md as the open standard for agent skills. And agents.md has emerged as a proposed universal alternative to vendor-specific config files. Here is how they compare and when to use each.
CLAUDE.md: project-level Claude Code configuration
CLAUDE.md is a markdown file you place in your project root to configure Claude Code's behavior for that specific codebase. It tells Claude Code your coding conventions, preferred patterns, testing requirements, and project-specific context. Andrej Karpathy's viral post about using CLAUDE.md to configure Claude Code brought widespread attention to the concept.
CLAUDE.md is powerful but limited in scope. It only works with Claude Code. It is project-specific, not portable. You cannot share a CLAUDE.md file as a reusable skill that other developers install. It is configuration, not capability.
When to use CLAUDE.md: when you want Claude Code to follow your project's specific conventions, coding standards, and patterns. Every project should have one if you use Claude Code. See Karpathy's CLAUDE.md approach for examples.
Recommended skills
AGENTS.md & Agent-Config Quality Gate — Catch Ambiguous Rules, Conflicts & Missing Guardrails Before You Ship
by PubsProToolkit
An adversarial reviewer for AGENTS.md and agent instruction files. It flags ambi…
🤖 AGENTS.md Linter
by JustHandled Labs
Lint your AGENTS.md (or CLAUDE.md and .cursorrules) for the problems that make a…
AGENTS.md and llms.txt Writer-Reviewer — Make Your Repo and Site Agent-Ready
by PubsProToolkit
Write and review the docs AI agents actually read — AGENTS.md for your repo and…
SKILL.md: portable, agent-agnostic skills
SKILL.md is the open standard for AI agent skills. A SKILL.md file teaches any compatible agent a new capability: structured code review, testing frameworks, documentation generation, security auditing, or domain-specific workflows. Skills are portable across Claude Code, Cursor, Codex CLI, OpenCode, Windsurf, GitHub Copilot, and 20+ other agents.
The key difference from CLAUDE.md: SKILL.md files are designed to be shared, sold, and installed across agents. They define a capability, not project configuration. You can browse and install 1,600+ SKILL.md skills from the Agensi marketplace, or create your own.
When to use SKILL.md: when you want reusable capabilities that work across multiple agents. Code review, testing, documentation, security auditing, and any workflow you want to share with your team or the community. See SKILL.md examples and the format reference.
Agents.md: the proposed universal standard
Agents.md is a proposed open standard that aims to do what CLAUDE.md does for Claude Code, but for every AI coding agent. Instead of each tool having its own config format (.cursorrules for Cursor, CLAUDE.md for Claude Code, etc.), agents.md would provide a single universal file.
The idea is appealing: one configuration file that works everywhere. In practice, adoption is still early. Most agents continue to use their vendor-specific formats. Agents.md is worth watching but not yet a practical choice for production use.
When to use agents.md: when broad adoption arrives and your team uses multiple agents that all support it. Until then, use CLAUDE.md for Claude Code and SKILL.md for portable skills.
Using them together
These standards are not mutually exclusive. A typical project setup:
CLAUDE.md in your project root for Claude Code-specific configuration (your conventions, patterns, testing requirements). SKILL.md skills in your .skills/ directory for capabilities you want to use across agents (code review, testing, documentation). Both serve different purposes and coexist cleanly.
For most developers in 2026: write a project CLAUDE.md if you use Claude Code, then install SKILL.md skills from the Agensi marketplace for capabilities you want to reuse across projects.