agents-md-generator

AGENTS.md Generator & Auditor

Generate, optimize, and audit AGENTS.md documentation for AI coding agents. Supports 30+ agent platforms.

When to Use

• •User asks to "create AGENTS.md", "generate AGENTS.md", or "write AGENTS.md"
• •User wants to "update" or "optimize" an existing AGENTS.md
• •User asks to "review" or "audit" their AGENTS.md
• •User mentions project documentation for AI agents or coding assistants
• •User wants to generate agent config files for specific editors (TRAE, Cursor, etc.)

Workflow Selection

Creating or regenerating AGENTS.md? -> Follow "Generator Workflow" Improving an existing AGENTS.md? -> Follow "Auditor Workflow" Need editor-specific configs? -> Follow "Multi-Editor Export" after generating

Generator Workflow

Step 1: Scan the Project

Run the scan script to detect the tech stack:

python scripts/scan-project.py /path/to/project

This outputs a JSON summary with:

• •language: Primary language(s) detected
• •frameworks: Frameworks and libraries
• •package_manager: npm/pnpm/yarn/pip/go/cargo etc.
• •commands: Build, test, lint, start, dev commands
• •test_framework: Testing tools detected
• •ci_cd: CI/CD platform if detected
• •directory_structure: Key directories and their purposes
• •has_existing_agents_md: Whether AGENTS.md already exists

Step 2: Read Existing Context

Check for existing project documentation:

• •Read existing AGENTS.md, README.md, CONTRIBUTING.md
• •Read configuration files (package.json, tsconfig.json, pyproject.toml, etc.)
• •Check for .env.example, docker-compose.yml, Makefile

Step 3: Generate AGENTS.md

Use the scan results and context to generate AGENTS.md following the standard template. See reference.md for the full template and section definitions.

Required sections (always include):

1. Project Overview - what the project is, its purpose
2. Commands - build, test, lint, format, start, dev
3. Architecture - directory structure with descriptions
4. Code Style - formatting rules, naming conventions
5. Key Constraints - security rules, forbidden actions

Optional sections (include when relevant):

1. Development Workflow - PR process, branching strategy
2. Testing Strategy - test commands, coverage requirements
3. Environment Setup - required tools, env variables
4. API Reference - key endpoints or interfaces
5. Common Pitfalls - known issues, debugging tips

Step 4: Validate the Output

After generating, verify:

• •All commands are accurate (check against package.json scripts, Makefile, etc.)
• •Directory structure matches actual project layout
• •No placeholder text remains (e.g., "TODO", "INSERT HERE")
• •Security constraints are appropriate for the project type

Auditor Workflow

Step 1: Run the Audit Script

python scripts/audit-agents.py /path/to/project/AGENTS.md --project-root /path/to/project

This outputs:

• •score: Quality score 0-100
• •issues: List of problems found (critical/warning/info)
• •suggestions: Specific improvement recommendations
• •missing_sections: Required sections not present

Step 2: Review Audit Results

Evaluate each issue by severity:

Critical - Must fix:

• •Missing project overview or commands section
• •Commands that don't actually work in the project
• •Missing security constraints (e.g., "never modify .env files")
• •Incorrect directory structure descriptions

Warning - Should fix:

• •Vague descriptions that could mislead the AI agent
• •Missing optional but valuable sections
• •Outdated information not matching current project state
• •Commands without descriptions

Info - Nice to have:

• •Formatting inconsistencies
• •Missing examples in sections
• •Sections that could be more concise

Step 3: Apply Fixes

For each issue, make targeted edits to the AGENTS.md file. Prioritize critical issues first.

Step 4: Re-audit

Run the audit script again to confirm the score has improved and critical issues are resolved.

Multi-Editor Export

After generating AGENTS.md, export to editor-specific formats when requested.

Supported Editors and File Paths

Export Process

1. Generate the universal AGENTS.md first
2. For each requested editor, apply format adaptations from reference.md
3. Write each file to the appropriate location
4. Report which files were created

Format Adaptations by Editor

AGENTS.md (universal): Standard markdown, all sections.

CLAUDE.md: Same as AGENTS.md. No format changes needed.

.cursorrules: Flatten markdown - use plain text rules instead of headers. Remove table formatting. Use --- separators between sections.

.trae/rules.md: Same as AGENTS.md format.

.windsurfrules: Concatenate all sections into a single rules block. Use RULE: prefix for each rule.

.clinerules: Plain text, one rule per line. Use # comments for section headers.

Generation Best Practices

Writing Effective Commands

Always specify the exact command, not a description:

# Bad
Run the tests

# Good
pnpm test

For multi-language projects, show all relevant commands:

# Frontend tests
pnpm --filter frontend test

# Backend tests
cd backend && go test ./...

Architecture Section

Keep directory trees shallow (2-3 levels max). Focus on directories the AI agent will need to modify:

src/
  components/    # React components
  services/      # API service layer
  utils/         # Shared utilities

Security Constraints

Always include a security section for projects with:

• •Environment variables (never modify .env, .env.local, etc.)
• •Database migrations (always review before running)
• •Production deployments (never deploy without approval)
• •Sensitive data handling (PII, credentials, tokens)

Tone and Style

Write AGENTS.md in a direct, imperative style:

• •"Run pnpm test before committing" not "You should run pnpm test before committing"
• •"Never modify files in generated/" not "Please don't modify files in generated/"

Troubleshooting