github-readme

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:
4. [STRUCTURE] — missing/outdated sections, badge changes
5. [CONTENT] — stale version numbers, outdated tech references
6. [VOICE] — hedge language, marketing fluff, passive voice
7. [SECURITY] — PII/infra violations (applied automatically)
8. Show preview — numbered list of proposed changes
9. User approval — y (all), N (cancel), or comma-separated numbers
10. 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 | -- | |