Claude Code Mods and agents.md: What's New and Why It Matters
Claude Code now reads agents.md files and supports "mods," a plugin system for customizing the coding harness itself. Here's how both work.
What is agents.md support in Claude Code?
Claude Code can now read instructions from an agents.md file, a shared instruction format that multiple coding agents already understand. If a project has no Claude-specific file like claude.md, Claude Code will use agents.md by default instead. This shipped on September 18, in version 2.1.277, and it means teams running more than one coding agent on the same codebase no longer have to maintain duplicate instruction files for each tool.
TL;DR
- agents.md compatibility landed in Claude Code version 2.1.277 on September 18, letting the tool read project instructions from a shared file format instead of requiring a Claude-only file.
- Priority rules matter: if a project already has
claude.md, that file takes priority by default, though you can configure Claude Code to load both files under project instructions in/config. - Mods are the real story: agents.md support was built as an internal “mod,” a plugin that hooks into Claude Code’s harness (the software layer that assembles context, calls tools, and renders the session) rather than the model itself.
- Four built-in mods currently ship in the public repository: the agents.md loader, a diff panel, telemetry, and an organization security mod, and developers can inspect how each is implemented.
- Custom mods are early access only, gated behind function hooks that Anthropic warns may change between releases, so the broader plugin ecosystem is still forming even though this first mod is live.
- Related features shipped alongside it, including a redesigned Projects beta that coordinates multiple work threads, background computer use on desktop, and a
/plugin evalcommand for testing whether a plugin actually improves results. - Availability is limited: agents.md support isn’t yet available on Bedrock, Vertex, or Foundry, and the new Projects beta is restricted to select Pro and Max subscribers using cloud sessions.
Remy doesn't write the code. It manages the agents who do.
Remy runs the project. The specialists do the work. You work with the PM, not the implementers.
How does agents.md work inside Claude Code?
An instruction file like agents.md typically documents how to run tests, which package manager a project uses, and which folders contain generated code that shouldn’t be touched. Claude Code now parses this file automatically, provided the project doesn’t already have a claude.md. That default behavior is configurable: you can go into project instructions under /config and tell Claude Code to load both files together, giving you shared cross-agent guidance plus Claude-specific instructions layered on top.
The practical benefit is avoiding duplicate maintenance. If a team already writes agents.md for one coding assistant and wants to try Claude Code without rewriting everything, it now works out of the box. That said, reading a file is not the same as following it perfectly. Instructions still need to be specific and checked against actual output, especially early on while you calibrate how reliably Claude Code applies them.
One limitation worth noting: at launch, this support does not extend to Bedrock, Vertex, or Foundry deployments, so teams running Claude Code through those platforms won’t see the same behavior yet.
What exactly is a “mod” in Claude Code?
The harness is the layer of software wrapped around the underlying model. It handles assembling context, invoking tools, and displaying the session to the user. It is distinct from the model’s weights or training, and it’s the part of the system that determines how information flows in and out of a conversation.
A mod is a plugin that hooks into that harness using function hooks, letting developers change its behavior with code. Anthropic’s early examples include changing interface components and filtering tool output before it ever reaches the model. Agents.md support is itself implemented as a mod: it’s a concrete case of customizing which project instructions get loaded and passed into context.
Four mods currently exist in the public repository:
- The agents.md loader, which handles the instruction file logic described above.
- A diff panel mod, which adds a live view of changed files during a session.
- A telemetry mod.
- An organization security mod.
Because these are open in the repository, developers can inspect the actual implementation rather than guessing at how the feature works internally.
Why does the mods system matter more than agents.md itself?
Agents.md support solves an immediate, narrow compatibility problem: fewer duplicate instruction files across tools. But the way Anthropic built it signals something bigger. By expressing that feature as a mod rather than hardcoding it into the harness, Anthropic is showing what the emerging plugin system is capable of and inviting developers to build similar hooks themselves.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
Custom mods are still early access, and the documentation is explicit that function hooks must be enabled and that the API can change between releases. That means the four built-in mods are stable and shipped, but a broader ecosystem of third-party mods isn’t mature yet. For developers building specialized coding workflows, this is the piece worth tracking: once the interface stabilizes, mods could let teams control exactly which instructions, tools, or output filters apply to different parts of a large project, rather than loading every rule into every task.
What else shipped alongside mods and agents.md?
Several related updates landed in the same window (roughly August 20 through September 18):
Diff panel. Shipped September 3 in version 2.1.260, this adds a live panel next to the conversation in full-screen mode, showing changed files and line counts as Claude edits code or runs commands. You can select specific lines to reference in your next message. It requires a git repository and a terminal at least 110 columns wide. This makes it easier to point at a specific change and explain what needs fixing, without losing the conversation thread.
Redesigned Projects (beta). Announced September 17, this introduces a coordinator that breaks a project into separate threads, delegates tasks, and reviews results. Each thread runs as a cloud-based Claude Code session with its own branch and repository copy, and threads share project memory. Because sessions run in the cloud, work can continue after you close your laptop. Access at launch is limited to select Pro and Max subscribers using cloud sessions who don’t already have projects set up on web or desktop; team, enterprise access, and local execution are planned for later. Running multiple threads in parallel will consume your usage allowance faster, so it’s worth weighing coordination benefits against cost.
Background computer use. Rolled out the week of August 31 through September 4 for desktop users on macOS 15 or later. In beta for Pro and Max subscribers, this lets Claude work inside approved apps while you continue using your computer for other things. It’s aimed at tasks inside native apps that lack a useful command-line interface. You approve which apps Claude can access, and the desktop app needs to keep running (and your machine needs to stay awake) while it works.
Terminal-to-desktop handoff. From the August 24 update window, you can use a slash command in the desktop app to continue a session that was started in the terminal, keeping its conversation and context intact.
Model support: Sonnet/Opus-class update. A new model, referred to as “5.1,” launched September 4 with a 1 million token context window, and Claude Code supports it starting in version 2.1.257. One gotcha: some Claude API gateways alias older model names to newer ones automatically, but that alias doesn’t cover 5.1, so a gateway serving it needs the explicit model name specified. Usage may draw from separate credits depending on your plan.
Skill and plugin tooling. /skill doctor, added in early September, shows the context cost and usage of your skills, which is useful because even unused skills occupy context space just by being listed. Version 2.1.269, released September 11, added claude plugin eval, which runs test cases and scoring checks against a plugin, comparing results with and without it enabled. Because it uses real model calls, running evaluations consumes usage, but it gives a concrete before/after read on whether a plugin is worth keeping.
Frequently Asked Questions
Does Claude Code prioritize agents.md or claude.md?
- ✕a coding agent
- ✕no-code
- ✕vibe coding
- ✕a faster Cursor
The one that tells the coding agents what to build.
By default, if a project has its own claude.md file, those instructions take priority over agents.md. You can change this in /config under project instructions to load both files together instead.
What is the difference between a mod and a skill in Claude Code?
A mod customizes the harness itself (context assembly, tool calls, interface rendering) using function hooks. A skill is more like a packaged capability the model can invoke during a session. /skill doctor helps you audit skill context costs, while mods change how the surrounding system behaves.
Can I build my own custom mod right now?
Custom mods are in early access. Function hooks need to be enabled, and Anthropic notes the API can still change between releases, so building on it today means expecting some instability.
Is the new Projects beta available to everyone?
No. At launch it’s limited to select Pro and Max subscribers using cloud sessions who don’t already have projects set up on web or desktop. Team, enterprise access, and local execution are planned for later.
Does agents.md support work on all Claude deployment platforms?
Not yet. At launch, Anthropic states this support isn’t available on Bedrock, Vertex, or Foundry.
