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:

What to Find	Where to Look	Used For
Package manager	lockfile presence	Install command
Framework	package.json deps, imports	Dev server command
Build command	package.json scripts	Build section
Test command	package.json scripts, CI workflows	Testing section
Lint/format commands	package.json scripts, config files	Code style section
Dev server command	package.json scripts	Dev environment
TypeScript/strict mode	tsconfig.json	Code style
Code style rules	.eslintrc, .prettierrc, biome.json	Code style
Commit conventions	CONTRIBUTING.md, .commitlintrc	PR instructions
Monorepo tools	turbo.json, nx.json, lerna.json	Monorepo section
Security notes	README, SECURITY.md	Security section

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

• : <key style rules, e.g. TypeScript strict mode, single quotes, no semicolons>
• Linting: <lint command>
• Formatting: <format command> — run before committing.

PR Instructions

• <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

Path	Purpose
<dir>/

Monorepo Tips

• Use <workspace command> to run commands for a specific package.

Security

• Never commit .env files or secrets.

**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