GitHub repository documentation skills and templates for 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 GitHub repository docs — SEO and GEO ready with llms.txt (including external documentation sites), and npm/PyPI registry compatible.

A plugin for Claude Code and OpenCode — also works with Codex CLI, Cursor, Gemini CLI, and more.

Get Started · Features · How It Compares · Commands · Skills · Other AI Tools · Contributing

# 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
/readme

OpenCode reads .claude/skills/ natively — the same install steps work in both tools.

Using Codex CLI, Cursor, Gemini CLI, Aider, or Goose? See Use with Other AI Tools for setup instructions.

You've finished your MVP. The repo is about to go public. You need a README that does more than list install commands — it needs to sell the project to potential users, contributors, and sponsors.

PitchDocs scans your codebase, extracts features with file-level evidence, translates them into benefit-driven language, and generates a marketing-friendly README with a hero section, a "why" narrative, a features-and-benefits table, a working quick start, and proper badges. Run /readme and get a README that passes the 4-question test.

Beyond the README, a professional open-source repo needs CHANGELOG, CONTRIBUTING, ROADMAP, CODE_OF_CONDUCT, SECURITY, issue templates, PR templates, release config, and more. Writing all of these by hand is tedious and error-prone.

Run /docs-audit fix to scan your repo against a 20+ file checklist and auto-generate everything that's missing — or use individual commands (/changelog, /roadmap, /user-guide) for just the docs you need.

Great docs are useless if nobody can find them. PitchDocs handles the discovery layer:

• llms.txt — generate AI-readable content indices following the llmstxt.org spec, so AI coding assistants and search engines surface your docs (SEO and GEO)
• AI context files — generate AGENTS.md, CLAUDE.md, .cursorrules, and copilot-instructions.md so AI coding assistants understand your project's conventions and architecture
• GEO-optimised structure — crisp definitions, atomic sections, comparison tables, and concrete statistics structured for LLM extraction and citation
• npm / PyPI metadata — audit your package.json and pyproject.toml for missing fields that affect your registry page (description, keywords, repository, homepage, types)
• Cross-renderer compatibility — ensure your README renders correctly on GitHub, npm, and PyPI, not just one platform
• Launch artifacts — transform your README and CHANGELOG into Dev.to articles, Hacker News posts, Reddit posts, and awesome list submissions
• Upstream spec drift detection — a GitHub Action checks monthly that your CHANGELOG, CODE_OF_CONDUCT, and commit conventions follow the latest spec versions

flowchart LR
    A["🔍 Scan\nCodebase"] --> B["📋 Extract\nFeatures"]
    B --> C["✍️ Write\nDocs"]
    C --> D["✅ Validate\n4-Question Test"]

    style A fill:#1e3a5f,stroke:#4a9eff,color:#fff
    style B fill:#1e3a5f,stroke:#4a9eff,color:#fff
    style C fill:#1e3a5f,stroke:#4a9eff,color:#fff
    style D fill:#1e3a5f,stroke:#4a9eff,color:#fff

Scan reads your manifest, project structure, git history, and GitHub metadata. Extract runs a 5-step workflow across 10 signal categories to surface features with file-level evidence. Write applies the Daytona/Banesullivan marketing framework with progressive disclosure. Validate checks every doc against the 4-question test, verifies links and badges, and ensures cross-renderer compatibility.

Most documentation generators produce technically-accurate but dry output. Nobody reads it, nobody gets excited, nobody stars the repo.

PitchDocs generates documentation with a marketing edge — docs that answer the reader's real questions:

Every doc follows progressive disclosure — non-technical first paragraph, technical details deeper — and every doc cross-links to related docs so readers never hit a dead end.

Beyond human readers, PitchDocs also optimises for AI discoverability. Docs are structured with crisp definitions, atomic sections, comparison tables, and concrete statistics so that ChatGPT, Perplexity, Google AI Overviews, and other generative engines can extract and cite your project accurately. AI context files (AGENTS.md, CLAUDE.md, .cursorrules) ensure coding assistants understand your conventions from day one — and launch artifacts help you reach the third-party platforms (Dev.to, Hacker News, Reddit, awesome lists) that AI systems treat as trust signals.

