---
name: github-readme
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: 2.0.0
category: devops
domain: github
updated: 2026-03-19
tested: 2026-03-19
tested_with: "Claude Code v2.1"
---
# GitHub README Generator
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
```
/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
```
Default `repo-path` is the current working directory if omitted.
---
## Step 0: Parse and Validate
Expect: `/github:readme {mode} [repo-path]`
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.
Store `repo_path` (absolute) and `mode`.
---
## Step 1: Scan the Repo
Gather context by reading available files. Skip gracefully if a file does not exist.
**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
**Directory structure:**
- Run `ls` at repo root for top-level layout
- Note: `src/`, `bin/`, `lib/`, `scripts/`, `docs/`, `tests/`, `skills/`, `templates/`, `plugins/`, `.github/`
**Existing docs:**
- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`, `ARCHITECTURE.md`, `CHANGELOG.md`, `CODE_OF_CONDUCT.md`, `llms.txt`
**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
---
## Step 2: Detect Project Type
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
Based on detected tech stack, generate 1-3 tech badges + license badge minimum.
Use `style=for-the-badge` for all badges. Generic patterns:
```markdown
```
Badge order: tech stack (left) → stars → license (right).
---
## 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.