AGENTS.md Generator

/init

Set up a minimal AGENTS.md optimized for agent performance. AGENTS.md is loaded into every your coding CLI session, so it must stay compact and high-signal.

Optimization policy:
- Hardcode AGENTS.md as the instruction file target. Do not generate any alternate instruction filename.
- Treat AGENTS.md as a living friction log, not a codebase overview.
- Before adding any line to AGENTS.md, ask: can the agent discover this by reading the repo, docs, manifests, CI, or config? If yes, do not include it.
- Do not include directory trees, tech stack summaries, architecture overviews, module catalogs, or generic best-practice filler.
- Prefer operational landmines only: tooling gotchas, non-obvious conventions, unsafe legacy traps, deployment pitfalls, and commands the agent would otherwise guess wrong.
- If a problem can be fixed in code, linting, tests, hooks, or automation, prefer fixing the root cause over adding another persistent instruction.
- Prefer scoped AGENTS.md files in subdirectories for module-specific rules instead of bloating the root file.
- Avoid mentioning legacy or incidental patterns unless they are still operationally relevant for current work.
- Remove stale instructions once the underlying issue is fixed.

## Phase 1: Ask what to set up

Use AskUserQuestion to find out what the user wants:

- "Which AGENTS.md files should /init set up?"
  Options: "Project AGENTS.md" | "Personal AGENTS.local.md" | "Both project + personal"
  Description for project: "Team-shared operational instructions checked into source control."
  Description for personal: "Your private preferences for this project (gitignored, not shared) such as role, sandbox URLs, and workflow quirks."

- "Also set up skills and hooks?"
  Options: "Skills + hooks" | "Skills only" | "Hooks only" | "Neither, just AGENTS.md"
  Description for skills: "On-demand capabilities you or the agent invoke with `/skill-name` for repeatable workflows."
  Description for hooks: "Deterministic shell commands that run on tool events, such as formatting after edits."

## Phase 2: Explore the codebase

Launch a subagent to survey the codebase and read key files: manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, etc.), README, Makefile/build configs, CI config, existing AGENTS.md, .codex/rules/, .cursor/rules or .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules, .mcp.json.

Detect:
- Build, test, and lint commands the agent could guess wrong
- Languages, frameworks, and package manager only as working context; do not copy them into AGENTS.md unless they imply a non-obvious rule
- Project structure only to decide whether scoped subdirectory AGENTS.md files are needed
- Code style rules that differ from language defaults
- Non-obvious gotchas, required env vars, workflow quirks, and legacy hazards
- Existing .codex/skills/ and .codex/rules/ directories
- Formatter configuration (prettier, biome, ruff, black, gofmt, rustfmt, or a unified format script like `npm run format` / `make fmt`)
- Git worktree usage via `git worktree list` if the user wants a personal AGENTS.local.md

For every candidate note, apply this filter:
- If the agent can discover it quickly from the repo, exclude it from AGENTS.md.
- If it is broad explanatory prose instead of a concrete operational constraint, exclude it.
- If it belongs to one subsystem only, prefer a scoped AGENTS.md near that subsystem instead of the root file.

Note what you could NOT figure out from code alone. Those become interview questions.

## Phase 3: Fill in the gaps

Use AskUserQuestion to gather only the missing information needed to write good AGENTS.md files and skills. Ask only things the code cannot answer.

If the user chose project AGENTS.md or both: ask about non-obvious commands, workflow traps, branch or PR conventions, required env setup, testing quirks, and landmines. Skip anything already obvious from the repo.

If the user chose personal AGENTS.local.md or both: ask about the user, not the codebase. Examples:
  - Their role on the team
  - Their familiarity with this codebase and its languages/frameworks
  - Personal sandbox URLs, test accounts, API key paths, or local setup details
  - Communication preferences such as "be terse" or "always explain tradeoffs"

Synthesize a proposal from Phase 2 findings, but only include items that survive the optimization policy:
- Hook if it should be enforced mechanically on a tool event
- Skill if it is an on-demand workflow
- AGENTS.md note only if it is truly non-discoverable and not better enforced elsewhere

Respect the Phase 1 skills/hooks choice as a hard filter. Never propose an artifact type the user did not opt into.

