README Generator
Analyze a codebase and produce a complete, professional README.md.
Parse the user's input to determine:
- Target: a local path, a remote GitHub repo (e.g.,
fortra/impacket), or current directory (default) - Style:
security-tool,library,cli,webapp,minimal, or auto-detect (default) - Update mode: if the user says "update" or the project already has a README, preserve custom sections
Common patterns:
$readme-generation→ generate for current directory, auto-detect style$readme-generation ~/projects/mytool→ generate for local path$readme-generation fortra/impacket→ clone and generate for remote repo$readme-generation --style security-tool→ force a specific style$readme-generation --update→ update existing README, keeping custom sections
Steps
1. Acquire the codebase
- If a remote repo is given:
gh repo clone owner/repo /tmp/readme-targetand work from there - If a local path is given: use that directory
- Otherwise: use current working directory
2. Deep scan the project
Read and analyze these files (skip any that don't exist):
Project metadata:
pyproject.toml,setup.py,setup.cfg— Python project info, dependencies, entry pointsCargo.toml— Rust project infogo.mod— Go module infopackage.json— Node.js project infoMakefile,Justfile— Build commandsDockerfile,docker-compose.yml— Container setup.github/workflows/— CI/CD configuration
Source code (sample, don't read everything):
- Entry points:
main.py,cli.py,main.go,main.rs,src/main.*,cmd/ - Top-level source files for imports and structure
- CLI argument definitions (argparse, typer, cobra, clap)
- Config file examples
Existing docs:
- Current
README.md(if updating) CONTRIBUTING.md,CHANGELOG.md,LICENSEdocs/directory contents
Git context:
git log --oneline -30— recent activity and feature descriptionsgit tag --sort=-v:refname | head -5— version historygit remote -v— origin URL
3. Determine project type and style
Auto-detect from user input or infer:
| Signal | Type |
|---|---|
| nmap/scanning/enum imports, --target flags | security-tool |
| Library with no CLI, published to PyPI/crates | library |
| CLI with subcommands, --help output | cli |
| Web framework (Flask, FastAPI, Express, Next.js) | webapp |
| Few files, single purpose | minimal |
4. Generate README using the appropriate template
Security Tool Template
# [Name]
[One-line description of what it does and why you'd use it]
## Features
- [Key capability 1]
- [Key capability 2]
- [Key capability 3]
## Installation
[Package manager install or build from source — include both if applicable]
## Quick Start
```bash
[Single command showing the most common usage]
Usage
[Full --help output or manual command reference]
Examples
# [Description of scenario 1]
[command]
# [Description of scenario 2]
[command]
# [Description of scenario 3]
[command]
Output Formats
[If the tool supports multiple output formats, show examples of each]
Requirements
- [Runtime dependencies]
- [System requirements]
- [Required access/permissions]
Building from Source
[Build steps]
License
[License type and link]
#### Library Template
```markdown
# [Name]
[One-line description]
## Installation
```bash
[pip install / cargo add / go get command]
Quick Start
[Minimal working example — 5-10 lines]
API Reference
[Module/Class Name]
function_name(params) -> return_type
[Description and example]
Configuration
[Config options if applicable]
Contributing
[How to contribute, run tests, submit PRs]
License
[License]
#### CLI Template
```markdown
# [Name]
[One-line description]
## Installation
```bash
[Install command]
Usage
[Command syntax overview]
Commands
command-name
[Description, flags, example]
Configuration
[Config file location and format if applicable]
Examples
[2-3 real-world usage scenarios]
License
[License]
#### Webapp Template
```markdown
# [Name]
[One-line description]
## Tech Stack
- [Frontend framework]
- [Backend framework]
- [Database]
- [Deployment]
## Getting Started
### Prerequisites
[Required software and versions]
### Setup
```bash
[Clone, install deps, configure, run — step by step]
Environment Variables
| Variable | Description | Default |
|---|---|---|
VAR_NAME |
What it does | default |
Development
[Dev server, test, lint commands]
Deployment
[How to deploy]
License
[License]
#### Minimal Template
```markdown
# [Name]
[One-line description]
## Usage
```bash
[Primary usage command]
Install
[Install steps]
License
[License]
### 5. Writing guidelines
- **First line matters most** — the description after `# Name` should explain what the tool does AND why someone would use it, in one sentence
- **Show, don't tell** — real command examples over descriptions of what's possible
- **Copy-pasteable** — every code block should work if pasted into a terminal
- **No filler** — skip badges, excessive formatting, or sections with no content
- **Accurate dependencies** — only list what's actually required, pulled from the project files
- **Version-aware** — if the project has tags, reference the latest version in install commands
### 6. Update mode
When updating an existing README (user said "update" or `--update`):
1. Read the existing README fully
2. Identify **custom sections** — any section not in the standard template (acknowledgments, special notes, contributor lists, etc.)
3. Regenerate the standard sections with current project data
4. **Preserve custom sections in their original position** — do not delete or rewrite them
5. If a standard section has user-added content beyond what the template provides (e.g., extra examples), keep the user additions and only update the generated parts
6. Show a diff summary of what changed before writing
### 7. Output
- Write the README to the project directory
- If working on a remote repo in `/tmp/`, also copy the output to the current directory as `README-[project-name].md`
- Report the file path and a brief summary of what was generated