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]
- Extract mode —
generate,audit, orupdate. 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
lsat 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-repomarker → public;-devsuffix 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 viewif 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.txtfile - 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:
- 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.
More from thatrebeccarae/claude-marketing
facebook-ads
Meta Ads (Facebook & Instagram) platform expertise. Audit campaigns, audiences, creative strategy, pixel tracking, and CAPI. Use when the user asks about Facebook Ads, Instagram Ads, Meta Ads, social media advertising, Advantage+ campaigns, or Meta pixel/CAPI setup.
13content-creator
Comprehensive content marketing toolkit with brand voice analysis, SEO optimization scripts, content frameworks, social media strategy, and content calendar planning. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or developing content strategy. For deep SEO writing optimization, see the seo-content-writer skill.
13icp-research
Build detailed ideal customer profiles with pain points, objections, buying triggers, and messaging angles. Includes community research to find where ICPs gather online and extract their exact language. Use when researching audiences, creating buyer personas, or developing targeted messaging.
12content-pipeline
End-to-end content creation workflow that orchestrates research, editorial review, and social distribution agents in sequence. Use when the user wants to create, review, and distribute content through a multi-stage pipeline, or says "/content-pipeline".
12content-workflow
End-to-end content creation pipeline from research through editorial review to social distribution. Orchestrates a 3-stage workflow: research, draft/edit, and distribute. Supports blog posts, LinkedIn, Twitter threads, newsletters, and essays.
12brand-voice-guidelines
Develop brand voice, tone matrices, messaging frameworks, and brand book documentation. Use when the user asks about brand voice, tone of voice, brand guidelines, messaging framework, or brand consistency.
12