New repo agent setup

Verified against Claude Code 2.1.311, Codex CLI 0.164.0, Cursor 3.27 · Updated

I do this on every new repo before I let an agent touch product code. Thirty minutes. After this, the agent has a map, two procedures it can load, and a gate that fails a bad build.

1. Create the repo and the always-on file

git init

Write AGENTS.md at the root. Keep it under 100 lines. Commands table, hard rules, links to docs you actually have. Steal the template from Your AGENTS.md is too long.

Do not write CLAUDE.md first. AGENTS.md is the source.

2. Add two or three skills

Pick procedures you will repeat this week. I start with:

  • verify-build: run the test and build commands from AGENTS.md, paste failures, stop if they fail
  • commit-hygiene: staged diff only, no secrets, conventional subject line
---
name: verify-build
description: Run this repo's test and build commands and report failures. Use when finishing a change or before a commit.
---

Run the Test and Build rows from AGENTS.md.
If a command fails, paste the last 80 lines and stop.
Do not commit on a red build.

Put each skill in its own directory with SKILL.md. name must match the directory name.

Install into the tool directories you use, or use the skills CLI:

npx skills add <owner>/<repo> -s verify-build -a claude-code -a cursor -a codex -y

Requires Node.js 22.20+.

Flags I checked in the skills CLI reference: -s/--skill, -a/--agent, -y.

In Claude Code

# one-line bridge
printf '@AGENTS.md\n' > CLAUDE.md

mkdir -p .claude/skills/verify-build
# copy SKILL.md there

Claude Code reads AGENTS.md when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md is in the working directory or any directory above it. Direct reads need v2.1.277 or later. A CLAUDE.md without an @AGENTS.md import makes Claude skip AGENTS.md, so I still write the one-line bridge. It also covers sessions that cannot load AGENTS.md: before v2.1.277, the built-in plugin disabled, or the first session after an upgrade from v2.1.276 or earlier. Project skills live in .claude/skills/.

In Codex

Leave AGENTS.md at the root. In ~/.codex and in each directory from the repo root down to where you launched Codex, it reads the first non-empty file of AGENTS.override.md, then AGENTS.md. Project skills via the CLI land in .agents/skills/.

In Cursor

AGENTS.md is enough for always-on instructions. Add .cursor/rules/ only if you need globs or alwaysApply. Project skills go in .cursor/skills/ or .agents/skills/.

Add the stop hook from Verification loops:

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": ".cursor/hooks/build-check.sh",
        "timeout": 300,
        "loop_limit": 2
      }
    ]
  }
}

Copy build-check.sh from this repo and point it at your build command.

3. Prove the wiring

  1. Open the tool. Ask: “What is the test command?” It should quote AGENTS.md.
  2. Invoke the skill. Claude Code and Cursor use /verify-build. Codex uses $verify-build, or /skills to pick it. You can also ask the agent to verify the build. The skill body should load.
  3. Break the build on purpose, stop the agent, confirm the hook or the skill reports the failure.

If step 1 fails in Claude Code, a CLAUDE.md on the path is not importing AGENTS.md, or this session cannot load AGENTS.md and the bridge file is missing. If it fails in Cursor, you are in a subdirectory that has a nested AGENTS.md you forgot about. If it fails in Codex, look for an AGENTS.override.md in ~/.codex or in a parent directory.

Checklist

  • AGENTS.md at repo root, under 100 lines, with a commands table
  • CLAUDE.md contains @AGENTS.md
  • Two skills with name matching the directory
  • Skills present in the tool directories you actually run
  • One verification hook or CI job that runs the build command
  • A throwaway session quoted the test command from the file

Sources