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:

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}