AGENTS.md Generator
Generate structured AGENTS.md files by analyzing a project's tools, dependencies, and organization.
Workflow
- Identify project root — Locate
package.json, pyproject.toml, Cargo.toml, or similar manifest
- Analyze dependencies — Extract framework, testing, linting, and build tools from manifest
- Scan structure — Map
src/, lib/, test/, and other key directories
- Detect quality tools — Identify typecheck, lint, test, and build commands
- Generate AGENTS.md — Output using the template format
Analysis Checklist
Detect Project Type
| Manifest File |
Language |
Common Frameworks |
package.json |
JavaScript/TypeScript |
React, Next.js, Express, Vite |
pyproject.toml / setup.py |
Python |
FastAPI, Django, Flask |
Cargo.toml |
Rust |
Actix, Axum, Tokio |
go.mod |
Go |
Gin, Echo, Fiber |
pom.xml / build.gradle |
Java/Kotlin |
Spring, Quarkus |
Identify Quality Tools
Typechecking:
- TypeScript:
tsc --noEmit
- Python:
mypy, pyright, ty check
- Rust:
cargo check
Linting:
- JavaScript/TypeScript:
eslint, biome
- Python:
ruff, flake8, pylint
- Rust:
clippy
Testing:
- JavaScript/TypeScript:
vitest, jest, mocha
- Python:
pytest, unittest
- Rust:
cargo test
Determine Project Classification
- Library: Exports modules for other packages (has
exports or lib config, no bin)
- Application: Runnable entry point (has
main, bin, or serves HTTP)
- Tool: CLI utility (has
bin field or command-line interface)
Output Template
Use the following structure exactly:
# <Project Name> <Library|Application|Tool>
<1-2 sentence description of what the project does and its purpose>
## Quality Instructions
- **Typecheck**: `<command>` — <brief note if needed>
- **Lint**: `<command>` — <brief note if needed>
- **Test**: `<command>` — <brief note if needed>
- **Build**: `<command>` — <brief note if needed> (if applicable)
## Structure
- `src/` — <purpose>
- `lib/` — <purpose>
- `test/` — <purpose>
<additional key directories only>
## Technical Stack
- **Language**: <primary language and version if relevant>
- **Framework**: <main framework if applicable>
- **Key Libraries**: <2-4 most impactful dependencies>
- **Build Tool**: <bundler or build system>
Generation Guidelines
Be Minimal
- List only directories that matter for understanding the codebase
- Include only the most impactful 3-5 dependencies
- Omit obvious tooling (e.g., don't list
typescript if already listing tsc)
Be Specific
- Use actual command invocations, not generic descriptions
- Reference real paths from the analyzed project
- Match the project's actual tooling configuration
Be Concise
- One-line descriptions for directories
- No redundant explanations
- Skip sections that don't apply (e.g., no "Framework" for a pure utility library)
Example Output
# @acme/data-utils Library
Lightweight data transformation utilities for parsing, validating, and formatting structured data.
## Quality Instructions
- **Typecheck**: `tsc --noEmit`
- **Lint**: `eslint --fix src/`
- **Test**: `vitest run`
- **Build**: `pnpm build`
## Structure
- `src/` — Source modules organized by domain (parsers, validators, formatters)
- `src/__tests__/` — Unit tests colocated with source
## Technical Stack
- **Language**: TypeScript 5.x
- **Key Libraries**: zod (validation), date-fns (date formatting)
- **Build Tool**: tsup
1---2name: agents-md-generator-33description: Generate AGENTS.md files for software projects by analyzing project structure, dependencies, and tooling. Use when asked to create an AGENTS.md file, document a project for AI agents, or establish project conventions for agent consumption. Triggers on requests like "create AGENTS.md", "generate agent instructions", "document this project for agents", or "add AI agent documentation".4---5
6# AGENTS.md Generator
7
8Generate structured AGENTS.md files by analyzing a project's tools, dependencies, and organization.
9
10## Workflow
11
121. **Identify project root** — Locate `package.json`, `pyproject.toml`, `Cargo.toml`, or similar manifest
132. **Analyze dependencies** — Extract framework, testing, linting, and build tools from manifest
143. **Scan structure** — Map `src/`, `lib/`, `test/`, and other key directories
154. **Detect quality tools** — Identify typecheck, lint, test, and build commands
165. **Generate AGENTS.md** — Output using the template format
17
18## Analysis Checklist
19
20### Detect Project Type
21
22| Manifest File | Language | Common Frameworks |
23|---------------|----------|-------------------|
24| `package.json` | JavaScript/TypeScript | React, Next.js, Express, Vite |
25| `pyproject.toml` / `setup.py` | Python | FastAPI, Django, Flask |
26| `Cargo.toml` | Rust | Actix, Axum, Tokio |
27| `go.mod` | Go | Gin, Echo, Fiber |
28| `pom.xml` / `build.gradle` | Java/Kotlin | Spring, Quarkus |
29
30### Identify Quality Tools
31
32**Typechecking:**
33- TypeScript: `tsc --noEmit`
34- Python: `mypy`, `pyright`, `ty check`
35- Rust: `cargo check`
36
37**Linting:**
38- JavaScript/TypeScript: `eslint`, `biome`
39- Python: `ruff`, `flake8`, `pylint`
40- Rust: `clippy`
41
42**Testing:**
43- JavaScript/TypeScript: `vitest`, `jest`, `mocha`
44- Python: `pytest`, `unittest`
45- Rust: `cargo test`
46
47### Determine Project Classification
48
49- **Library**: Exports modules for other packages (has `exports` or `lib` config, no `bin`)
50- **Application**: Runnable entry point (has `main`, `bin`, or serves HTTP)
51- **Tool**: CLI utility (has `bin` field or command-line interface)
52
53## Output Template
54
55Use the following structure exactly:
56
57```markdown
58# <Project Name> <Library|Application|Tool>
59
60<1-2 sentence description of what the project does and its purpose>
61
62## Quality Instructions
63
64- **Typecheck**: `<command>` — <brief note if needed>
65- **Lint**: `<command>` — <brief note if needed>
66- **Test**: `<command>` — <brief note if needed>
67- **Build**: `<command>` — <brief note if needed> (if applicable)
68
69## Structure
70
71- `src/` — <purpose>
72- `lib/` — <purpose>
73- `test/` — <purpose>
74<additional key directories only>
75
76## Technical Stack
77
78- **Language**: <primary language and version if relevant>
79- **Framework**: <main framework if applicable>
80- **Key Libraries**: <2-4 most impactful dependencies>
81- **Build Tool**: <bundler or build system>
82```
83
84## Generation Guidelines
85
86### Be Minimal
87- List only directories that matter for understanding the codebase
88- Include only the most impactful 3-5 dependencies
89- Omit obvious tooling (e.g., don't list `typescript` if already listing `tsc`)
90
91### Be Specific
92- Use actual command invocations, not generic descriptions
93- Reference real paths from the analyzed project
94- Match the project's actual tooling configuration
95
96### Be Concise
97- One-line descriptions for directories
98- No redundant explanations
99- Skip sections that don't apply (e.g., no "Framework" for a pure utility library)
100
101## Example Output
102
103```markdown
104# @acme/data-utils Library
105
106Lightweight data transformation utilities for parsing, validating, and formatting structured data.
107
108## Quality Instructions
109
110- **Typecheck**: `tsc --noEmit`
111- **Lint**: `eslint --fix src/`
112- **Test**: `vitest run`
113- **Build**: `pnpm build`
114
115## Structure
116
117- `src/` — Source modules organized by domain (parsers, validators, formatters)
118- `src/__tests__/` — Unit tests colocated with source
119
120## Technical Stack
121
122- **Language**: TypeScript 5.x
123- **Key Libraries**: zod (validation), date-fns (date formatting)
124- **Build Tool**: tsup
125```
diegosouzapw