New repo agent setup

Verified against Claude Code 2.1.263, Codex CLI 0.153.4

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 18+.

Flags I verified in the skills CLI README: -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 CLAUDE.md, not AGENTS.md. The @AGENTS.md import is the documented bridge. Project skills live in .claude/skills/.

In Codex

Leave AGENTS.md at the root. Optional personal overrides go in AGENTS.override.md (gitignored) or ~/.codex/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 /verify-build (or ask it 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, your CLAUDE.md 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, check ~/.codex/AGENTS.override.md.

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