---
name: wiki-agents-md
description: Generates AGENTS.md files for repository folders to provide coding agents with project-specific context including build commands, testing instructions, code style, project structure, and operational boundaries, only where AGENTS.md is missing.
license: MIT
---

# AGENTS.md Generator

Generate high-quality `AGENTS.md` files for repository folders. Each file provides coding agents with project-specific context — build commands, testing instructions, code style, structure, and operational boundaries.

## What is AGENTS.md

`AGENTS.md` complements `README.md`. README is for humans; AGENTS.md is for coding agents.

- **Predictable location** — Agents look for `AGENTS.md` in the current directory, then walk up the tree
- **Nested files** — Subfolders can have their own `AGENTS.md` that takes precedence over the root one
- **Separate from README** — Keeps READMEs concise; agent-specific details (exact commands, boundaries, conventions) go here
- **NOT the same as `.github/agents/*.agent.md`** — Those are agent persona definitions (who the agent is). `AGENTS.md` is project context (what the agent should know about this code)

## Critical Guard: Only Generate If Missing

> **This is the single most important rule.**

**NEVER overwrite an existing AGENTS.md.**

Before generating for ANY folder:

```bash
# Check if AGENTS.md already exists
ls AGENTS.md 2>/dev/null
```

- If it exists → **skip** and report: `"AGENTS.md already exists at <path> — skipping"`
- If it does not exist → proceed with generation
- This check applies to **every folder independently**

## Pertinent Folder Detection

Identify which folders should have an `AGENTS.md`:

### Always generate for:

- **Repository root** (`/`)
- **Wiki folder** (`wiki/`) — if generated by deep-wiki (has `package.json` with VitePress)

### Generate if they exist:

- `tests/`, `src/`, `lib/`, `app/`, `api/`
- Monorepo packages: `packages/*/`, `apps/*/`, `services/*/`
- Any folder with its own build manifest:
  - `package.json`
  - `pyproject.toml`
  - `Cargo.toml`
  - `*.csproj` / `*.fsproj`
  - `go.mod`
  - `pom.xml` / `build.gradle`
- `.github/` — only if it contains workflows or actions

### Always skip:

- `node_modules/`, `.git/`, `dist/`, `build/`, `out/`, `target/`
- `vendor/`, `.venv/`, `venv/`, `__pycache__/`
- Any directory that is generated output or third-party dependencies

## The Six Core Areas

Every good AGENTS.md covers these areas, tailored to what actually exists in the folder. Do not invent sections for things the project doesn't have.

### a) Build & Run Commands — PUT FIRST

Agents reference these constantly. Use exact commands with flags, not just tool names.

```markdown
## Build & Run

npm install          # Install dependencies
npm run dev          # Start dev server (port 3000)
npm run build        # Production build
npm run lint         # Run ESLint
```

Read these sources to find real commands:
- `package.json` → `scripts` section
- `Makefile` → targets
- `pyproject.toml` → `[tool.poetry.scripts]` or `[project.scripts]`
- `Cargo.toml` → standard cargo commands
- CI configs → `.github/workflows/*.yml`, `Jenkinsfile`, `.gitlab-ci.yml`

### b) Testing Instructions

```markdown
## Testing

pytest tests/ -v                    # Run all tests
pytest tests/test_auth.py -v        # Run single file
pytest -k "test_login" -v           # Run single test by name
pytest --cov=src --cov-report=term  # With coverage
```

Include:
- Test framework and how it's configured
- How to run all tests, a single file, a single test
- Expected behavior before commits (e.g., "all tests must pass")

### c) Project Structure

```markdown
## Project Structure

src/
├── api/          # FastAPI route handlers
├── models/       # Pydantic data models
├── services/     # Business logic
└── utils/        # Shared utilities

tests/            # Mirrors src/ structure
```

Include:
- Key directories and what they contain
- Entry points (e.g., `src/main.py`, `src/index.ts`)
- Where to add new features

### d) Code Style & Conventions

One real code example beats three paragraphs of description.

```markdown
## Code Style

- snake_case for functions and variables
- PascalCase for classes
- Type hints on all function signatures
- Async/await for I/O operations

### Example

```python
async def get_user_by_id(user_id: str) -> User:
    """Fetch a user by their unique identifier."""
    async with get_db_session() as session:
        return await session.get(User, user_id)
