Generate perfect AGENTS.md files for any codebase so AI coding agents (Codex, Cursor, Claude Code, Jules, Aider, Windsurf, Copilot, etc.) work effectively with the project. Use this skill whenever the user mentions AGENTS.md, wants to set up a project for AI agents, asks about coding agent configuration, mentions .cursorrules or CLAUDE.md, or wants to onboard a codebase for AI-assisted development. Also triggers on "set up my repo for AI", "configure coding agents", "agent instructions", or any request to create project-level AI guidance files.
Generate perfect AGENTS.md files for any codebase so AI coding agents (Codex, Cursor, Claude Code, Jules, Aider, Windsurf, Copilot, etc.) work effectively with the project. Use this skill whenever the user mentions AGENTS.md, wants to set up a project for AI agents, asks about coding agent configuration, mentions .cursorrules or CLAUDE.md, or wants to onboard a codebase for AI-assisted development. Also triggers on "set up my repo for AI", "configure coding agents", "agent instructions", or any request to create project-level AI guidance files.
AGENTS.md Generator
Generate cross-compatible, validated AGENTS.md files that work across 20+ AI coding agents.
When to Use
User asks to create or improve an AGENTS.md file
User wants to configure their project for AI coding agents
User mentions Codex, Cursor, Claude Code, Jules, Aider, Windsurf, Copilot agent setup
User asks about .cursorrules, CLAUDE.md, or similar agent config files
User wants to onboard a client project for AI-assisted development
User says "set up my repo for AI agents" or similar
Generation Modes
Mode A: Codebase Scan (preferred when files are available)
Before outputting any AGENTS.md, verify against these rules:
MUST
Total length ≤ 150 lines (root file)
Every command is in backticks and copy-pasteable
All six pillars are addressed (at minimum: commands, testing, structure, style, boundaries)
No generic advice - every line is project-specific
Boundaries section exists with at least 3 items
"When stuck" section exists
MUST NOT
No hardcoded file paths that will go stale (describe capabilities instead)
No duplication of README.md content
No walls of text - use bullet points and code blocks
No version numbers that will go stale
No "always" or "never" in ALL CAPS (agents respond better to conversational tone)
No multi-paragraph prose blocks (agents parse bullets and commands better)
SHOULD
Include good/bad example file references
Include file-scoped test/lint commands (faster feedback)
Include a "When stuck" escape hatch
Reference deeper docs via progressive disclosure
Output Format
Generate the AGENTS.md with this structure:
# AGENTS.md## Project overview
[1-2 sentences: what this project is, what tech stack]
## Setup commands- Install: `[exact command]`- Dev server: `[exact command]`- Build: `[exact command]`- Type check: `[exact command]`## Testing- Run all: `[exact command]`- Run single test: `[exact command with pattern placeholder]`- Run specific package: `[exact command]` (monorepo only)
- CI config: `[path to CI config]`- Fix all tests before committing.
## Project structure- [capability description] → see `[file/dir]`- [capability description] → see `[file/dir]`- [capability description] → see `[file/dir]`## Code style- [Language] [mode]
- [formatting rules as bullets]
- Preferred patterns: see `[exemplar file]`- Avoid patterns in: `[legacy file]`## Good and bad examples- prefer: `[good pattern file]` (why)
- avoid: `[bad pattern file]` (why)
## Git workflow- Branch: `[format]`- Commits: `[format]`- PRs: `[format]`- Before committing: `[pre-commit commands]`## Boundaries- Never [specific prohibition]
- Never [specific prohibition]
- Never [specific prohibition]
- Do not modify: `[protected files/dirs]`- Security: [security-specific rules]
## When stuck- Ask a clarifying question before guessing
- Propose a short plan and wait for approval
- Open a draft PR with notes explaining the blocker
Cross-Agent Compatibility
After generating AGENTS.md, offer these optional extras:
Claude Code symlink: ln -s AGENTS.md CLAUDE.md
Aider config: Add read: AGENTS.md to .aider.conf.yml
Gemini CLI config: Add { "contextFileName": "AGENTS.md" } to .gemini/settings.json
Cursor: AGENTS.md is auto-detected, no extra config needed
Codex: AGENTS.md is auto-detected at project root
Monorepo Support
For monorepos, generate:
Root AGENTS.md - global conventions, monorepo-wide commands
Package AGENTS.md - package-specific overrides in each packages/*/AGENTS.md
Root file should include:
How to navigate packages
Global lint/test/build commands
Package-specific command patterns
Which package manager workspace commands to use
Progressive Disclosure
If a section would exceed 10 lines, extract it:
For TypeScript conventions, see `docs/TYPESCRIPT_CONVENTIONS.md`
For API documentation, see `docs/API_GUIDE.md`
For deployment procedures, see `docs/DEPLOY.md`
Offer to generate these referenced files as well.
Templates
For project-type-specific templates, read: references/templates.md
For common anti-patterns to avoid, read: references/anti-patterns.md
