October 24, 2026 · 10 min read

AGENTS.md for Codex and Claude Code. What to Include and What to Move into Skills

#codex #claude-code #coding-agents #agents-md #context-engineering #skills

An AI coding agent can understand a codebase reasonably well and still suggest a solution that makes no sense for the project.

Suppose you need to change an internal library’s interface. Instead of making a small change, the agent introduces deprecated methods, compatibility wrappers, and a migration plan. Yet the library is used by only a few applications, and all of them can be updated together.

The opposite happens too. An agent changes a public API without realizing that third-party developers depend on it.

This isn’t necessarily a problem with the model’s coding ability. Some project constraints simply aren’t visible in the source code. That’s where AGENTS.md becomes interesting. I’d like an agent to understand the repository’s important rules without creating another document that someone has to maintain forever.

How AGENTS.md works

At its core, AGENTS.md is an ordinary Markdown file. It can describe what the project does, what constraints it has, and which conventions an agent should follow when changing code.

Tools such as Codex and Claude Code can discover these files and use their contents as additional instructions. You don’t have to repeat the same project rules in every prompt.

The file usually lives at the repository root, but you can also place more specific instructions inside individual modules.

For example:

MyApp/
├── AGENTS.md
├── Sources/
├── Features/
└── MyAppUI/
    └── AGENTS.md

The root file describes the application’s general constraints. The nested one covers rules specific to MyAppUI.

Both Codex and Claude Code support AGENTS.md, although their instruction-loading behavior differs. Codex follows the file hierarchy relative to the working directory. Claude Code also supports AGENTS.md while retaining its own CLAUDE.md format.

If a repository contains both files, it’s worth checking how the tool handles their priority. This matters even more when people on the team use different coding agents.

AGENTS.md isn’t a linter, though. The model receives the instructions, but there’s no guarantee it will follow every one. The text also takes up context and may increase token usage.

The mechanism is straightforward. We provide some project knowledge in advance, and the agent uses it alongside the current task and whatever it finds in the codebase.

The harder question is what knowledge belongs in that file.

What belongs in AGENTS.md

Modern coding agents can already explore repositories. They can open Package.swift, find tests, inspect dependencies, and work out how the components fit together.

I wouldn’t spend AGENTS.md space retelling all of that, especially when the information is easy to discover directly from the code.

What matters more is information that might not be present in the repository at all.

Imagine a separate repository called MySDK. It’s a public Swift library distributed to third-party developers through Swift Package Manager.

Its AGENTS.md could start with just a few lines:

# Project

MySDK is a public Swift SDK distributed
through Swift Package Manager.

Third-party applications depend on its public API.

## Constraints

- Preserve public API compatibility.
- Do not introduce breaking changes without approval.
- Keep the SDK independent of application-specific code.

There’s nothing sophisticated here. But when the agent changes a public method, it now has a reason to think about compatibility.

If MySDK were an internal library, the rules might be different.

Say the team controls every application that uses the SDK and coordinates their releases. In that case, changing the interface and updating its consumers may be simpler than keeping an old API alive.

Of course, not every internal library works that way. A package with dozens of independently released consumers may need compatibility guarantees almost as strict as a public SDK.

These are exactly the differences worth documenting.

An agent can see how a method is implemented. It’s much harder for it to infer how freely that method may be changed.

Architecture is similar. If a project has stable constraints that aren’t obvious from its code, write them down. Listing every class, screen, and current dependency is much less useful.

And file length isn’t the only concern.

Why long instructions can get in the way

AGENTS.md can easily follow the same path as traditional project documentation.

It starts as a short file with a handful of rules. Then the agent makes a mistake, so someone adds another instruction. A week later it introduces an unnecessary abstraction, and another rule appears. Soon there are sections on testing, error handling, naming, and refactoring.

Before long, the document is hundreds of lines long.

The problem is that an agent may receive much of this material even when the task has nothing to do with it.

Research on the subject is worth looking at.

In February 2026, researchers at ETH Zürich published Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

They studied how repository instructions affect coding agents. Under their experimental conditions, automatically generated files slightly reduced task success, while developer-written files offered only modest improvements. Inference costs increased by roughly 20% or more.

The agents did follow the instructions. They explored repositories more, performed extra actions, and ran additional checks. But that activity didn’t always translate into better outcomes.

Another paper, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, published in January 2026, reported a 28.64% reduction in median task completion time.

The studies used different methods, so their results aren’t directly comparable. Together, though, they show that the value of AGENTS.md isn’t as automatic as it may seem.

In January 2026, Matt Pocock also suggested cleaning up AGENTS.md and CLAUDE.md files by removing contradictions, obvious advice, and rules that don’t need to be present for every task.

It’s hard to disagree when you come across instructions like these:

## Guidelines

- Write clean code.
- Follow SOLID principles.
- Use meaningful names.
- Avoid bugs.

All good advice, but none of it tells the model anything useful about this particular project.

