agents-md-generator

name

agents-md-generator

description

Generate or lint an AGENTS.md file from repository analysis. Discovers build commands, test commands, environment variables, architecture patterns, and coding conventions, then produces a comprehensive AGENTS.md that tells AI coding agents how to work in the repo. Use when the user says "generate agents.md", "create agents.md", "lint agents.md", "agents file", "agent instructions", or wants to create standardized agent onboarding docs for a repository.

AGENTS.md Generator / Linter — Agent Onboarding for Any Repo

Analyze a repository and generate a comprehensive AGENTS.md that gives AI coding agents everything they need to operate effectively. Also lints existing AGENTS.md files for completeness gaps.

Prerequisites

• Target repository must be locally accessible
• Works with any language/framework (polyglot detection)
• No external API calls required

Mode Selection

Ask the user which mode:

1. Generate: Create a new AGENTS.md from scratch via repo analysis
2. Lint: Audit an existing AGENTS.md for completeness and accuracy
3. Update: Re-analyze the repo and merge new findings into an existing AGENTS.md

Phase 1: Repository Analysis (Generate/Update modes)

Scan the repository for the following categories:

1.1 Build & Run Commands

• Package manifests: package.json scripts, pyproject.toml scripts, Makefile targets, Cargo.toml, go.mod
• Docker/compose files: Dockerfile, docker-compose.yml
• CI configs: .github/workflows/, .gitlab-ci.yml, Jenkinsfile
• Extract: build command, dev command, start command, clean command

1.2 Test Commands

• Test frameworks: jest, vitest, pytest, go test, cargo test
• Test config files: jest.config.*, vitest.config.*, pyproject.toml [tool.pytest]
• Extract: test command, test:watch command, coverage command, test file patterns

1.3 Lint & Format Commands

• Linters: ESLint, Ruff, clippy, golangci-lint
• Formatters: Prettier, Black, rustfmt, gofmt
• Type checkers: TypeScript tsc, mypy, pyright
• Extract: lint command, format command, type-check command, pre-commit config

1.4 Environment Variables

• Scan .env.example, .env.sample, .env.template
• Scan code for process.env., os.environ, os.getenv, env::var
• Extract: required vars, optional vars, which have defaults, which need secrets

1.5 Architecture Patterns

• Directory structure analysis (src/, lib/, api/, components/, etc.)
• Import graph patterns (barrel files, absolute imports, path aliases)
• Key abstractions: repositories, services, controllers, handlers, middleware
• Database access patterns (ORM, raw queries, repository pattern)
• State management approach

1.6 Coding Conventions

• Naming conventions (camelCase, snake_case, PascalCase for what)
• File naming patterns (kebab-case files, PascalCase components)
• Import ordering (stdlib, third-party, local)
• Error handling patterns (Result types, try/catch, error codes)
• Comment style and documentation patterns

1.7 Git Workflow

• Branch naming from git log / branch list
• Commit message style from recent commits
• PR template if present
• Branch protection / CODEOWNERS

Phase 2: AGENTS.md Generation

Structure the output following this template:

# AGENTS.md

Instructions for AI coding agents working in this repository.

## Quick Start

[One-command setup + verification]

## Commands

| Task | Command |
|------|---------|
| Build | `[command]` |
| Dev | `[command]` |
| Test | `[command]` |
| Lint | `[command]` |
| Format | `[command]` |
| Type check | `[command]` |

## Environment

Required environment variables:
- `VAR_NAME` — [purpose] ([how to obtain])

## Architecture

[Brief description of project structure and key patterns]

### Key Rules
- [Convention 1 — e.g., "All DB access through Repository class"]
- [Convention 2 — e.g., "TypeScript imports use .js extensions"]
- [Convention 3 — e.g., "Never import from internal modules directly"]

### Directory Structure

src/ components/ — [purpose] lib/ — [purpose] api/ — [purpose]

## Testing

- Test files go in: `[location]`
- Naming convention: `[pattern]`
- Run single test: `[command]`
- [Any special test setup needed]

## Git Workflow

- Branch from: `[branch]`
- Branch naming: `[pattern]`
- Commit style: `[description]`
- [PR process if applicable]

## Common Pitfalls

- [Things agents commonly get wrong in this codebase]
- [Patterns that look right but are wrong here]

Phase 3: Lint Mode (for existing AGENTS.md)

Check the existing file against this completeness checklist:

Section	Required	Present	Accurate
Quick Start	Yes	?	?
Build/Dev/Test commands	Yes	?	?
Environment variables	Yes	?	?
Architecture overview	Yes	?	?
Key rules/conventions	Yes	?	?
Directory structure	Recommended	?	?
Testing instructions	Yes	?	?
Git workflow	Recommended	?	?
Common pitfalls	Recommended	?	?

For each section:

1. Present: Does it exist in the file?
2. Accurate: Does it match what the repo analysis found? Flag stale commands, missing env vars, outdated patterns.
3. Complete: Are there significant gaps within the section?

Output a lint report with specific fix suggestions.

Phase 4: Review & Write

1. Present the generated/linted AGENTS.md to the user.
2. Ask if any sections need adjustment.
3. Write to the project root as AGENTS.md.
4. If the project also has a CLAUDE.md, note any duplication and suggest consolidation.

Verification

• All commands verified by checking package manifests (not guessed)
• Environment variables cross-referenced with actual code usage
• Architecture section reflects actual directory structure
• No placeholder text left in output
• File is concise (agents work better with focused instructions, not novels)

Relationship to CLAUDE.md

• CLAUDE.md = instructions for Claude specifically (may include personality, learned mistakes, user preferences)
• AGENTS.md = universal agent instructions (any AI coding agent should understand these)
• If a project has both, AGENTS.md covers the universal stuff, CLAUDE.md adds Claude-specific context
• This skill generates AGENTS.md; it does not modify existing CLAUDE.md files

Source Attribution

Based on the insight that a well-organized AGENTS.md + lint rules solve 80% of agent environment problems. Via Nate's Newsletter (2026-03-24): "Accenture booked $2.2 billion in AI consulting last quarter." Alvin Sng's research on lint-as-architecture referenced for complementary approach.