github-readme

---
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
---

# 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
![License](https://img.shields.io/github/license/{owner}/{repo}?style=for-the-badge)
![GitHub Stars](https://img.shields.io/github/stars/{owner}/{repo}?style=for-the-badge)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
![React](https://img.shields.io/badge/React-61DAFB?style=for-the-badge&logo=react&logoColor=black)
```

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.