• Evidence-based feature extraction — scans 10 signal categories in your codebase and surfaces selling points automatically, with every feature traced to actual code
• 4-question framework on every doc — validates that your docs answer "Does this solve my problem?", "Can I use it?", "Who made it?", and "Where do I learn more?"
• GEO-optimised content structure — crisp definitions, atomic sections, comparison tables, and concrete statistics structured for LLM extraction and AI citation (based on the Princeton GEO study)
• AI context file generation — generate AGENTS.md, CLAUDE.md, .cursorrules, and copilot-instructions.md from a single codebase scan so AI coding assistants understand your conventions
• Diataxis documentation framework — classify docs into tutorials, how-to guides, reference, and explanation quadrants for clear information architecture
• Documentation verification — check for broken links, stale content, llms.txt sync, heading hierarchy issues, and badge URL validity — locally or in CI
• Launch artifacts — transform your README and CHANGELOG into Dev.to articles, Hacker News "Show HN" posts, Reddit posts, Twitter/X threads, and awesome list submission PRs
• 20+ file documentation audit — never ship a repo with missing docs, broken metadata, AI context drift, or invisible image links
• 10 slash commands — generate any doc type from your terminal in under a minute, from README to launch artifacts
• Ready-to-use templates — CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, issue templates, PR templates, and release config — one plugin replaces writing 10+ files by hand
• llms.txt generation — create AI-readable content indices following the llmstxt.org spec so coding assistants and search engines surface your docs
• API reference guidance — configuration templates for TypeDoc, Sphinx, godoc, and rustdoc with comment conventions for each language
• npm and PyPI compatibility — audit registry metadata and ensure your README renders correctly on GitHub, npm, and PyPI
• Progressive disclosure — docs open with non-technical language and reveal technical depth as readers scroll, with automatic cross-linking between sections
• Upstream spec drift detection — a GitHub Action checks monthly that your CHANGELOG, CODE_OF_CONDUCT, and commit conventions follow the latest spec versions
• Cross-tool portability — works with 7 AI coding tools (Claude Code, OpenCode, Codex CLI, Cursor, Gemini CLI, Aider, Goose) with documented setup for each

The docs-writer agent powers these commands — it scans your codebase, extracts features with evidence, and writes docs that pass the 4-question test.

# Generate a README for the current project
/readme

# Extract features from code and output a benefits table
/features table

# Extract features as bold+em-dash bullets for a README
/features bullets

# Audit features: what's documented vs what's in the code
/features audit

# Generate the full changelog from all tags
/changelog full

# Audit what docs are missing and auto-generate them
/docs-audit fix

# Generate llms.txt for AI tool discoverability
/llms-txt

# Generate both llms.txt and llms-full.txt
/llms-txt full

# Generate a getting-started user guide
/user-guide getting-started

# Generate AI context files for all supported tools
/ai-context

# Generate CLAUDE.md only
/ai-context claude

# Verify all docs for broken links and stale content
/docs-verify

# Generate launch artifacts for all platforms
/launch

# Generate a Dev.to article from your README
/launch devto

Skills are loaded on-demand to provide deep reference knowledge:

PitchDocs is built as a Claude Code plugin, but the documentation knowledge it contains — skills, agent workflows, quality standards — is stored as plain Markdown files with YAML frontmatter. That makes it portable to other AI coding tools with minimal effort.

The source of truth lives in .claude/. Here's what's inside and what each piece does:

OpenCode reads .claude/skills/ natively — PitchDocs works out of the box with no extra setup.

Install the same way as Claude Code (clone or add as a plugin), then invoke skills by name in your OpenCode session. The 12 SKILL.md files, the docs-writer agent, and the doc-standards rule are all picked up automatically.

OpenCode also supports MCP servers, so if you have the GitHub MCP server configured, the docs-writer agent can access repository metadata, issues, and releases just as it does in Claude Code.

Codex CLI (OpenAI) uses the same SKILL.md format as Claude Code but looks for skills at a different path: .agents/skills/ instead of .claude/skills/.

Step 1 — Copy skills into your project:

# From your project root (not the PitchDocs repo)
PITCHDOCS="/path/to/pitchdocs"

# Copy all 12 skills
cp -r "$PITCHDOCS/.claude/skills/"* .agents/skills/

# Copy the quality standards as AGENTS.md (Codex reads this automatically)
cp "$PITCHDOCS/AGENTS.md" ./AGENTS.md

Step 2 — Use the skills:

