Generate comprehensive AGENTS.md, README.md, and CLAUDE.md documentation for any repository. Deep-dives into codebase structure, identifies technologies, creates ASCII architecture diagrams, and respects existing documentation content.
Generates comprehensive repository documentation with ASCII architecture diagrams and agent-friendly guidelines.
/plugin marketplace add diversioteam/agent-skills-marketplace/plugin install repo-docs@diversiotechThis skill is limited to using the following tools:
Generates comprehensive, agent-friendly documentation (AGENTS.md, README.md, CLAUDE.md) for any software repository by analyzing its structure, technologies, and patterns.
Respect existing content. Never blindly replace documentation that humans have written. Always:
Thoroughly explore the repository before writing anything:
# 1. Understand the repo structure
find . -maxdepth 3 -type f -name "*.md" 2>/dev/null | head -20
ls -la
cat README.md 2>/dev/null || echo "No README.md"
cat AGENTS.md 2>/dev/null || echo "No AGENTS.md"
cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md"
# 2. Identify the tech stack
ls package.json pyproject.toml requirements.txt Cargo.toml go.mod build.gradle pom.xml Gemfile 2>/dev/null
cat package.json 2>/dev/null | head -50
cat pyproject.toml 2>/dev/null | head -50
# 3. Find main entry points
find . -maxdepth 2 -name "main.*" -o -name "index.*" -o -name "app.*" 2>/dev/null
ls src/ app/ lib/ 2>/dev/null
# 4. Identify the build/deploy system
ls Dockerfile docker-compose.yml .github/workflows .circleci serverless.yml 2>/dev/null
# 5. Check for existing documentation
find . -maxdepth 2 -name "*.md" -type f 2>/dev/null
# 6. Identify quality gates (pre-commit, linters, formatters)
ls .pre-commit-config.yaml .pre-commit-config.yml 2>/dev/null
rg -n "djlint|ruff|mypy|pyright|ty|eslint|prettier|black|isort" .pre-commit-config.yaml .pre-commit-config.yml pyproject.toml package.json 2>/dev/null | head -50
Based on discovery, identify:
If the repo uses pre-commit and/or strict linters, treat them as the highest ROI documentation target. In AGENTS.md, explicitly document:
ty first when configured, then pyright, then mypyty is mandatory if configureddocs/python-typing-3.14-best-practices.md, TY_MIGRATION_GUIDE.md)# AGENTS.md — The [Project Name] Story
*A guide for AI agents and humans alike. [One-sentence description of what this guide explains.]*
---
## What This Repo Is
**[Project Name]** is [brief description of what it does and why it exists].
[Metaphor or analogy that captures its essence.]
[HIGH-LEVEL ASCII ARCHITECTURE DIAGRAM]
---
## Architecture Diagrams
### [Subsystem 1] Architecture
[DETAILED ASCII DIAGRAM]
### [Subsystem 2] Architecture
[DETAILED ASCII DIAGRAM]
---
## Folder Structure
project/ | +-- dir1/ # Description | +-- file.ext # Description +-- dir2/ # Description
---
## Technologies
| Category | Technology | Purpose |
|----------|------------|---------|
| **Language** | ... | ... |
| **Framework** | ... | ... |
| **Database** | ... | ... |
---
## Do
- [Best practice 1]
- [Best practice 2]
- [Best practice 3]
## Don't
- Don't [anti-pattern 1]
- Don't [anti-pattern 2]
- Don't [anti-pattern 3]
---
## Common Commands
```bash
# Development
command1 # Description
# Testing
command2 # Description
# Deployment
command3 # Description
[What happened]
The cause: [Root cause]
The fix: [Solution]
[Category 1]:
command
[Category 2]:
key info
When in doubt: [Most important advice]
#### ASCII Diagram Rules (Critical)
**DO use these characters:**
- Box corners: `+`
- Horizontal lines: `-`, `=`
- Vertical lines: `|`
- Arrows: `>`, `<`, `v`, `^`, `---->`, `|`
- Bullet points: `*`, `-`
- Section dividers: `===`, `---`
**DO NOT use:**
- Unicode box-drawing characters (U+2500-U+257F): `─`, `│`, `┌`, `┐`, `└`, `┘`, `├`, `┤`, `┬`, `┴`, `┼`
- Emojis in diagrams
- Fancy Unicode arrows: `→`, `←`, `↓`, `↑`
**Correct example:**
+------------------------------------------------------------------+ | PROJECT NAME | +------------------------------------------------------------------+ | | | +------------------+ +------------------+ +------------------+ | | | COMPONENT A | | COMPONENT B | | COMPONENT C | | | | Description | | Description | | Description | | | +------------------+ +------------------+ +------------------+ | | | +------------------------------------------------------------------+
**Flow diagram example:**
+----------------+ +----------------+ +----------------+ | Input |---->| Process |---->| Output | | (source) | | (transform) | | (result) | +----------------+ +----------------+ +----------------+ | | Annotated flow description v +----------------+ | Next Step | +----------------+
#### README.md Strategy
**If README.md exists:**
1. Read it entirely
2. Identify human-written content that must be preserved
3. Add architecture overview at the TOP (after title)
4. Add reference to AGENTS.md for detailed documentation
5. Keep all existing sections intact
6. Only add, don't remove
**If README.md doesn't exist:**
- Create a concise version with:
- Project name and description
- Architecture overview diagram
- Quick start instructions
- Reference to AGENTS.md for details
#### CLAUDE.md Structure (Required)
CLAUDE.md should be minimal and source AGENTS.md:
```markdown
@AGENTS.md
---
## Notes
This `CLAUDE.md` intentionally sources `AGENTS.md` so that requirements,
commands, and agent behavior live in a single source of truth for this repo.
For Claude Code best practices on `CLAUDE.md` / `AGENTS.md` in web-based repos,
see:
- https://docs.claude.com/en/docs/claude-code/claude-code-on-the-web#best-practices
Relevant guidance (summarized):
- Document requirements: clearly specify dependencies and commands for the
project.
- If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using
`@AGENTS.md` to maintain a single source of truth.
Before finalizing:
Look for:
pyproject.toml, setup.py, requirements.txtuv.lock, poetry.lock, Pipfile.lockmanage.py, settings.py, apps with models.pyapp.py, wsgi.pymain.py with FastAPI() instanceCommon commands:
# uv-based
uv run python ...
uv sync
# pip-based
pip install -r requirements.txt
python manage.py runserver
# poetry-based
poetry install
poetry run python ...
Look for:
package.json, yarn.lock, package-lock.jsontsconfig.json for TypeScriptsrc/App.tsx, src/index.tsxserver.js, index.jsvite.config.tsnext.config.js, pages/ or app/Common commands:
npm install / yarn
npm run dev / yarn dev
npm run build / yarn build
npm test / yarn test
Look for:
pom.xml (Maven), build.gradle (Gradle)src/main/java/, src/test/java/Application.java, application.propertiesCommon commands:
# Maven
mvn clean install
mvn spring-boot:run
# Gradle
./gradlew build
./gradlew bootRun
# Ant (legacy)
ant build
ant clean
Look for:
*.tf filesmodules/, environments/terraform.tfvars, backend.tfCommon commands:
terraform init
terraform plan
terraform apply
terraform fmt
Look for:
serverless.yml (Serverless Framework)zappa_settings.json (Zappa)sam.yaml (AWS SAM)functions/ directoryCommon commands:
serverless deploy --stage dev
serverless offline
zappa deploy staging
When documentation is generated, report:
## Documentation Generated
**Repository:** /path/to/repo
**Type:** [Web App / API / Library / Infrastructure / Scripts]
**Tech Stack:** [Primary technologies]
### Files Created/Updated:
| File | Action | Notes |
|------|--------|-------|
| AGENTS.md | Created/Updated | [summary] |
| README.md | Enhanced/Created | [summary] |
| CLAUDE.md | Created/Updated | Sources AGENTS.md |
### Architecture Diagrams Included:
1. [Diagram name 1]
2. [Diagram name 2]
3. [Diagram name 3]
### Preserved Content:
- [Existing section 1 from README.md]
- [Existing section 2 from README.md]
### Recommendations:
- [Any follow-up suggestions]
If the existing AGENTS.md has valuable content that shouldn't be lost:
If you can't identify the technology:
If the repo contains multiple distinct projects:
After analyzing a Django project, the AGENTS.md might include:
## Architecture Diagrams
### Request Flow
+------------------------------------------------------------------+ | DJANGO REQUEST LIFECYCLE | +------------------------------------------------------------------+
+----------------+ +----------------+ +----------------+ | Browser |---->| nginx |---->| gunicorn | | (HTTP request) | | (reverse proxy)| | (WSGI server) | +----------------+ +----------------+ +----------------+ | v +----------------+ +----------------+ | Django |---->| PostgreSQL | | (views/models) | | (database) | +----------------+ +----------------+
After analyzing a React project:
## Architecture Diagrams
### Component Hierarchy
+------------------------------------------------------------------+ | REACT APPLICATION | +------------------------------------------------------------------+
+------------------------+
| App.tsx |
| (Router, Providers) |
+------------------------+
|
+---------------------+---------------------+
| | |
v v v
+----------------+ +----------------+ +----------------+ | AuthLayout | | DashboardLayout| | PublicLayout | | (login/signup) | | (main app) | | (landing) | +----------------+ +----------------+ +----------------+
If README.md exists with:
# My Project
Some important info written by humans.
## Installation
Custom installation instructions.
The enhanced README.md becomes:
# My Project
Some important info written by humans.
> **Architecture Note**: For detailed architecture documentation, agent guidelines, and development patterns, see [AGENTS.md](./AGENTS.md).
## Architecture Overview
[ASCII DIAGRAM]
---
## Installation
Custom installation instructions.
Discover repo:
ls -la && cat README.md 2>/dev/null && cat AGENTS.md 2>/dev/null
Find tech stack:
ls package.json pyproject.toml *.tf serverless.yml 2>/dev/null
Check existing docs:
find . -maxdepth 2 -name "*.md" -type f
When in doubt: Read everything first, enhance carefully, preserve human content, use standard ASCII only for diagrams.
Use /repo-docs:canonicalize to audit and fix existing documentation across a repository, making AGENTS.md the canonical source of truth and normalizing all CLAUDE.md files to minimal stubs.
Find all directories with AGENTS.md and/or CLAUDE.md:
# Find all AGENTS.md and CLAUDE.md files recursively
find . -name "AGENTS.md" -o -name "CLAUDE.md" | sort
# Group by directory
find . -name "AGENTS.md" -o -name "CLAUDE.md" | xargs -I{} dirname {} | sort -u
For each directory with docs, analyze the actual current behavior:
Tooling Analysis:
# Check for uv (modern Python)
ls uv.lock pyproject.toml 2>/dev/null
# Check for .bin/* wrappers
ls .bin/ 2>/dev/null
# Check CI configuration
ls .github/workflows/*.yml 2>/dev/null
cat .github/workflows/*.yml 2>/dev/null | grep -E "run:|command:" | head -20
# Check for Makefile/scripts
ls Makefile *.sh scripts/ 2>/dev/null
# Check pre-commit + linting configuration (often the real “source of truth”)
ls .pre-commit-config.yaml .pre-commit-config.yml 2>/dev/null
rg -n "djlint|ruff|mypy|pyright|ty|eslint|prettier|black|isort" .pre-commit-config.yaml .pre-commit-config.yml pyproject.toml package.json 2>/dev/null | head -50
Identify Stale Patterns (remove these):
pip install -r requirements.txt → should be uv syncpoetry install / poetry run → should be uv sync / uv runpython manage.py → should be .bin/django or uv run python manage.pypytest → should be .bin/pytest or uv run pytestIdentify Current Patterns (use these):
uv sync, uv run ....bin/django, .bin/pytest, .bin/ruff, plus active type gate wrapper
(.bin/ty, .bin/pyright, or .bin/mypy)pre-commit run ... (and any repo wrappers like make precommit)For each directory:
Read both files:
cat AGENTS.md 2>/dev/null
cat CLAUDE.md 2>/dev/null
Identify content categories:
Merge strategy:
Update AGENTS.md to be canonical for its directory scope:
Command updates:
## Common Commands
```bash
# Environment setup
uv sync # Install dependencies
# Running the server
.bin/django runserver # Or: uv run python manage.py runserver
# Testing
.bin/pytest # Or: uv run pytest
.bin/pytest -x -vvs path/to/test.py # Single test with output
# Linting
.bin/ruff check . # Check for issues
.bin/ruff format . # Auto-format
# Pre-commit (if present, this is usually the authoritative lint gate)
pre-commit run --all-files # Or: pre-commit run --files <changed files>
# Type checking
# Prefer ty when configured, then pyright, then mypy
.bin/ty check . # Run ty (if configured)
.bin/pyright . # Or pyright
.bin/mypy . # Or mypy
```
Behavior descriptions must match actual code:
.pre-commit-config.* exists, summarize key hooks and “gotchas” in
AGENTS.md (e.g. djlint template rules, required commit message prefixes) so
agents write compliant code on the first pass instead of discovering failures
at commit time.Replace every CLAUDE.md with this minimal stub:
@AGENTS.md
---
## Notes
This `CLAUDE.md` intentionally sources `AGENTS.md` so that requirements,
commands, and agent behavior live in a single source of truth for this repo.
For Claude Code best practices on `CLAUDE.md` / `AGENTS.md` in web-based repos,
see:
- https://docs.claude.com/en/docs/claude-code/claude-code-on-the-web#best-practices
Relevant guidance (summarized):
- Document requirements: clearly specify dependencies and commands for the
project.
- If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using
`@AGENTS.md` to maintain a single source of truth.
Important: No additional rules, requirements, or divergent specs in CLAUDE.md. All behavioral guidance must live in AGENTS.md.
## Documentation Canonicalized
**Repository:** /path/to/repo
**Directories processed:** N
### Summary by Directory:
| Directory | AGENTS.md | CLAUDE.md | Changes |
|-----------|-----------|-----------|---------|
| `/` | Updated | Normalized | Merged 3 sections, removed stale pip commands |
| `/backend` | Updated | Normalized | Updated to .bin/* wrappers |
| `/infra` | Created | Normalized | Was CLAUDE.md only, now has AGENTS.md |
### Stale Content Removed:
- `pip install -r requirements.txt` → `uv sync`
- `poetry run pytest` → `.bin/pytest`
- References to Django 3.x (now 4.x)
- Old CI workflow names
### Content Merged from CLAUDE.md → AGENTS.md:
- `/backend/CLAUDE.md`: Database migration safety rules
- `/infra/CLAUDE.md`: Terraform state locking guidance
### All CLAUDE.md files now source @AGENTS.md
uv, .bin/* wrappers, actual CI commandsThis skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.