| name | init-agents |
| description | Initialize or update AGENTS.md (or CLAUDE.md for Claude Code) with AI agent guidance. Use when user says 'init agents', 'create AGENTS.md', 'setup agent instructions', or wants project-specific AI coding assistant configuration. |
Init Agents
Initialize or update AGENTS.md at project root — the instruction manual that tells AI coding assistants exactly how to work in this project.
What AGENTS.md Is
A vendor-agnostic markdown file that provides persistent, project-specific guidance to AI coding agents. Codex, OpenCode, Cursor, and GitHub Copilot read it. Claude Code uses CLAUDE.md instead — use the same content; the filename differs by tool.
Contains:
- Clear dos and don'ts (tech stack, versions, patterns)
- Executable commands (file-scoped type-check, lint, format, test)
- Project structure hints and key file locations
- Safety and permission boundaries
- Code style examples (good vs bad)
- Git workflow and PR checklist
Does NOT contain:
- Business rules (that belongs in
KNOWLEDGE.md)
- Product roadmap (not included in this document)
Tool Conventions
| Tool | File | Location |
|---|
| Codex | AGENTS.md | Project root, ~/.codex/AGENTS.md global |
| OpenCode | AGENTS.md | ~/.config/opencode/AGENTS.md global |
| Cursor | AGENTS.md or .cursor/rules/ | Project root |
| Claude Code | CLAUDE.md | Project root |
| GitHub Copilot | AGENTS.md | .github/agents/*.md for specialized agents |
Project root AGENTS.md applies to Codex, Cursor, Copilot. Claude Code expects CLAUDE.md. When user mentions Claude Code specifically, create/update CLAUDE.md; otherwise use AGENTS.md.
Six Core Areas (Best Practice)
Effective agent files cover all six:
- Commands — Executable commands with flags (put early in the file)
- Testing — How to run tests, test-first expectations
- Project structure — Key paths, where things live
- Code style — Naming, formatting, patterns with examples
- Git workflow — Commit format, PR checklist
- Boundaries — Allowed / ask first / never
Format
# AGENTS.md
This file provides guidance to AI coding agents working in this repository.
## Project Overview
[1-2 sentences: what this project is, key stack]
## Commands
# Type-check single file
npm run tsc --noEmit path/to/file.ts
# Lint single file
npm run eslint --fix path/to/file.ts
# Format single file
npm run prettier --write path/to/file.ts
# Run tests (single file or suite)
npm test -- path/to/file.test.ts
## Project Structure
- `src/` — [purpose]
- `docs/` — [purpose]
- [key files that define architecture]
## Do
- [specific rule with versions/libraries]
- [specific rule]
## Don't
- [specific prohibition]
- [specific prohibition]
## Safety and Permissions
**Allowed without prompt:** [read files, run lint/format on single file, run single test]
**Ask first:** [package installs, git push, full build, schema changes]
**Never:** [commit secrets, edit vendor/, modify production configs]
## When Stuck
- Ask a clarifying question or propose a short plan
- Do not push large speculative changes without confirmation
Process
Step 1: Explore Project
Gather in parallel:
- Tech stack (package.json, composer.json, requirements.txt, go.mod, etc.) — versions matter
- Build/lint/test commands from scripts
- Project structure and key entry points
- Existing rules (
.cursorrules, .cursor/rules/, .github/copilot-instructions.md, CONTRIBUTING.md)
KNOWLEDGE.md, if it exists — reference it, don't duplicate
Step 2: Extract Commands
Find file-scoped commands (prefer over full-project builds):
- Type-check:
tsc --noEmit, pyright, etc.
- Lint:
eslint --fix, ruff check --fix, etc.
- Format:
prettier --write, black, etc.
- Test:
vitest run, pytest, jest, etc.
Include exact flags. Put commands early in the file.
Step 3: Define Boundaries
Three tiers:
- Always do — Run lint/test on changed files, follow style examples
- Ask first — Package installs, git push, full builds, schema changes
- Never — Commit secrets, edit vendor/node_modules, modify production configs
Step 4: Add Code Examples
Point to real files that demonstrate good patterns. Call out legacy code to avoid.
Examples beat paragraphs of description.
Step 5: Write or Merge
If AGENTS.md (or CLAUDE.md) exists:
- Read existing content
- Merge new sections (don't duplicate)
- Update outdated commands and structure
- Preserve user customizations
If it doesn't exist:
- Create from template above
- Fill with discovered project context
- Keep it concise — expand over time based on agent mistakes
Companion Documents
| Document | Use When |
|---|
KNOWLEDGE.md | Business context, domain rules, gotchas — suggest init-knowledge if missing |
When running init-agents, if companion docs exist, reference them in AGENTS.md (e.g. "See KNOWLEDGE.md for business context"). Don't duplicate their content.
Rules
- Just do it — no approval needed, write directly
- Be specific — "React 18 with TypeScript and Vite" not "React project"
- Commands first — put executable commands early, with flags
- Code examples over prose — one real snippet beats three paragraphs
- File-scoped commands — prefer single-file validation over full builds
- Never commit secrets — most common and valuable boundary
- Hierarchy — project
AGENTS.md overrides global; nested AGENTS.override.md for subdirs (Codex)
- Iterate — start minimal, add detail when agents make mistakes
