AGENTS.md, CLAUDE.md, and SKILL.md

Use AGENTS.md for shared repository instructions, CLAUDE.md where Claude-specific discovery or guidance requires it, and SKILL.md for a procedure you want to reuse. The filenames are entry points into an agent's working context. They do not all load the same way, and copying the same handbook into every file makes maintenance harder.

A useful setup answers three questions quickly: what is this repository, how do I check a change, and which special procedure applies to this task? This guide builds that setup around a small receipt-formatting project. It also explains an easy-to-miss change: current Claude Code can read AGENTS.md directly, but the presence of other instruction files affects its default behavior.

Download the starter project. It contains a working Python fixture, instruction files, a review skill, and a consistency checker. The fixture and checker were run locally. The client behavior below was checked against official documentation on October 15, 2026; it is not a claim that an agent completed every exercise.

What belongs in each file?#

Repository instructions should explain the few things a capable contributor cannot safely infer. A skill should describe an identifiable job.

Treat the root file as an orientation note, not a second copy of all your documentation. Link to longer design documents and explain when the agent needs them. A 30-page architecture history is useful during a redesign; it adds little to a one-line typo fix.

This is part of harness engineering: shaping the environment around an agent so it can find the right evidence and verify its work.

Check the client before copying a layout#

A format being shared does not make its discovery rules universal.

Codex's default combined instruction budget is 32 KiB. Its global guidance comes from its configured Codex home, and its directory chain is assembled when a run starts. Check OpenAI's AGENTS.md documentation before relying on an override or a nested layout.

Claude Code's direct AGENTS.md support requires version 2.1.277 or later and the relevant built-in support to be available. Its Project instructions setting can change what loads. A CLAUDE.md containing @AGENTS.md remains supported, including when direct loading is unavailable; the current implementation avoids loading that imported content twice. See Claude's instruction-file documentation.

For this starter, the explicit import keeps the sharing arrangement visible. It is a compatibility choice, not a claim that every current Claude installation needs a CLAUDE.md.

Start with a small working repository#

After unzipping the download, open its directory and run:

The first command exercises a receipt formatter. The second verifies the imports and distributed skill copies. The supplied tests pass, and the layout checker prints:

The structure is deliberately small:

The skills/ folder is this example's canonical authoring location. It is not presented as a universal discovery directory. Codex uses repository .agents/skills/; Claude Code uses .claude/skills/. Their documentation describes other scopes and configuration choices: Codex skills, Claude Code skills.

The two provider copies make the download easy to inspect without a build step. In a larger project, generate those copies from the canonical folder and make the consistency check part of your existing checks.

Write standing rules that change an action#

The root AGENTS.md says:

Every sentence changes something observable. The check command removes guesswork. The output constraint makes compatibility relevant. The review boundary keeps a request to inspect code from turning into an unsolicited rewrite.

Avoid instructions such as “write excellent code” or “use best practices.” They do not resolve a decision. Replace them with a concrete rule grounded in the project: “amounts are integer cents,” “the old endpoint remains supported,” or “generated files are rebuilt with this command.”

Do not add a rule for every mistake an agent has ever made. First ask whether the underlying issue belongs in a test, linter, type definition, or setup script. A mechanical check gives future contributors evidence; a growing list of admonitions gives them more text to reconcile.

Share rules without maintaining two handbooks#

The starter's root CLAUDE.md contains one line:

The file is an import, not a request that the model may choose to follow later. Put the literal line in the actual file; the Markdown fence here only shows its contents.

If you need a Claude-specific note, place it below the import. Keep shared facts in AGENTS.md so that changing the test command means editing one source.

For existing repositories, migrate incrementally:

1. Compare your current files and identify contradictory commands or conventions.
2. Move genuinely shared rules into AGENTS.md.
3. Replace duplicated text in CLAUDE.md with the import.
4. Preserve intentional client-specific notes.
5. Start fresh sessions and inspect discovery before deleting old workarounds.