That doesn’t mean I’d remove project context entirely. A few lines describing the repository and its public API constraints may do more good than pages of generic recommendations.

There’s another reason to keep instructions short. They go stale.

Imagine documenting the application’s architecture, navigation, major screens, and service locations in AGENTS.md.

A few months later, some modules have been rewritten, navigation has changed, and several components have moved into a Swift Package.

The code has changed, but the instructions haven’t.

Now the agent is reading an outdated description and may trust it instead of inspecting the current implementation.

This gets especially awkward in large applications with mixed architectures. One module uses SwiftUI, another uses UIKit, and a third has its own navigation approach.

Declaring a single architecture for the entire application in the root AGENTS.md can cause more problems than it solves.

I’d rather maintain a short set of instructions that won’t need rewriting after every refactor.

Instructions for individual modules

Let’s return to MyApp.

Suppose the application is large enough to have its own reusable UI library, MyAppUI.

MyApp/
├── AGENTS.md
├── App/
├── Features/
│   ├── Checkout/
│   └── Vouchers/
└── Packages/
    ├── MyAppUI/
    │   └── AGENTS.md
    └── MyAnalytics/
        └── AGENTS.md

The root AGENTS.md can describe the application and its general constraints.

Inside MyAppUI, I’d explain that the components are meant to be reused and shouldn’t depend on specific application screens.

# MyAppUI

This package contains reusable UI components
used across multiple application features.

## Constraints

- Keep components independent of feature-specific logic.
- Avoid dependencies on application navigation.
- Preserve existing component APIs unless a change is approved.

MyAnalytics would have different rules. For instance, it shouldn’t depend on the UI or contain business logic from individual features.

The advantage is that each set of instructions belongs to the relevant part of the project. If MyAppUI changes, there’s no need to rewrite the application’s root file.

I still wouldn’t create AGENTS.md in every directory. A separate file makes sense only when there are meaningful local constraints. Otherwise, one large document turns into ten small documents that also need maintenance.

The same applies to separate repositories.

If MyApp, MyAppUI, and MySDK live in different repositories, each can reasonably have its own AGENTS.md. Their purposes and constraints differ.

But copying identical testing or refactoring rules into all three repositories is less appealing. Those copies will eventually drift apart.

That’s where Skills fit in.

What to move into Skills

Suppose your Swift projects follow a particular testing approach. You have conventions for fixtures, mocks, asynchronous tests, and Swift Testing.

You could put several pages about all of that into AGENTS.md.

But why make the agent read detailed testing instructions when it’s only changing a small UI component?

Skills are a better fit for this kind of material.

.agents/
└── skills/
    ├── swift-testing/
    │   └── SKILL.md
    ├── api-compatibility/
    │   └── SKILL.md
    └── code-quality/
        └── SKILL.md

A Skill includes metadata describing when it should be used, along with more detailed instructions. The agent can identify a relevant Skill from that description and load its contents when needed.

That means the entire procedure doesn’t have to sit in the permanent context.

For example, swift-testing can document the team’s testing conventions. code-quality can cover readability, error handling, and refactoring. api-compatibility can describe the process for reviewing public interfaces.

Depending on the tool and installation method, the same Skill can also be reused across multiple repositories.

There is an important boundary between AGENTS.md and Skills, however.

If a repository contains a public SDK, the agent needs to know that API compatibility matters whether or not it decides to load an API compatibility Skill.

So I’d keep that constraint in AGENTS.md and move the detailed checking procedure into a Skill.

This isn’t a perfect mechanism. The agent may fail to select the right Skill, and tools differ in how they discover and load them. Still, separating permanent project context from task-specific procedures makes sense to me.

Who should write AGENTS.md

Should we ask the agent to generate AGENTS.md itself?

It sounds convenient. The agent can inspect the repository, identify architectural patterns, and produce a draft in minutes.

But there’s a catch. It can see the existing code without knowing which decisions the team still considers good and which ones are leftovers from an older architecture.

Suppose the project contains many classes ending in Manager. The model may conclude that this is a naming convention and add it as a rule.

Meanwhile, the team may have been trying to move away from those names for years.

The same problem applies to singletons, architectural patterns, and module boundaries. Just because something exists in the repository doesn’t mean it should be repeated.

I’d happily use AI to draft the file. For instance, I’d ask it to identify possible constraints and point to the code or documentation supporting each suggestion.

But I’d review and edit the final text myself.

I also wouldn’t add a new rule after every failed task. If the agent creates an unnecessary abstraction, first work out why. A clearer prompt or a pointer to an existing implementation may be enough.

AGENTS.md is worth updating when a mistake keeps recurring because of a stable project constraint that the agent really does need to know in advance.

Takeaways

AGENTS.md works best when it is short and covers only the repository’s purpose and the constraints you can’t see in the code. Detailed workflows belong in Skills, and an AI-generated draft still needs a human review.

It is also worth checking whether it helps at all. Comparing a few typical tasks with and without instructions is enough. If there is no difference, there is no point maintaining the file.