```
```

Detect conventions by reading existing code:
- Naming patterns (camelCase, snake_case, PascalCase)
- Import organization (stdlib → third-party → local)
- Module structure patterns

### e) Git Workflow

```markdown
## Git Workflow

- Branch naming: `feature/`, `fix/`, `chore/`
- Commit messages: conventional commits (`feat:`, `fix:`, `docs:`)
- Run `npm test && npm run lint` before committing
- PR titles follow conventional commit format
```

Only include if the repo has evidence of conventions (e.g., commitlint config, PR templates, contributing guides).

### f) Boundaries

Use a three-tier system:

```markdown
## Boundaries

- ✅ **Always do:** Run tests before committing. Write tests for new features. Use type hints.
- ⚠️ **Ask first:** Adding new dependencies. Changing database schemas. Modifying CI/CD configs. Changing public API signatures.
- 🚫 **Never do:** Commit secrets or credentials. Modify `vendor/` or `node_modules/`. Push directly to `main`. Delete migration files.
```

Tailor boundaries to the project:
- Backend projects: schema changes, API contracts
- Frontend projects: breaking component APIs, design system changes
- Infrastructure: production configs, IAM permissions

## Generation Process

When generating an AGENTS.md for a specific folder:

### Step 1: Check existence

```bash
ls <folder>/AGENTS.md 2>/dev/null
```

If it exists, **stop**. Report and move to the next folder.

### Step 2: Scan the folder

