AGENTS.md Generator

Generate a tailored AGENTS.md file for the current project by analyzing its structure, tooling, and conventions.

This skill writes files. It produces a draft for review, then writes AGENTS.md to the repo root upon confirmation.

What is AGENTS.md?

AGENTS.md is a standard open format for guiding AI coding agents. Think of it as a README for agents: a dedicated, predictable place to provide context and instructions. It is supported by OpenAI Codex, Cursor, Amp, Jules, Factory, Claude Code, and others.

Workflow

Phase 1: Discover Project Structure

Run these commands to understand the project:

# Root-level files
ls -la

# Package manager and language detection
cat package.json 2>/dev/null | head -60
cat pyproject.toml 2>/dev/null
cat Cargo.toml 2>/dev/null
cat go.mod 2>/dev/null
cat pom.xml 2>/dev/null | head -40
cat composer.json 2>/dev/null | head -40

# Check for existing agent/dev instructions
cat README.md 2>/dev/null | head -80
cat CONTRIBUTING.md 2>/dev/null | head -80
cat AGENTS.md 2>/dev/null

# Check for test config
ls jest.config* vitest.config* pytest.ini setup.cfg .mocharc* karma.conf* 2>/dev/null

# Check for linting/formatting config
ls .eslintrc* .eslintignore .prettierrc* biome.json .ruff.toml .flake8 .pylintrc 2>/dev/null

# Check for CI workflows
ls .github/workflows/ 2>/dev/null

# Check for monorepo setup
ls packages/ apps/ services/ libs/ modules/ 2>/dev/null

# Check lockfiles to identify package manager
ls package-lock.json pnpm-lock.yaml yarn.lock bun.lockb 2>/dev/null

Also use Glob to scan for key config files and use Read to examine them.

Key things to extract:

Phase 2: Generate AGENTS.md Content

Based on the analysis, produce a tailored AGENTS.md. Use only sections that are relevant to this project. Omit sections that would be empty or generic.

Template (adapt to the project — replace <placeholders> and remove irrelevant sections):

# AGENTS.md

<One-line description of what this project is and does.>

## Setup

```bash
<install command>         # e.g. pnpm install / pip install -e ".[dev]" / cargo build

Development

<dev server command>      # e.g. pnpm dev / python manage.py runserver
<build command>           # e.g. pnpm build / cargo build --release

Testing

• Run all tests: <test command>
• Run a single test: <focused test command>
• Tests must pass before committing. <Any other testing notes — e.g. test database setup, fixtures, coverage thresholds.>

Code Style

• <language>: <key style rules, e.g. TypeScript strict mode, single quotes, no semicolons>
• Linting: <lint command>
• Formatting: <format command> — run before committing. <Any other conventions found in config files.>

PR Instructions

• <Branch naming convention if found>
• <Commit message format if found — e.g. Conventional Commits>
• Always run <lint> and <test> before opening a PR. <Any other PR/review notes from CONTRIBUTING.md.>

Project Structure

Monorepo Tips

• Use <workspace command> to run commands for a specific package.
• <Any monorepo-specific tooling notes.>

Security

• Never commit .env files or secrets.
• <Any other security notes from SECURITY.md or README.>

**Section guidance:**
- **Setup**: Always include. Use the detected package manager and install command.
- **Development**: Include if there's a dev server or build step.
- **Testing**: Always include. Be specific about commands. Note any test environment setup.
- **Code Style**: Include specific rules from config files, not generic advice.
- **PR Instructions**: Include commit format or branch conventions if detected; otherwise keep brief.
- **Project Structure**: Only include for non-obvious layouts (monorepos, complex directory trees).
- **Monorepo Tips**: Only include if turbo.json, nx.json, lerna.json, or a `packages/` directory is detected.
- **Security**: Only include if there are concrete security notes (e.g., `.env` patterns, SECURITY.md).

### Phase 3: Present and Confirm

Show the generated AGENTS.md content to the user and ask:

> "Does this look good? I'll write it to `AGENTS.md` in the repo root. Any changes before I proceed?"

If `AGENTS.md` already exists, highlight what will change and ask for confirmation before overwriting.

### Phase 4: Write the File

After confirmation, write the file using the Write tool:
- Target: `AGENTS.md` in the repo root (not a subdirectory)
- For monorepos, offer to also create package-level `AGENTS.md` files in detected packages

## Quality Checklist

Before presenting the draft, verify:
- [ ] All commands are copy-paste ready (no `<placeholder>` left in)
- [ ] Commands were verified against actual scripts/configs found in the repo
- [ ] No generic/obvious advice that applies to every project
- [ ] No sections are empty or redundant
- [ ] Instructions match the detected package manager (don't write `npm` for a `pnpm` project)
- [ ] If a section couldn't be determined, it's omitted rather than filled with placeholders