github-readme · diff
v1.0.0 to v2.0.0
241 added, 109 removed. Audit A to A.
---
name: github-readme
- description: "Generate, audit, or update GitHub READMEs. Three modes: generate (new), audit (check existing), update (patch). Detects repo type (library/CLI/app/API/monorepo), selects appropriate badges, and generates sections following conventions for the detected type."
+ description: "Generate, audit, or update GitHub READMEs with project-type-aware structure, voice calibration, and SEO/AEO discoverability guidance. Three modes: generate (new), audit (check existing), update (patch). Detects repo type and adapts sections, tone, and badges accordingly."
license: MIT
origin: custom
author: Rebecca Rae Barton
author_url: https://github.com/thatrebeccarae
metadata:
- version: 1.0.0
- category: developer-tools
+ version: 2.0.0
+ category: devops
domain: github
- updated: 2026-03-13
- tested: 2026-03-17
+ updated: 2026-03-19
+ tested: 2026-03-19
tested_with: "Claude Code v2.1"
---
# GitHub README Generator
- Generate, audit, or update GitHub READMEs against a standard template. Detects repo type and adapts structure accordingly.
+ Generate, audit, or update repository READMEs with project-type detection, voice calibration, discoverability guidance, and scored quality audits.
## Install
```bash
git clone https://github.com/thatrebeccarae/claude-marketing.git && cp -r claude-marketing/skills/github-readme ~/.claude/skills/
```
+ ## When to Use
+
+ - Starting a new public repo and need a solid README from scratch
+ - Auditing an existing README for quality, discoverability, and security issues
+ - Updating a README after the repo has evolved (new deps, features, structure)
+ - Preparing a repo for public release and want discoverability optimized
+
## Modes
- ### 1. Generate (New README)
+ ```
+ /github:readme generate [repo-path] # Scan repo, detect type, generate README
+ /github:readme audit [repo-path] # Score existing README (read-only, 0-100)
+ /github:readme update [repo-path] # Re-scan, silent audit, patch with approval
+ ```
- Create a README from scratch by analyzing the repo.
+ Default `repo-path` is the current working directory if omitted.
- **Steps:**
- 1. Detect repo type (library, CLI tool, web app, API, monorepo, skill pack)
- 2. Read package.json/pyproject.toml/Cargo.toml for metadata
- 3. Scan directory structure for key patterns
- 4. Select badge set based on repo type and detected CI/tooling
- 5. Generate sections appropriate to repo type
- 6. Write README.md
+ ---
- ### 2. Audit (Check Existing)
+ ## Step 0: Parse and Validate
- Evaluate an existing README for completeness and quality.
+ Expect: `/github:readme {mode} [repo-path]`
- **Checks:**
- - All required sections present for the repo type
- - Badge URLs resolve (not broken)
- - Version numbers are current
- - Install commands work
- - Code examples are syntactically valid
- - Links are not broken
- - No placeholder text remaining
- - PII/infrastructure scrub (no internal IPs, hostnames, credentials)
+ 1. **Extract mode** — `generate`, `audit`, or `update`. Any other value or missing → error with usage hint. STOP.
+ 2. **Extract repo-path** — second argument, or current working directory if omitted.
+ 3. **Validate** — confirm path exists, is a directory, and contains `.git`. If not → error. STOP.
- **Output:** Score (0-100) + findings report with specific fix recommendations.
+ Store `repo_path` (absolute) and `mode`.
- ### 3. Update (Patch Existing)
+ ---
- Modify an existing README while preserving its structure.
+ ## Step 1: Scan the Repo
- **Steps:**
- 1. Read current README
- 2. Identify sections and their content
- 3. Plan changes (add missing sections, update stale content)
- 4. Show diff-style preview
- 5. Apply updates on approval
+ Gather context by reading available files. Skip gracefully if a file does not exist.
- ## Repo Type Detection
+ **Package/config files** (tech stack detection):
+ - `package.json` — Node/TypeScript/React
+ - `Cargo.toml` — Rust
+ - `pyproject.toml`, `setup.py`, `requirements.txt` — Python
+ - `go.mod` — Go
+ - `tsconfig.json` — TypeScript confirmation
+ - `Dockerfile`, `docker-compose.yml` — containerization
+ - `Makefile`, `justfile` — build system
+ - `.github/workflows/` — CI/CD
- | Signal | Type |
- |--------|------|
- | `src/` + `package.json` with `main`/`exports` | Library |
- | `bin` field in package.json or CLI entry point | CLI Tool |
- | `app/` or `pages/` directory, framework config | Web App |
- | `routes/` or OpenAPI spec | API |
- | `packages/` or workspace config | Monorepo |
- | `skills/` with SKILL.md files | Skill Pack |
+ **Directory structure:**
+ - Run `ls` at repo root for top-level layout
+ - Note: `src/`, `bin/`, `lib/`, `scripts/`, `docs/`, `tests/`, `skills/`, `templates/`, `plugins/`, `.github/`
- ## Section Order by Type
+ **Existing docs:**
+ - `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`, `ARCHITECTURE.md`, `CHANGELOG.md`, `CODE_OF_CONDUCT.md`, `llms.txt`
- ### Library
- 1. Title + badges
- 2. One-line description
- 3. Features
- 4. Installation
- 5. Quick Start
- 6. API Reference
- 7. Configuration
- 8. Contributing
- 9. License
+ **Git remote:**
+ - Run `git -C {repo_path} remote get-url origin`
+ - Extract `{owner}` and `{repo}` from the URL
+ - Determine public/private: `.public-repo` marker → public; `-dev` suffix or no marker → ask user
- ### CLI Tool
- 1. Title + badges
- 2. One-line description
- 3. Installation (brew, npm, cargo, etc.)
- 4. Quick Start
- 5. Commands reference
- 6. Configuration
- 7. Contributing
- 8. License
+ ---
- ### Web App
- 1. Title + badges
- 2. One-line description
- 3. Screenshots/demo
- 4. Features
- 5. Getting Started (prerequisites, install, run)
- 6. Environment Variables
- 7. Deployment
- 8. Contributing
- 9. License
+ ## Step 2: Detect Project Type
- ### API
- 1. Title + badges
- 2. One-line description
- 3. Base URL + authentication
- 4. Quick Start
- 5. Endpoints reference
- 6. Error handling
- 7. Rate limits
- 8. Contributing
- 9. License
+ Classify the repo into exactly one type based on scan signals:
+ | Type | Signals |
+ |------|---------|
+ | **tool/CLI** | Has `bin` field in package.json, CLI entry points, man pages, command parsers (yargs, clap, cobra) |
+ | **library/SDK** | Has `main`/`exports`/`module` field, published to npm/PyPI/crates.io, no CLI entry |
+ | **collection/marketplace** | Contains multiple independent items: `skills/`, `templates/`, `plugins/`, `recipes/` directories with 3+ subdirectories |
+ | **web-app** | Has React/Vue/Svelte/Next/Nuxt, server framework (Express, FastAPI, Actix), deployment config (Vercel, Dockerfile) |
+ | **personal/experimental** | Small repo (<20 files), no package publishing config, no CI, no semver tags |
+
+ If ambiguous, ask the user to confirm. Store as `project_type`.
+
+ ---
+
+ ## Step 3: Discoverability Audit
+
+ Before generating or auditing README content, check these repo-level discoverability signals. Present findings and suggestions to the user.
+
+ **Repo name:**
+ - Is it keyword-rich and searchable? (e.g., `markdown-lint-action` > `my-linter`)
+ - Flag generic names: `app`, `project`, `tool`, `my-thing`
+
+ **GitHub About/description:**
+ - Read via `gh repo view` if available
+ - Should be 3-8 words, front-loaded with primary keyword
+ - Suggest improvement if missing or generic
+
+ **Topics:**
+ - GitHub allows up to 20 topics
+ - Suggest relevant topics based on detected tech stack, project type, and domain
+ - Include both broad (`typescript`, `cli`) and specific (`markdown-parser`, `github-action`) topics
+
+ **Social preview image:**
+ - Flag if missing — suggest creating one (1280x640px recommended)
+
+ **llms.txt (optional):**
+ - If repo is a library/SDK or tool/CLI, suggest generating an `llms.txt` file
+ - Purpose: helps LLMs understand and recommend the project accurately
+
+ Present discoverability suggestions. User can accept, skip, or defer. These do NOT block README generation.
+
+ ---
+
+ ## Step 4: Generate / Audit / Update
+
+ ### Generate Mode
+
+ **4a. Check for existing README** — if present, confirm overwrite or suggest update mode instead.
+
+ **4b. Select sections** based on project type (see Section Menu below).
+
+ **4c. Voice calibration:**
+ - Default: professional product voice — clear, direct, no hedge language, no marketing fluff
+ - Personal/experimental repos OR explicit user opt-in: first-person voice allowed
+ - Never: passive voice in problem statements, emojis in prose, marketing fluff
+
+ **4d. Generate each section:**
+ - **Title + description** — derive name from package config or directory; one-line bold description under 120 chars
+ - **Badges** — see Badge Selection below
+ - **Getting Started / Install** — prerequisites with versions, install steps, first-run command. Under 20 lines.
+ - **Type-specific sections** — per Section Menu. Only include if enough scanned context exists.
+ - **"Why" section** (personal/experimental only) — ask user for 2-3 sentences. Do not fabricate.
+ - **License** — read LICENSE file type. One line linking to the file.
+
+ **4e. Run PII/infrastructure scrub** (see below). Remove violations before writing.
+
+ **4f. Write** `{repo_path}/README.md` and display summary.
+
+ ### Audit Mode (read-only)
+
+ Read existing README. Do NOT modify any files.
+
+ Run quality-signal checks and score against weighted rubric:
+
+ | Category | Weight | Checks |
+ |----------|--------|--------|
+ | **Clarity** | 25 | Clear one-line description? Title is descriptive? |
+ | **Usability** | 25 | Working install/setup command? Code examples? Getting started under 20 lines? |
+ | **Credibility** | 15 | Badges present? Badge URLs resolve? License section present? |
+ | **Currency** | 15 | Version numbers match package config? Tech stack matches repo? No stale links? |
+ | **Security** | 20 | No PII or infrastructure leaks? No API keys/tokens? No private hostnames/IPs? |
+
+ **Scoring:** Each category scored 0-100, final score = weighted average.
+
+ ```
+ === README Audit: {repo-name} ===
+ Score: {X}/100
+
+ Clarity: {X}/25
+ Usability: {X}/25
+ Credibility: {X}/15
+ Currency: {X}/15
+ Security: {X}/20
+
+ PASS:
+ - {passing checks}
+
+ WARN:
+ - {warnings with specific detail}
+
+ FAIL:
+ - {failures with specific detail and fix suggestion}
+ ```
+
+ ### Update Mode
+
+ 1. **Re-scan** repo (Step 1) to detect current state
+ 2. **Run silent audit** — store results, do not display
+ 3. **Generate update plan** — diff-style, grouped by category:
+ - `[STRUCTURE]` — missing/outdated sections, badge changes
+ - `[CONTENT]` — stale version numbers, outdated tech references
+ - `[VOICE]` — hedge language, marketing fluff, passive voice
+ - `[SECURITY]` — PII/infra violations (applied automatically)
+ 4. **Show preview** — numbered list of proposed changes
+ 5. **User approval** — `y` (all), `N` (cancel), or comma-separated numbers
+ 6. **Apply**, run final PII scrub, write file, display summary
+
+ ---
+
+ ## Section Menu by Project Type
+
+ | Section | tool/CLI | library/SDK | collection | web-app | personal |
+ |---------|:--------:|:-----------:|:----------:|:-------:|:--------:|
+ | Title + description | Required | Required | Required | Required | Required |
+ | Badges | Required | Required | Required | Required | Optional |
+ | Getting Started / Install | Required | Required | Required | Required | Required |
+ | Usage / Commands | Required | -- | -- | -- | -- |
+ | API Reference | -- | Required | -- | -- | -- |
+ | Catalog / Index | -- | -- | Required | -- | -- |
+ | Features | Recommended | Recommended | -- | Required | -- |
+ | Configuration | Recommended | Recommended | -- | Recommended | -- |
+ | Architecture | -- | -- | -- | Recommended | -- |
+ | Why I Built This | -- | -- | -- | -- | Required |
+ | Who This Is For | Recommended | Recommended | Recommended | -- | -- |
+ | Contributing | Recommended | Required | Recommended | Recommended | -- |
+ | License | Required | Required | Required | Required | Required |
+
+ ---
+
+ ## Voice Guidelines
+
+ | Type | Default Tone | Example Opening |
+ |------|-------------|-----------------|
+ | tool/CLI | Direct, practical | "Fast Markdown linting for CI pipelines." |
+ | library/SDK | Technical, precise | "A typed HTTP client for the Stripe API." |
+ | collection | Organized, scannable | "50+ reusable GitHub Actions workflows." |
+ | web-app | Product-focused, clear | "Real-time project dashboard with team analytics." |
+ | personal | First-person, opinionated | "I needed a better way to track reading habits." |
+
+ **Always:** direct, specific, opinionated, short paragraphs (4 sentences max).
+ **Never:** hedge language, marketing fluff, passive voice in problem statements, emojis in prose.
+
+ ---
+
## Badge Selection
- | Badge | When to Include |
- |-------|----------------|
- | Build/CI status | CI config detected (.github/workflows/) |
- | Coverage | Coverage config detected (codecov, coveralls) |
- | npm version | package.json with npm publish |
- | PyPI version | pyproject.toml with PyPI config |
- | License | Always |
- | Node/Python version | When runtime version matters |
- | TypeScript | tsconfig.json present |
- | Docker | Dockerfile present |
+ Based on detected tech stack, generate 1-3 tech badges + license badge minimum.
- ## Key Principles
+ Use `style=for-the-badge` for all badges. Generic patterns:
- 1. **Lead with what it does.** First sentence should explain the tool in one line.
- 2. **Show, don't tell.** Code examples > descriptions.
- 3. **Install command must work.** Test it mentally — does it reference the right package name?
- 4. **No placeholder text.** Every `TODO`, `YOUR_`, `CHANGEME` must be resolved.
- 5. **No stale badges.** Remove badges for services not configured.
+ ```markdown
+ 
+ 
+ 
+ 
+ 
+ 
+ ```
- ## Anti-Patterns
+ Badge order: tech stack (left) → stars → license (right).
- - Walls of text without code examples
- - Broken badge URLs or badges for unconfigured services
- - Generic descriptions ("A tool for doing things")
- - Missing install instructions
- - Stale version numbers in examples
- - Internal URLs, IPs, or credentials in examples
- - Placeholder text left in ("TODO", "Add description here")
+ ---
- For badge URL patterns and section templates, see [REFERENCE.md](REFERENCE.md).
+ ## PII / Infrastructure Scrub
+
+ Run in ALL modes. Scan generated or existing README text for:
+
+ - [ ] Private hostnames
+ - [ ] IP addresses (especially 10.x, 172.16-31.x, 192.168.x, 100.x Tailscale)
+ - [ ] Internal network/VLAN names
+ - [ ] Device identifiers or serial numbers
+ - [ ] Client or employer names that should not be public
+ - [ ] Personal email addresses
+ - [ ] API keys or tokens (`sk-`, `token_`, `ghp_`, `Bearer`, long alphanumeric strings)
+ - [ ] Internal Docker/service config (private port mappings, container names)
+ - [ ] SSH config references (aliases, private key paths)
+
+ **If violations found:** list each, remove or redact, show user what was removed.
+ **Security violations are never optional** — applied automatically in update mode.
+
+ ---
+
+ ## Key Principles
+
+ - **Detect, don't assume.** Scan the repo and adapt structure to what actually exists.
+ - **Professional by default.** First-person voice is opt-in, not the default.
+ - **Discoverability matters.** Repo name, description, topics, and llms.txt are part of the README story.
+ - **Quality over completeness.** Fewer well-written sections beat bloated README with empty placeholders.
+ - **Security is non-negotiable.** PII/infra scrub runs in every mode, every time.
+ - **Audit mode is read-only.** Never modify files during an audit.