Identify:
- Primary language (Python, TypeScript, Rust, Go, Java, C#)
- Framework (FastAPI, Next.js, Actix, Spring Boot)
- Build tool (npm, cargo, poetry, maven, gradle)
- Test runner (pytest, vitest, cargo test, JUnit)

### Step 3: Read config files

Extract real commands and settings from:
- `package.json` scripts
- `Makefile` / `Justfile` targets
- `pyproject.toml` scripts and tool configs
- `Cargo.toml` metadata
- `.github/workflows/*.yml` build/test steps
- `docker-compose.yml` service definitions
- Linter configs (`.eslintrc`, `ruff.toml`, `rustfmt.toml`)

### Step 4: Detect conventions

Read 3-5 source files to identify:
- Naming patterns
- Import organization
- Error handling style
- Comment style
- Module structure

### Step 5: Compose the AGENTS.md

Use only the sections that apply. If the folder has no tests, omit the testing section. If there's no CI config, omit git workflow.

### Step 6: Validate

Before writing the file:
- Every command references a real script, target, or tool
- Every file path references an actual file or directory
- No placeholder text like `<your-project>` or `TODO`
- No invented sections for things that don't exist

## Template Structure

```markdown
# [Folder Name] — Agent Instructions

## Overview
[1-2 sentences: what this folder/project does, its role in the larger system]

## Build & Run
[Exact commands — install, dev, build, clean]

## Testing
[Framework, run commands, single-test commands]

## Project Structure
[Key directories, entry points, where to add new things]

## Code Style
[Naming conventions + one real code example from this project]

## Boundaries
- ✅ **Always do:** [safe operations]
- ⚠️ **Ask first:** [risky operations]
- 🚫 **Never do:** [dangerous operations]

## Documentation
[Only include if wiki/, llms.txt, or docs/ exist in the repo]
- Wiki: `wiki/` — architecture, API, onboarding guides
- LLM Context: `llms.txt` — project summary for coding agents (full version: `wiki/llms-full.txt`)
- Onboarding: `wiki/onboarding/` — guides for contributors, staff engineers, executives, PMs
```

Omit any section that doesn't apply. A 20-line AGENTS.md with real commands beats a 200-line one with generic filler.

## Root vs Nested AGENTS.md

### Root AGENTS.md (`/AGENTS.md`)

Covers the entire project:
- Overall tech stack and architecture
- Global conventions and coding standards
- Dev environment setup
- Repository-wide boundaries
- CI/CD overview

### Nested AGENTS.md (e.g., `tests/AGENTS.md`)

Covers that specific subfolder:
- What this folder does and why it exists
- Folder-specific commands (e.g., `cd tests && pnpm test`)
- Folder-specific conventions
- Should NOT repeat root-level content

### Wiki AGENTS.md (`wiki/AGENTS.md`)

**ALWAYS check** if `wiki/AGENTS.md` exists before generating — same only-if-missing guard as all other folders. If it exists, skip it.

Use this template (adapt to the actual project):

```markdown
# Wiki — Agent Instructions

## Overview
Generated VitePress documentation site. Contains architecture docs, onboarding guides, and API references with source-linked citations and dark-mode Mermaid diagrams.

## Build & Run
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`
- Preview: `npm run preview`

## Wiki Structure
- `index.md` — Landing page with project overview and navigation
- `onboarding/` — Audience-tailored guides (contributor, staff engineer, executive, product manager)
- `{NN}-{section}/` — Numbered documentation sections
- `llms.txt` — LLM-friendly project summary (links + descriptions)
- `llms-full.txt` — LLM-friendly full content (inlined pages)
- `.vitepress/config.mts` — VitePress config with sidebar and Mermaid setup
- `.vitepress/theme/` — Dark theme (custom.css) and zoom handlers (index.ts)

## Content Conventions
- All Mermaid diagrams use dark-mode colors (fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3`)
- Every page has VitePress frontmatter (`title`, `description`)
- Citations link to source repository with line numbers
- Tables include a "Source" column with linked citations
- Mermaid diagrams followed by `<!-- Sources: ... -->` comment blocks

## Boundaries
- ✅ **Always do:** Add new pages following existing section numbering, use dark-mode Mermaid colors
- ⚠️ **Ask first:** Change theme CSS, modify VitePress config, restructure sections
- 🚫 **Never do:** Delete generated pages without understanding dependencies, use light-mode colors, remove citation links

## Documentation
- Wiki: `./` — This folder is the wiki
- LLM Context: `llms.txt` — Quick summary; `llms-full.txt` — Full content
- Onboarding: `onboarding/` — Four audience-tailored guides
```

Fill in the real section names, technologies, and project-specific conventions.

Agents read the nearest AGENTS.md in the directory tree. Nested files take precedence, so they should contain folder-specific details, not global ones.

## CLAUDE.md Companion File

Whenever you generate an `AGENTS.md` in a folder, also generate a `CLAUDE.md` in the same folder — **only if `CLAUDE.md` does not already exist**.

The `CLAUDE.md` content is always exactly:

```markdown
# CLAUDE.md

<!-- Generated for repository development workflows. Do not edit directly. -->

Before beginning work in this repository, read `AGENTS.md` and follow all scoped AGENTS guidance.
```

This ensures Claude Code (and similar tools that look for `CLAUDE.md`) are redirected to the authoritative `AGENTS.md` instructions.

**Same guard applies:** check if `CLAUDE.md` exists before writing. If it exists, skip it.

## Quality Principles

| Principle | Good | Bad |
|-----------|------|-----|
| **Specific** | "React 18 with TypeScript, Vite, Tailwind CSS" | "React project" |
| **Executable** | `pytest tests/ -v --tb=short` | "run the tests" |
| **Grounded** | Show a real code snippet from the project | Describe the style in abstract terms |
| **Real paths** | `src/api/routes/` | `path/to/your/code/` |
| **Honest** | Omit testing section if no tests exist | Invent a testing section |
| **Concise** | 30-80 lines for most folders | 300+ lines of prose |

## Anti-Patterns to Avoid

- ❌ **"You are a helpful coding assistant"** — too vague, describes feelings not actions
- ❌ **Generic boilerplate** — content that could apply to any project provides no value
- ❌ **Invented commands/paths** — every command and path must reference something real
- ❌ **Duplicating README.md** — AGENTS.md complements README, doesn't copy it
- ❌ **Including secrets** — never put credentials, API keys, or tokens in AGENTS.md
- ❌ **Overwriting existing files** — if AGENTS.md exists, do not touch it
- ❌ **Padding empty sections** — if there are no tests, don't write a testing section
- ❌ **Describing what agents should "think" or "feel"** — describe what they should DO