wiki-agents-md

What this skill does

# 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