README.md
March 15, 2026 · View on GitHub
Turn any codebase into professional, marketing-ready repository documentation — powered by AI coding assistants.
Give your AI the knowledge to map out any codebase, extract a features-and-benefits summary, then create, enhance, and maintain professional public-facing repository docs — works with GitHub, GitLab, and Bitbucket. 100% Markdown, zero runtime dependencies — use with Claude Code, OpenCode, Codex CLI, Cursor, Gemini CLI, and more. SEO and GEO ready with llms.txt (including external documentation sites), and npm/PyPI registry compatible.
Get Started · Features · How It Compares · Commands · Other AI Tools · Contributing
 Untether Telegram bridge for AI coding agents |
 Outlook Assistant MCP server for Outlook email, calendar, and contacts |
 PitchDocs This repo's own README was generated with PitchDocs |
| READMEs generated by PitchDocs — click to see the full result | ||
⚡ Get Started
Get your first generated README in under 60 seconds.
Prerequisites
- Claude Code or OpenCode installed
Using a different AI tool? PitchDocs skills are plain Markdown files — they work with Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, and Goose too.
Claude Code / OpenCode
# 1. Add the LBA plugin marketplace (once)
/plugin marketplace add littlebearapps/lba-plugins
# 2. Install PitchDocs
/plugin install pitchdocs@lba-plugins
# 3. Generate a README for any project
/pitchdocs:readme
Note: When installed as a plugin, all commands use the pitchdocs: prefix (e.g., /pitchdocs:readme). The short form /readme only works inside the pitchdocs source directory.
Optional — Enable per-project advisory features:
PitchDocs commands work everywhere, but quality standards, smart documentation suggestions, and freshness checking are opt-in per-project:
# Enable doc standards + awareness nudges + freshness agent
/pitchdocs:activate install
# Also add content-filter-guard hook (Claude Code only)
/pitchdocs:activate install strict
Optional — AI context file management:
For AI context files (AGENTS.md, CLAUDE.md, .cursorrules, etc.), install ContextDocs separately. It includes Context Guard hooks, Signal Gate generation, and drift auditing.
OpenCode reads .claude/skills/ natively — the same install steps (1–3) work in both tools.
For other AI tools, see the setup guide.
📚 Documentation
Learn PitchDocs through tutorials, guides, and reference docs. Pick your path:
| I want to… | Start here |
|---|---|
| Learn by doing | Build Your First Docs Suite — 20-minute hands-on tutorial |
| Understand how it works | How PitchDocs Thinks — Design rationale, frameworks, and philosophy |
| See all commands | Command Reference — All 16 commands with arguments and examples |
| Solve a problem | Troubleshooting & FAQ — Common issues and solutions |
| Find a workflow | Workflow Cookbook — Recipes for public-ready repos, releases, and launches |
| Explore everything | Full Documentation Hub — All guides organised by learning type (tutorial, how-to, reference, explanation) |
🚀 What PitchDocs Does
Your repo is ready to go public, but the docs aren't. You need a README that sells, a CHANGELOG that makes sense to users, a SECURITY policy, contributing guidelines, issue templates, PR templates — and it all needs to look professional.
PitchDocs gives your AI coding assistant the skills and knowledge to scan your codebase, find what's worth talking about, and write the whole documentation suite for you. README, CHANGELOG, CONTRIBUTING, ROADMAP, CODE_OF_CONDUCT, SECURITY, issue templates, PR templates, user guides, and llms.txt — all from slash commands like /pitchdocs:readme and /pitchdocs:docs-audit fix.
Every generated doc is GEO and SEO optimised, npm and PyPI registry compatible, and backed by evidence from your actual code — with professional documentation standards (the 4-question test, lobby principle, and Time to Hello World targets) baked in automatically.
For AI context file management (AGENTS.md, CLAUDE.md, .cursorrules, and more), see ContextDocs.
🎯 Features
- 🔍 Evidence-based feature extraction — scans 10 signal categories, infers target personas, and extracts user benefits via auto-scan or a conversational "talk it out" path — every claim backed by a file path
- 📋 Full docs suite from one command — README, CHANGELOG, CONTRIBUTING, ROADMAP, SECURITY, issue templates, and 15+ more files
- ✅ Professional docs without documentation expertise — every generated doc passes the 4-question test, applies the lobby principle for progressive disclosure, and targets measurable Time to Hello World
- 🔎 GEO-optimised for AI citation — structured so ChatGPT, Perplexity, and Google AI Overviews cite your project accurately
- 📊 Quality scoring (0–100) — grades docs on completeness, structure, freshness, link health, and evidence quality — export to CI with
--min-score - 🧪 CI-ready validation checks — 6 automated GitHub Actions checks (spell check, frontmatter validation, llms.txt consistency, banned phrase detection, orphan file detection, token budget enforcement) catch documentation issues before merging
- 🛡️ Content filter protection — automatically handles Claude Code's API filter for CODE_OF_CONDUCT, LICENSE, and SECURITY so you never hit HTTP 400 errors (Claude Code only)
- 🌐 GitHub, GitLab, and Bitbucket — auto-detects hosting platform and adapts badges, URLs, CI config, and Markdown rendering for each
- 🔌 Works with 9 AI tools — Claude Code, OpenCode, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, Goose
⚖️ How PitchDocs Compares
| Capability | PitchDocs | readmeai | Generic AI Prompt |
|---|---|---|---|
| Scans codebase for features | 10 signal categories with file-level evidence | Basic directory scan | Depends on prompt quality |
| Full docs suite (20+ files) | One command: /pitchdocs:docs-audit fix | README only | One file at a time |
| GEO / AI citation optimised | Atomic sections, comparison tables, concrete stats, llms.txt | No | No |
| Quality scoring and verification | 0–100 score, broken links, freshness, heading hierarchy, badges | No | No |
| Cross-tool compatibility | 9 AI coding tools with documented setup | CLI only | Tool-specific |
🤖 Commands
| Command | What It Does | Why It Matters |
|---|---|---|
/pitchdocs:readme | Generate or update a marketing-friendly README.md | First impressions that convert browsers to users |
/pitchdocs:features | Extract features and user benefits from code — output as inventory, table, bullets, or bold-outcome benefits (auto-scan or conversational) | Never miss a feature worth documenting |
/pitchdocs:changelog | Generate CHANGELOG.md from git history with user-benefit language | Users see what changed for them, not your commit log |
/pitchdocs:roadmap | Generate ROADMAP.md from GitHub milestones and issues | Show contributors where the project is heading |
/pitchdocs:docs-audit | Audit docs completeness, quality, GitHub metadata, visual assets, Diataxis coverage, and npm/PyPI registry config | Catch gaps in files, metadata, images, and package registry fields before you ship |
/pitchdocs:llms-txt | Generate llms.txt and llms-full.txt for AI discoverability | AI coding assistants and search engines find and understand your docs |
/pitchdocs:user-guide | Generate task-oriented user guides in docs/guides/ with Diataxis classification | Readers find answers without reading your source code |
/pitchdocs:ai-context | Stub — redirects to ContextDocs for AI context file management | Install ContextDocs separately for AI context generation |
/pitchdocs:docs-verify | Verify links, freshness, llms.txt sync, heading hierarchy, and badge URLs | Catch documentation decay before it reaches users |
/pitchdocs:launch | Generate Dev.to articles, HN posts, Reddit posts, Twitter threads, awesome list submissions | Transform docs into platform-specific launch content |
/pitchdocs:doc-refresh | Refresh all docs after version bumps — CHANGELOG, README features, user guides, llms.txt | Never ship a release with stale documentation |
/pitchdocs:platform | Detect hosting platform (GitHub, GitLab, Bitbucket) and report feature support | Know which PitchDocs features work on your platform before you start |
/pitchdocs:visual-standards | Load visual formatting reference — emoji headings, screenshot specs, captions, image optimisation | Consistent, polished visual elements across your docs |
/pitchdocs:geo | Load GEO optimisation patterns — citation capsules, statistics, comparison tables | AI systems cite your project accurately |
/pitchdocs:activate | Install/uninstall per-project rules, agent, and hook | Control which projects get doc standards, awareness nudges, and freshness checking |
/pitchdocs:context-guard | Stub — redirects to ContextDocs for Context Guard hooks | Install ContextDocs separately for context drift enforcement |
Quick Examples
/pitchdocs:readme # Generate a marketing-friendly README
/pitchdocs:features bullets # Extract features as emoji+bold+em-dash bullets
/pitchdocs:features benefits # Extract user benefits (auto-scan or "talk it out")
/pitchdocs:docs-audit fix # Audit and auto-generate missing docs
/pitchdocs:changelog full # Generate full changelog from all tags
/pitchdocs:docs-verify # Check for broken links and stale content
/pitchdocs:doc-refresh # Refresh all docs for an upcoming release
/pitchdocs:visual-standards # Load screenshot and emoji heading specs
/pitchdocs:geo # Load AI citation optimisation patterns
🔀 Use with Other AI Tools
PitchDocs works natively with Claude Code and OpenCode. It's also portable to Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, Aider, and Goose — all knowledge is stored as plain Markdown files.
See the Other AI Tools guide for per-tool setup instructions and a full compatibility matrix.
🤝 Contributing
Found a way to make generated docs even better? We'd love your help — whether it's improving a template, fixing a language rule, or suggesting a new doc type entirely.
See our Contributing Guide to get started, or jump straight in:
Roadmap: See open milestones and feature requests for what's coming next.
- Good First Issues — Great starting points
- Feature Requests — Suggest improvements
- Open Issues — See what needs doing
📄 Licence
MIT — Made by Little Bear Apps 🐶