# Agents Md Setup

> 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-…

- **Type:** Skill
- **Install:** `agentstack add skill-stealth-engine-skills-agents-md-setup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [stealth-engine](https://agentstack.voostack.com/s/stealth-engine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [stealth-engine](https://github.com/stealth-engine)
- **Source:** https://github.com/stealth-engine/skills/tree/main/skills/agents-md-setup

## Install

```sh
agentstack add skill-stealth-engine-skills-agents-md-setup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/anthropics/claude-code/issues/34235).
  Re-verify against the [changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
  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:
   ```bash
   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):
   ```bash
   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

```bash
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:

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

Optionally point other tools at the same file:

```bash
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`**:

```bash
# 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//AGENTS.md`, `packages//AGENTS.md` — each with its
own sibling symlink created **from inside that directory** so the target is
relative:

```bash
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 —

```markdown
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

```markdown
# 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

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

## Conventions
- 
- Commit messages: 
- 

## Layout

```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [stealth-engine](https://github.com/stealth-engine)
- **Source:** [stealth-engine/skills](https://github.com/stealth-engine/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-stealth-engine-skills-agents-md-setup
- Seller: https://agentstack.voostack.com/s/stealth-engine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.