Agent-ready repo

An agent pays for every file it has to open and every convention it has to infer. This skill makes both cheap: the conventions are written down, and one command tells the agent whether its change works.

When to use

• A new repository, right after the stack is chosen.
• An existing repository where agents repeat the same mistakes.
• Before handing a codebase to a new agent or a new teammate.

Steps

1. Read before writing. List the package manager, scripts, test runner, linter, type checker, folder layout and deploy target from the files that define them (package.json, pyproject.toml, Makefile, CI workflows). Never invent a command.
2. Make one verify command. If there is no single command that runs formatting check, lint, type check and tests, add one (npm run verify, make verify, just verify) that chains the existing ones and exits non-zero on any failure. CI should run the same command.
3. Type the environment. Load environment variables through one module that validates them at startup (Zod, Pydantic settings, envconfig). Commit an .env.example with every key and no secrets.
4. Write AGENTS.md at the root, following the template below. Keep it under about 150 lines; link to longer docs instead of pasting them.
5. Point other tools at it. If the team uses Claude Code, add a short CLAUDE.md that references AGENTS.md and holds only Claude-specific notes. Do not maintain two diverging copies.
6. Check the layout. If features are spread across type folders (controllers/, services/, components/), note it in AGENTS.md and suggest vertical-slice-feature for new work instead of a big-bang move.
7. Verify. Run the verify command yourself. AGENTS.md is done when an agent that reads only that file can run, test and ship a small change.

AGENTS.md template

# <Project>: agent guide

## What this is

One paragraph: what the product does and who uses it.

## Stack

Framework, language, database, hosting, with major versions.

## Commands

- Install: `...`
- Dev: `...`
- Verify (run before every commit): `...`
- Single test: `...`
- Migrations: `...`

## Layout

- `src/features/<feature>/`: everything for one feature (UI, logic, tests).
- `src/lib/`: shared helpers. ...

## Conventions

- Naming, error handling, validation at boundaries, how to add a route/screen/table.

## Do not

- The three to five mistakes agents actually make here, each with the right alternative.

## Done means

Verify passes, tests cover the change, and the docs above are still true.

Rules

• Every command in AGENTS.md must have been run successfully in this repo.
• Prefer rules that a tool enforces (lint rule, type, test) over prose. Prose rules go under “Do not” only when no tool can catch them.
• Update AGENTS.md in the same change that makes it wrong.
• Popular, documented tools over clever in-house ones: agents know what they have read most.

Output

The files you created or changed, the verify command and its result, and any “Do not” entries that came from mistakes found in the repo’s history.