Why Agent Skills Took Off: CLAUDE.md vs AGENTS.md vs SKILL.md

Here is the short answer:

CLAUDE.md and AGENTS.md describe how an agent should generally work in a project. SKILL.md describes a reusable procedure to load when a particular kind of task appears.

They all influence coding agents, but they do not have the same lifecycle. A giant project instruction file consumes context in every session. Turning every repository convention into a skill creates the opposite problem: the agent may miss rules it always needed to know.

The important idea behind Agent Skills is not another Markdown filename. It is the separation between capability discovery and loading the full operating manual. An agent can see compact metadata at startup, then load the complete procedure, scripts, and references only when a task matches.

This article uses official Agent Skills, Anthropic, OpenAI, and AGENTS.md documentation checked on July 19, 2026. It also reports a minimal two-call A/B probe run through a local Hermes Agent endpoint.

The three files at a glance

File	What it is	Typical content	When it loads	Best use
CLAUDE.md	Persistent Claude Code user or project instructions	Build commands, coding rules, architecture, recurring pitfalls	Ancestor files at startup; descendant rules as relevant files are accessed	Facts Claude Code should know in every session
AGENTS.md	An open project-instruction format for coding agents	Setup, tests, directory ownership, contribution rules	Client-defined; Codex builds a root-to-current-directory chain	Sharing repository guidance across coding agents
SKILL.md	The entry point of an Agent Skill	Trigger description, procedure, decisions, acceptance criteria	Usually after task matching or explicit invocation	On-demand workflows such as releases, audits, and migrations

A practical rule:

• if the agent should know it on every task, put it in CLAUDE.md or AGENTS.md;
• if it matters only for a class of tasks, make it a Skill;
• if it must be enforced, use permissions, sandboxes, hooks, or policy—not Markdown alone.

SKILL.md is not a renamed project prompt

A portable Skill is a directory with at least one entry file:

release-note/
├── SKILL.md
├── scripts/       # Optional deterministic programs
├── references/    # Optional detailed material
└── assets/        # Optional templates and resources

A minimal entry point looks like this:

---
name: release-note
description: Create release notes that follow the team's exact format. Use when preparing a product release.
---

# Release note workflow

1. Read the release policy.
2. Group changes by type.
3. Render the approved template.
4. Run the validation script.

The open specification requires name and description, followed by Markdown instructions. Optional fields include license, compatibility, metadata, and the currently experimental allowed-tools.

Clients can add extensions. Claude Code invocation controls and subagent options, or Codex's agents/openai.yaml, are not automatically portable to every Skills-compatible client.

Progressive disclosure is the useful part

The Agent Skills model has three layers:

1. Metadata: name and description are visible at startup so the agent can decide whether the Skill is relevant.
2. The SKILL.md body: full instructions load after matching or explicit invocation.
3. Scripts and references: supporting material is read or executed only when needed; untouched files stay out of context.

This resolves a real tension. Teams want agents to know more operating procedures, but they do not want every conversation to carry every manual.

Anthropic's current architecture guidance describes roughly 100 tokens of startup metadata per Skill and recommends keeping a triggered body below about 5K tokens. Those are product-level approximations, not universal limits. OpenAI Codex uses a separate budget for its initial Skill list: normally up to 2% of the context window, or 8,000 characters when the window size is unknown. A selected Skill's full body loads afterward.

On-demand loading is therefore not free. Metadata has a discovery cost, and a triggered workflow increases input size. The useful question is whether that cost prevents omissions, exploration, and rework.

CLAUDE.md: durable Claude Code context

Good candidates include:

• use pnpm, not npm;
• standard test and build commands;
• directory responsibilities and architecture constraints;
• coding conventions that apply to every change;
• stable project-specific traps.

Claude Code searches upward from the working directory for CLAUDE.md and CLAUDE.local.md, adding discovered files to context. Instructions below the current directory are generally loaded as Claude works with files in those subtrees. Files can import other material with @path.

The crucial boundary is enforcement. Anthropic describes these files as context, not hard configuration. Conflicting prose is not a deterministic policy engine. Use permissions or hooks for rules that must never be bypassed.

Does Claude Code read AGENTS.md directly?

As of the documentation checked for this article, it does not treat AGENTS.md as an automatic replacement for CLAUDE.md. Anthropic documents an import pattern:

# CLAUDE.md
@AGENTS.md

## Claude Code

- Put Claude Code-specific notes here.

A symlink is another option:

ln -s AGENTS.md CLAUDE.md

So “Claude Code natively reads AGENTS.md” is too broad.

AGENTS.md: a README for coding agents

The official AGENTS.md site calls it a “README for agents.” It provides a predictable home for details that need not clutter a human README:

# AGENTS.md

## Setup
- Install dependencies with `pnpm install`.

## Tests
- Run `pnpm test` before reporting completion.

## Conventions
- Do not edit generated files.

Codex documents a specific discovery chain:

1. inspect AGENTS.override.md or AGENTS.md in Codex home;
2. walk from project root to the current directory;
3. select at most one matching file per directory;
4. append closer instructions later so they can refine earlier guidance;
5. stop when project instruction content reaches its default 32 KiB limit.

