| 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-19T00:00:00.000Z","tested":"2026-03-19T00:00:00.000Z","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
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]
- Extract mode —
generate, audit, or update. Any other value or missing → error with usage hint. STOP.
- Extract repo-path — second argument, or current working directory if omitted.
- 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/ReactCargo.toml — Rustpyproject.toml, setup.py, requirements.txt — Pythongo.mod — Gotsconfig.json — TypeScript confirmationDockerfile, docker-compose.yml — containerizationMakefile, 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
- Re-scan repo (Step 1) to detect current state
- Run silent audit — store results, do not display
- 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)
- Show preview — numbered list of proposed changes
- User approval —
y (all), N (cancel), or comma-separated numbers
- 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:
Badge order: tech stack (left) → stars → license (right).
PII / Infrastructure Scrub
Run in ALL modes. Scan generated or existing README text for:
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.