Codex CLI loads SKILL.md files automatically when they're in .agents/skills/. Ask it to generate documentation and it will have access to the PitchDocs frameworks:

> Generate a marketing-friendly README for this project using the public-readme skill
> Extract features and benefits from this codebase using the feature-benefits skill

Step 3 (optional) — Add slash commands:

Copy PitchDocs command files into your Codex prompts directory to get /prompts:readme, /prompts:changelog, etc.:

cp "$PITCHDOCS/commands/"*.md ~/.codex/prompts/pitchdocs/

Cursor uses .cursor/rules/*.mdc files for contextual rules and .cursor/agents/*.md for subagents. It doesn't read SKILL.md files, but you can adapt PitchDocs content to Cursor's format.

Step 1 — Add the documentation standards as a Cursor rule:

Create .cursor/rules/doc-standards.mdc in your project:

---
description: PitchDocs documentation quality standards — 4-question framework, benefit-driven language, progressive disclosure, marketing-friendly structure
---

(Paste the contents of .claude/rules/doc-standards.md here, without its YAML frontmatter)

Because this rule has a description but no globs or alwaysApply, Cursor treats it as an agent-selected rule — it gets included automatically when the AI determines it's relevant to your request.

Step 2 — Add the docs-writer agent:

Create .cursor/agents/docs-writer.md in your project:

---
name: docs-writer
description: Generates high-quality public-facing repository documentation with marketing appeal
---

(Paste the contents of .claude/agents/docs-writer.md here, without its YAML frontmatter)

Step 3 — Reference skills on demand:

Cursor doesn't have a skills directory, but you can reference PitchDocs skill files directly. Clone the PitchDocs repo somewhere accessible, then ask Cursor:

> Read the file at /path/to/pitchdocs/.claude/skills/public-readme/SKILL.md and use it to generate a README for this project

Or paste specific skill content into additional .cursor/rules/*.mdc files for the skills you use most often.

Gemini CLI uses GEMINI.md for project context and .gemini/commands/*.toml for custom commands. It doesn't read SKILL.md files directly, but the knowledge transfers easily.

Option A — Quick setup (context file):

Copy the documentation standards into your project's Gemini context:

# Create .gemini/ directory
mkdir -p .gemini

# Use the doc-standards rule as your base context
cp /path/to/pitchdocs/.claude/rules/doc-standards.md .gemini/GEMINI.md

Then ask Gemini to read specific skill files when needed:

> Read /path/to/pitchdocs/.claude/skills/public-readme/SKILL.md and use it to generate a README

Option B — Custom commands (TOML):

For frequently used workflows, create TOML command files. For example, .gemini/commands/readme.toml:

description = "Generate a marketing-friendly README using PitchDocs standards"
prompt = """
Read the PitchDocs public-readme skill at /path/to/pitchdocs/.claude/skills/public-readme/SKILL.md
and the feature-benefits skill at /path/to/pitchdocs/.claude/skills/feature-benefits/SKILL.md.

Then analyse this codebase and generate a README.md following the skill instructions.
Use the 4-question framework, progressive disclosure, and benefit-driven language.
"""

This gives you a /readme command in Gemini CLI.

Aider doesn't have a plugin or skill system, but it can load reference files into its context via the read config option.

Add to .aider.conf.yml in your project:

read:
  - /path/to/pitchdocs/.claude/rules/doc-standards.md

This loads the documentation quality standards into every Aider session. For specific tasks, load skill files directly in chat:

/read /path/to/pitchdocs/.claude/skills/public-readme/SKILL.md
Generate a README for this project following the skill instructions.

Goose (by Block) uses .goosehints for project context and MCP servers for tool access.

Add PitchDocs context to .goosehints:

# Append the doc-standards rule to your project hints
cat /path/to/pitchdocs/.claude/rules/doc-standards.md >> .goosehints

For specific documentation tasks, reference skill files in your Goose session. If you have the GitHub MCP server configured, Goose can access repository metadata just as Claude Code does.

This plugin references several third-party specifications. Pinned versions are tracked in upstream-versions.json and checked monthly via GitHub Actions:

• Getting Started Guide — Installation, first README generation, and full command walkthrough
• Documentation Hub — All guides, command reference, and skills reference

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:

• Good First Issues — Great starting points
• Feature Requests — Suggest improvements
• Open Issues — See what needs doing

MIT — Made by Little Bear Apps 🐶