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:

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:

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)

1. Show preview — numbered list of proposed changes
2. User approval — y (all), N (cancel), or comma-separated numbers
3. Apply, run final PII scrub, write file, display summary

Section Menu by Project Type

Voice Guidelines

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.