tomevault-io README Generator
Generate human-focused README files following current best practices.
Core principle: README is for humans, not agents. Research → Analyze → Write.
Model recommendation: Use Task tool with model: haiku for README generation — faster and cheaper for documentation tasks.
When to Use
- Creating README for new project
- Rewriting outdated README
- User asks "write/create/update README"
Process
digraph readme_flow {
rankdir=TB;
"1. Research best practices via Exa" [shape=box];
"2. Analyze project structure" [shape=box];
"3. Identify project type" [shape=diamond];
"4. Write README with appropriate sections" [shape=box];
"5. Commit and push if requested" [shape=box];
"1. Research best practices via Exa" -> "2. Analyze project structure";
"2. Analyze project structure" -> "3. Identify project type";
"3. Identify project type" -> "4. Write README with appropriate sections";
"4. Write README with appropriate sections" -> "5. Commit and push if requested";
}
Step 1: Research
Always search first for current README best practices:
mcp__exa__web_search_exa: "best practices README.md {year} {project_type}"
Look for:
- Current trends in README structure
- Examples from similar projects
- What sections are essential vs optional
Step 2: Analyze Project
Read these files to understand the project:
CLAUDE.mdor existing docspackage.json/pyproject.toml/Cargo.toml- Main entry points
- Test files (understand features)
Step 3: Identify Project Type
| Type | Key Sections |
|---|---|
| CLI Tool | Usage examples, Options table, Installation |
| Library/SDK | API overview, Quick start, Examples |
| Web App | Features, Quick start, Architecture diagram |
| Full-stack | Architecture, Quick start both parts, Tech stack |
| AI/ML | Model info, Requirements (GPU), Examples |
Step 4: README Structure
Essential (all projects):
# Project Name
**One-line value proposition.**
Brief description (2-3 sentences max).
## What It Does / Features
- Bullet points of capabilities
- Focus on VALUE not implementation
## Quick Start
Minimal steps to get running (< 5 commands)
## Requirements
- Runtime versions
- System requirements
- Disk space if significant
## Usage
Examples for common cases
## Tech Stack (if non-trivial)
Table format preferred
## License
Optional by project type:
| Section | When to Include |
|---|---|
| Architecture diagram | Web apps, full-stack, complex systems |
| Project Structure | Open source, contribution expected |
| API Reference | Libraries, SDKs (or link to docs) |
| Related Skills | If Claude Code skills exist |
| CLI Options table | CLI tools |
| Configuration | Apps with config files |
| Known Limitations | If significant gotchas exist |
Writing Style
DO:
- Start with value, not implementation
- Use active voice
- Keep sentences short
- Include runnable examples
- Write for humans scanning quickly
DON'T:
- Include API reference for internal use
- Write walls of text
- Use jargon without explanation
- Include every possible option
Related Skills Section
If project has Claude Code skills, add:
## Related Skills
| Skill | Trigger | What it does |
|-------|---------|--------------|
| `skill-name` | "trigger phrase" | Brief description |
Quick Reference
| Project has... | Include |
|---|---|
| Web UI | Screenshot or architecture |
| CLI | Options table, examples |
| API | Endpoint summary (not full docs) |
| AI/ML | Model, hardware requirements |
| Claude skills | Related Skills table |
| Complex arch | Mermaid diagram |
Common Mistakes
| Mistake | Fix |
|---|---|
| API docs dump | Link to separate file or remove |
| No quick start | Add "clone → run" in < 5 steps |
| Wall of text | Use bullets, tables, code blocks |
| Missing requirements | Always list runtime + system reqs |
| Generic description | Start with specific value prop |
Example Structure (Full-stack App)
# Project Name
**Value proposition in one line.**
Brief description.
## Features
- Feature 1
- Feature 2
## Quick Start
\`\`\`bash
./start.sh
\`\`\`
## Requirements
- OS/hardware
- Runtime versions
## Tech Stack
| Layer | Stack |
|-------|-------|
## Architecture
\`\`\`mermaid
flowchart...
\`\`\`
## Project Structure
\`\`\`
project/
├── ...
\`\`\`
## Related Skills
| Skill | Trigger | Description |
## Development
How to test, build
## License
Converted and distributed by TomeVault — claim your Tome and manage your conversions.