Do not replace an existing CLAUDE.md wholesale just to match the example. It may contain important project knowledge. Review the diff as you would a build configuration change.

Use local rules for local constraints#

The receipt module adds one rule in src/AGENTS.md:

That matters because 125 means 125 cents, not 125 dollars. Formatting with integer division and remainder preserves that contract.

The adjacent src/CLAUDE.md imports its AGENTS.md. The root file also explicitly tells agents to read nearby instructions. This avoids assuming that an agent launched at the root has already loaded every descendant instruction file.

Run the discovery exercise from both the repository root and src/. Ask the agent to name the applicable instruction paths and the command it would run from that directory. The root-relative test command needs the repository root; a useful agent should notice that instead of executing a command from the wrong location and concluding there are no tests.

Nested instructions should narrow scope, not quietly reverse a central invariant. If root guidance says public output is stable, a module file should not casually authorize a breaking format change.

Make the occasional procedure a skill#

The starter's review skill begins:

The Agent Skills specification defines a directory-based package with a SKILL.md and optional supporting material. Keep the portable core small: a clear name, a description that identifies the task, and a procedure whose output can be inspected. Client-specific metadata should be treated as an adapter, not assumed to work everywhere.

Notice the description says when the skill applies and what boundary it preserves. “Helps with code” would match almost everything. “Review a requested receipt-code change” gives the agent a meaningful selection decision.

For larger procedures, keep detailed examples in reference files and deterministic work in scripts. The companion MCP, skills, and CLI guide explains where those pieces fit.

Test discovery separately from quality#

A file being present, a skill being selected, and a useful result are three different observations.

Use this prompt in a fresh session:

Record:

An agent saying “I followed AGENTS.md” is weaker evidence than its visible actions. Check the diff after the review. Ask it to review a harmless prose change too; the receipt skill should not force a lengthy code procedure onto unrelated work.

For a broader comparison with controls and repeated runs, use skill evaluation. The local checker in this download tests file consistency only.

Keep the setup useful as the repository changes#

Review instruction changes whenever a build command, directory boundary, or public contract changes. Remove obsolete guidance instead of adding a correction several paragraphs later.

Keep temporary investigation notes in a task checkpoint. Keep tool access in settings and credentials. Keep a skill's long reference material out of the root file. Those choices let each piece evolve without turning every session into an archaeology exercise.

Agentastic's Skills library can distribute selected skills using each supported agent's directory convention. That helps when running a parallel workflow, but it does not erase provider-specific behavior. Start with two sessions, verify what each receives, and keep the shared rules small enough that a human reviewer can understand them too.

Try the shared setup in two separate sessions: download Agentastic for macOS and open the starter project.

Frequently asked questions#

What is the difference between AGENTS.md, CLAUDE.md, and SKILL.md?#

AGENTS.md and CLAUDE.md provide standing repository instructions to clients that discover them. SKILL.md defines a reusable procedure, usually loaded when its description matches a task or you explicitly select it.

Does Claude Code read AGENTS.md?#

Current Claude Code can, beginning with version 2.1.277, subject to its Project instructions setting and plugin availability. By default, a project CLAUDE.md or CLAUDE.local.md in the working directory or an ancestor changes that behavior. Importing @AGENTS.md from CLAUDE.md is still a supported sharing approach.

Can I share one skill between Claude Code and Codex?#

You can share a portable instruction body and supporting files, but discovery locations and optional metadata differ. This starter keeps a canonical skill and checks that the two provider-specific copies remain identical.

Should every project rule become a skill?#

No. Keep frequently needed project facts and check commands in repository instructions. Use a skill for a distinct recurring procedure such as reviewing a schema migration or preparing a release.

Do instruction files enforce permissions?#

They guide the model's behavior. Enforce access restrictions through the client's permission settings, execution environment, credentials, and repository protections.