GitHub README Generator

Generate, audit, or update repository READMEs with project-type detection, voice calibration, discoverability guidance, and scored quality audits.

Install

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:

![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.