Show the proposal via AskUserQuestion's `preview` field, not as a separate text message. Keep previews compact and operational.

Build the preference queue from the accepted proposal. Each entry: {type: hook|skill|note, description, target file, any discovered command or workflow detail}. Phases 4-7 consume this queue.

## Phase 4: Write AGENTS.md (if user chose project or both)

Write a minimal AGENTS.md at the project root. Every line must pass both tests:
- Would removing this make the agent more likely to make a mistake?
- Could the agent discover this by inspecting the repo on demand?

If the answer to the first is no, cut it.
If the answer to the second is yes, cut it.

Consume `note` entries from the Phase 3 preference queue whose target is AGENTS.md.

Include only:
- Commands the agent is likely to guess wrong
- Code style rules that differ from defaults
- Testing quirks and validation traps
- Repo etiquette only when it changes how the agent should operate
- Non-obvious setup steps, landmines, and architectural hazards
- Important constraints from existing AI tool configs only when they are still operationally relevant

Exclude:
- File-by-file structure or component lists
- Standard language conventions the agent already knows
- Generic advice such as "write clean code" or "handle errors"
- Detailed API docs or long references; use `@path/to/import` instead
- Information that changes frequently if the source can be referenced directly
- Legacy patterns that should not bias new work unless the repo still depends on them

Prefix the file with:

```
# AGENTS.md

This file provides guidance to your coding CLI (developers.openai.com/codex) when working with code in this repository.
```

If the repo has distinct subdirectories or modules with different constraints, prefer additional scoped AGENTS.md files near those directories over expanding the root file.

If AGENTS.md already exists: read it, propose specific diffs, and remove stale or redundant lines instead of only appending more text.

## Phase 5: Write AGENTS.local.md (if user chose personal or both)

Write a minimal AGENTS.local.md at the project root. This file is automatically loaded alongside AGENTS.md. After creating it, add `AGENTS.local.md` to the project's .gitignore so it stays private.

Consume `note` entries from the Phase 3 preference queue whose target is AGENTS.local.md.

Include:
- The user's role and familiarity with the codebase
- Personal sandbox URLs, test accounts, or local setup details
- Personal workflow or communication preferences

Keep it short and user-specific.

If Phase 2 found multiple git worktrees and the user confirmed they use sibling/external worktrees: write the real personal content to `~/.codex/<project-name>-instructions.md` and make AGENTS.local.md a one-line stub importing it with `@~/.codex/<project-name>-instructions.md`.

If AGENTS.local.md already exists: propose precise additions instead of overwriting it.

## Phase 6: Suggest and create skills (if user chose "Skills + hooks" or "Skills only")

Skills add capabilities the agent can use on demand without bloating every session.

First, consume `skill` entries from the Phase 3 preference queue.
Then suggest additional skills only when they capture repeatable workflows or subsystem-specific knowledge better than root-level prose.

If `.codex/skills/` already exists, review it first and only propose complementary skills.

Create each skill at `.codex/skills/<skill-name>/SKILL.md`:

```yaml
---
name: <skill-name>
description: <what the skill does and when to use it>
---

<Instructions for the agent>
```

For workflows with side effects, add `disable-model-invocation: true` and use `$ARGUMENTS` to accept input.

## Phase 7: Suggest additional optimizations

Tell the user you are suggesting a few optimizations now that AGENTS.md and skills (if chosen) are in place.

Check the environment and ask about each applicable gap:
- GitHub CLI if missing and the project uses GitHub
- Linting if the project lacks lint configuration
- Proposal-sourced hooks if the user opted into hooks

When a repeated agent mistake could be prevented mechanically, prefer suggesting a hook, linter rule, test, or CI guard over a permanent AGENTS.md note.

Consider whether the repo would benefit from a lightweight maintenance workflow for pruning stale AGENTS.md lines as the codebase evolves.

## Phase 8: Summary and next steps

Recap what was set up and why each file exists.

Remind the user that AGENTS.md is not a permanent dumping ground. It should stay small, focus on non-discoverable landmines, and lose lines as the underlying friction gets fixed.

Present any follow-up suggestions as a short, relevant to-do list ordered by impact.