agents-md-setup

name	agents-md-setup
description	Set up a project's agent instructions as a single source of truth — AGENTS.md as the real file, with CLAUDE.md (and optionally other agents' files) as symlinks to it. Use when starting/bootstrapping a repo, when asked to "add a CLAUDE.md / AGENTS.md", "set up project conventions / agent instructions", "make Claude use AGENTS.md", or when a repo has a standalone CLAUDE.md that should become cross-tool. Also use to fix duplicated/drifting CLAUDE.md + AGENTS.md, or to add per-workspace instructions in a monorepo (Turborepo / pnpm workspaces).
metadata	{"author":"stealth-factory","co-author":"wiiiimm","version":"1.1.0"}

agents-md-setup

Make AGENTS.md the single source of truth for agent/project instructions, and point every tool's file at it via symlink. One file, read by all agents — no duplication, no drift.

Why this layout

• AGENTS.md is the emerging cross-tool standard (Cursor, Codex, and others read it).
• Claude Code reads CLAUDE.md. You cannot make the harness read AGENTS.md instead via a prompt or a skill — but a symlink CLAUDE.md → AGENTS.md means Claude opens CLAUDE.md and gets AGENTS.md's content. That is the mechanism; nothing else is needed. (True as of 2026-07: native AGENTS.md support is still an open request — anthropics/claude-code#34235. Re-verify against the changelog before relying on it; if Claude Code gains native AGENTS.md support the symlink becomes optional.)
• Result: edit AGENTS.md only; every agent stays in sync.

Decision: what's already there?

1. Neither file → create AGENTS.md from the template below.
2. Only CLAUDE.md (a real file) → make it the source of truth:

   git mv CLAUDE.md AGENTS.md       # preserve history (or: mv if not tracked)
   

3. Only AGENTS.md → keep it as-is (good).
4. Both exist as real files → do NOT blindly overwrite. Compare them; merge into AGENTS.md (it wins as the canonical file), confirm with the user if the contents differ, then remove the standalone CLAUDE.md.
5. CLAUDE.md already a symlink → AGENTS.md → already done; just confirm the target exists (link isn't dangling), then stop.
6. AGENTS.md is a symlink → CLAUDE.md (reversed) → flip it so AGENTS.md is the real file. Do not git mv the symlink onto its own target (creates a broken/self-referencing link):

   rm AGENTS.md                     # remove the symlink (the real content is in CLAUDE.md)
   git mv CLAUDE.md AGENTS.md        # CLAUDE.md becomes the real AGENTS.md
   ln -s AGENTS.md CLAUDE.md         # recreate CLAUDE.md as the symlink
   git add AGENTS.md CLAUDE.md
   

Create the symlink

ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md        # git stores it as a real symlink (mode 120000)

Verify it committed as a symlink, not a copy:

git ls-files -s CLAUDE.md          # mode should be 120000

Optionally point other tools at the same file:

ln -s AGENTS.md GEMINI.md

Most modern agents already read AGENTS.md (and often CLAUDE.md) natively — e.g. GitHub Copilot reads AGENTS.md directly (coding agent, VS Code, CLI) as of Aug 2025, so no copilot-instructions.md symlink is needed there. Only add a tool-specific symlink for older surfaces that don't yet read AGENTS.md:

# Only for legacy Copilot surfaces that predate native AGENTS.md support:
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md

Monorepos (Turborepo / workspaces)

Keep a root AGENTS.md for repo-wide conventions (with the CLAUDE.md symlink as above), then add a scoped AGENTS.md in each workspace that needs its own rules — apps/<app>/AGENTS.md, packages/<pkg>/AGENTS.md — each with its own sibling symlink created from inside that directory so the target is relative:

cd apps/web && ln -s AGENTS.md CLAUDE.md   # CLAUDE.md -> ./AGENTS.md (same dir)

• Claude Code reads the nearest CLAUDE.md for the files it's working on, so nested files supplement the root rather than replace it. Put repo-wide things at the root; put only the package-specific delta in each workspace — don't duplicate the root.
• Always make each symlink relative to its own folder (ln -s AGENTS.md CLAUDE.md while cd'd into the workspace), never pointing back at the root — relative same-dir links survive checkout/move.
• Turborepo itself doesn't read these files (they're for agents), so no turbo.json change is needed. If you want them surfaced, you can still note the convention in the root AGENTS.md.

README

If there's no README.md, scaffold a minimal one (project name, one-line description, setup/run commands). Keep human-facing docs in README.md and agent instructions in AGENTS.md — don't merge the two.

Windows / CI caveat (important)

Git symlinks need core.symlinks=true (off by default on Windows Git) and, to create them on checkout, Windows also requires either Developer Mode enabled or an elevated/admin shell. Without those they break on Windows checkouts or some CI runners (the symlink lands as a text file containing AGENTS.md). If the project targets Windows, prefer the fallback: a tiny real CLAUDE.md whose entire content is a pointer —

See [AGENTS.md](./AGENTS.md) for project + agent instructions.

— accepting that it must be kept in sync manually (or via a check). Symlink is better everywhere symlinks are reliable.

Don't undo it later

If you see CLAUDE.md as a symlink to AGENTS.md, that's intentional — edit AGENTS.md, never replace the symlink with a copy.

AGENTS.md template

# AGENTS.md

Instructions for AI agents and humans working in this repository.
`CLAUDE.md` is a symlink to this file; this file is the source of truth.

## Project overview
<what this is, in 1–3 sentences>

## Commands
- install: `…`
- dev: `…`
- build: `…`
- test / lint / format: `…`

## Conventions
- <code style, language/runtime, formatting>
- Commit messages: <e.g. Conventional Commits>
- <anything an agent must not do, or must always do>

## Layout
<key directories and what lives where>