Skip to content

docs: add file placement and per-agent targeting guidance #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
founder-OmniPA wants to merge 1 commit into
base: main
Choose a base branch
from
+33 −2
Open

docs: add file placement and per-agent targeting guidance #193

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Below is a minimal example of an AGENTS.md file:
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
- Check the name field inside each package/package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
Expand All @@ -32,10 +32,41 @@ Below is a minimal example of an AGENTS.md file:
- Always run `pnpm lint` and `pnpm test` before committing.
```

## File placement

Place `AGENTS.md` at the root of your repository. Agents look for this file first when starting work in your codebase.

For **monorepos**, you can place additional `AGENTS.md` files inside individual packages or directories. Agents that support nested discovery merge instructions based on proximity — package-level files take precedence over the root file for work happening in that subtree:

```
my-monorepo/
├── AGENTS.md # Root-level instructions (applies everywhere)
├── packages/
│ ├── api/
│ │ └── AGENTS.md # API-specific instructions (supplements or overrides root)
│ └── web/
│ └── AGENTS.md # Web-specific instructions (supplements or overrides root)
```

## Per-agent targeting

When running multiple agents in the same codebase, you may want to give different instructions to each one. The `AGENTS.[agent].md` naming convention lets you do this without fragmented config files:

```
AGENTS.md # Shared baseline — read by all agents
AGENTS.cursor.md # Cursor-specific additions
AGENTS.codex.md # Codex-specific additions
AGENTS.copilot.md # GitHub Copilot-specific additions
```

Agents that support this convention read both `AGENTS.md` and their named override file, appending the per-agent instructions after the shared baseline. This keeps common context in one place while allowing per-tool customisation.

> **Agent authors:** to opt in, look for `AGENTS.<your-tool-name-lowercase>.md` alongside `AGENTS.md` and append its contents to the shared context you load.

## Website

This repository also includes a basic Next.js website hosted at https://agents.md/
that explains the project’s goals in a simple way, and featuring some examples.
that explains the project's goals in a simple way, and featuring some examples.

### Running the app locally
1. Install dependencies:
Expand Down