Readme generator

README Generator

Overview

This skill produces a complete, polished README.md that serves as a project's front door. It inspects the repository to ground the content in reality (real install commands, real scripts, real entry points) rather than inventing details, then assembles the appropriate sections in a conventional, scannable order.

Keywords: readme, README.md, project documentation, badges, shields.io, quick start, installation, usage, getting started, contributing, license, table of contents, project description, onboarding docs.

A great README answers five questions fast:

1. What is this? (one sentence, above the fold)
2. Why should I care? (key features / value)
3. How do I install and run it? (quick start)
4. How do I use it? (usage + examples)
5. How do I contribute / get help / what license?

Workflow

Follow these steps in order. Do not skip the investigation step — accuracy beats fluff.

1. Detect project type and facts. Run scripts/detect_project.py <repo> (or inspect manually) to identify language, package manager, entry points, scripts, license, and existing badges. This drives which sections apply. See references/section-catalog.md for the type→section mapping.

2. Confirm the essentials. Gather (ask the user only for what you cannot infer): project name, one-line tagline, target audience, install command, minimal run/usage example, license, and repo URL (for badge slugs).

3. Choose sections. Start from the canonical order below and drop sections that do not apply. Never include an empty or placeholder section.

4. Draft the header block. Title (H1) → tagline (one line, no period needed) → badge row → optional hero image/demo → table of contents (only if the README is long, roughly 6+ H2 sections).

5. Write Quick Start. The single most important section. A reader should be able to copy-paste their way to a running result in under a minute. Use a fenced code block with a language hint and real commands.

6. Fill body sections (Features, Installation, Usage, Configuration, API, Examples, Roadmap) using concrete, copy-pasteable content. Prefer tables for options/flags/env vars.

7. Add the closing block (Contributing, License, Acknowledgments). Link to CONTRIBUTING.md and CODE_OF_CONDUCT.md if they exist; otherwise inline a short contributing blurb.

8. Validate. Run scripts/lint_readme.py README.md to check for broken relative links, missing alt text, placeholder leftovers (TODO, FIXME, <your-...>), heading hierarchy, and a present License section.

9. Self-review against references/quality-checklist.md.

Canonical Section Order

# Project Name
> One-line tagline

[badges]
[hero image / demo gif]

## Table of Contents        (long READMEs only)
## Features                 (3-6 bullets, benefit-first)
## Quick Start              (copy-paste to a result)
## Installation             (all supported methods)
## Usage                    (common tasks + code)
## Configuration            (options table / env vars)
## API / Commands           (reference, if applicable)
## Examples                 (real scenarios)
## Roadmap                  (optional)
## Contributing             (link or short blurb)
## License
## Acknowledgments          (optional)

Badge Quickref

Use shields.io. Place 4-7 badges max — relevant, not decorative. Common patterns (replace OWNER/REPO):

![Build](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/ci.yml)
![npm](https://img.shields.io/npm/v/PACKAGE)
![PyPI](https://img.shields.io/pypi/v/PACKAGE)
![License](https://img.shields.io/github/license/OWNER/REPO)
![Coverage](https://img.shields.io/codecov/c/github/OWNER/REPO)
![Stars](https://img.shields.io/github/stars/OWNER/REPO?style=social)

See references/badges.md for a full catalog (CI, coverage, version, downloads, language, code style, social, custom static badges) with the exact markdown and link-wrapping pattern.

Decision Heuristics

• Library/package → emphasize Installation, API, and import/usage snippets.
• CLI tool → emphasize Quick Start, Commands/flags table, examples.
• Web app / service → emphasize screenshots/demo, env config, deploy steps.
• Mono-repo → top-level overview + links to per-package READMEs.
• Tiny project → collapse to Title, tagline, Quick Start, Usage, License.
• Unsure of a fact → ask, or mark with a clearly-flagged TODO the user must fill — never silently fabricate version numbers, URLs, or commands.

Best Practices

• Lead with value: the first screen must convey what and why.
• Make every code block copy-pasteable and language-tagged.
• Prefer tables for any list of options, flags, or environment variables.
• Use relative links for in-repo files (./CONTRIBUTING.md) and absolute for external resources.
• Always include alt text on images for accessibility.
• Keep the tagline under ~12 words; keep Features to 3-6 benefit-driven bullets.
• Show, don't tell: a real example beats a paragraph of description.
• Add a Table of Contents only when the document is long enough to need it.

Common Pitfalls

• Fabricated install commands or version numbers — always ground in the repo.
• A wall of prose before the reader sees what the project is.
• Badges that don't resolve (wrong slug) or purely decorative badge spam.
• Multiple H1s (#) — there must be exactly one, the title.
• Placeholder leftovers shipped to users (<your-name>, TODO, lorem ipsum).
• Usage examples that don't actually run.
• Missing License section (legally important, frequently forgotten).

Bundled Files

• references/section-catalog.md — every section, what goes in it, when to include it, and the project-type matrix.
• references/badges.md — full shields.io badge catalog with copy-paste markdown.
• references/quality-checklist.md — final self-review checklist.
• templates/README.template.md — fill-in template with guidance comments.
• examples/cli-tool-readme.md — a complete worked example for a CLI project.
• scripts/detect_project.py — inspects a repo and reports facts for grounding.
• scripts/lint_readme.py — validates a finished README.