That is Codex behavior, not a universal algorithm mandated by the AGENTS.md ecosystem. Support and merge semantics remain client-specific.

A real two-call comparison

To avoid turning architecture claims into marketing, I ran a narrow experiment. This is not a broad coding-agent benchmark. It asks one question: when a task has a team-specific output contract, does an on-demand procedure improve compliance?

Controls:

• the same local Hermes Agent API;
• the same hermes-agent model route;
• temperature: 0;
• two independent requests;
• the same base task;
• the second request additionally received one release-note Skill body;
• no production system, real repository, or external data.

The base request supplied only three release changes and asked for release-note.md. The Skill preregistered eight machine-checkable requirements: an exact H1, four exact sections, two unchecked verification items, and backticks around the API path. The score was defined before reading either response.

Raw results

Metric	No Skill	With Skill	Difference
Runs	1	1	—
Instruction hits	3/8	8/8	+5 items
All requirements satisfied	No	Yes	—
Input tokens	15,204	15,354	+150
Output tokens	44	61	+17
Total tokens	15,248	15,415	+167
Output characters	139	220	+81

The No-Skill response was a valid generic release note:

# 2.4.0

## Added

- OAuth device flow

## Fixed

- Duplicate webhook delivery

## Breaking Changes

- `/v1/events` now requires `event_id`

It could not infer the team's required v prefix, Verification section, or two checklist items.

The With-Skill response was:

# v2.4.0

## Added

- OAuth device flow

## Fixed

- Duplicate webhook delivery

## Breaking changes

- `/v1/events` now requires `event_id`

## Verification

- [ ] Migration guide reviewed
- [ ] Changelog links verified

What this proves—and what it does not

For these two controlled calls, adding 150 input tokens moved team-specific compliance from 3/8 to 8/8.

It does not prove that:

• Skills improve every coding task;
• other models and clients produce the same outcome;
• Skills always save tokens—the total increased by 167 here;
• implicit matching is reliable—the experiment supplied the Skill body directly;
• the difference is statistically significant—each condition ran once.

A stronger benchmark would interleave repeated trials and preserve tool events, file reads, test results, and diffs. Publishing the raw one-shot output is more honest than turning it into a universal “success-rate improvement” claim.

A repository layout that keeps the roles clear

repo/
├── AGENTS.md                         # Cross-agent repository rules
├── CLAUDE.md                         # @AGENTS.md plus Claude-specific notes
├── .claude/skills/release/SKILL.md   # Claude Code project Skill
└── .agents/skills/release/SKILL.md   # Codex and compatible client Skill

Design rules:

1. Keep project instructions short and stable. Include only facts relevant to most work.
2. Make Skills task-specific. One directory should own one recognizable workflow.
3. Write a precise description. Say both what the Skill does and when to use it.
4. Move detail into references. Do not turn the main workflow into an encyclopedia.
5. Use scripts for deterministic work. Formatting, schema checks, and builds should not depend on guessing.
6. Do not duplicate conflicting rules. A Skill should follow project policy, not fork it.
7. Enforce security in the execution layer. Markdown is not an authorization system.

Common misconceptions

“A Skill is just a saved prompt”

Incomplete. A Skill is a metadata-bearing directory that can package scripts, references, and templates, loaded through progressive disclosure.

“Skills are MCP or plugins”

No. Skills carry procedural knowledge and local resources; MCP connects external tools and context. They compose well. In OpenAI's current terminology, a Plugin can also package and distribute Skills, connectors, or MCP integrations.

“SKILL.md always overrides AGENTS.md”

There is no cross-client rule. Discovery, merge order, and conflict handling are implementation details, and higher-level system or permission rules remain above repository prose.

“Putting everything in Skills minimizes context”

Not necessarily. If the standard test command is hidden behind a Skill that never triggers, the agent may miss it. Durable and on-demand context need separate homes.

“One Skill behaves identically everywhere”

The open format creates a portable baseline, but extension fields, paths, precedence, budgets, and tool authorization still vary by client. Keep the core procedure inside standard fields when portability matters.

What this means for multi-model agent teams

Once a team uses Claude Code, Codex, and other agents together, prompt management becomes a three-layer system:

1. Project layer: repository rules and quality gates;
2. Capability layer: reusable release, audit, and migration workflows;
3. Model access layer: common model routing, usage, and cost records.

Nbility operates at the third layer. It does not replace AGENTS.md or Skills, but it can give multiple agents one API entry point with centralized request, token, and cost records. As this experiment shows, a Skill may add per-call input cost while avoiding omissions and rework. You need end-to-end usage records to judge the net effect.

You can run controlled multi-model comparisons through Nbility. For a small test credit, contact support through the ticket system.

Official sources

• Agent Skills overview
• Agent Skills specification
• Claude Code Skills
• Claude Code project instructions and memory
• OpenAI Codex: AGENTS.md
• The open AGENTS.md format

Paths, precedence, context budgets, and extension fields in this area evolve quickly. The behavior above was checked on July 19, 2026.