thatrebeccarae/claude-marketing / skills/github-readme
github-readme
VerifiedGenerate, 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.
| File | Kind | Size |
|---|---|---|
| EXAMPLES.md | markdown | 5.4 KB |
| LICENSE | other | 1.0 KB |
| REFERENCE.md | markdown | 18.0 KB |
| SKILL.md | skill md | 11.5 KB |
REFERENCE.md
View on GitHub# GitHub README — Reference
Technical data, templates, and patterns for the github-readme skill.
---
## Badge URL Patterns
All badges use shields.io. Default style is `style=for-the-badge`. Append `&style=flat` for inline/compact use.
### Repository Badges
```markdown
<!-- GitHub stars -->
[](https://github.com/{owner}/{repo}/stargazers)
<!-- License (auto-detect from repo) -->
[](LICENSE)
<!-- License (hardcoded MIT) -->
[](LICENSE)
<!-- Build status (GitHub Actions) -->
[](https://github.com/{owner}/{repo}/actions)
<!-- Last commit -->
[](https://github.com/{owner}/{repo}/commits)
<!-- npm version -->
[](https://npmjs.com/package/{package})
<!-- PyPI version -->
[](https://pypi.org/project/{package})
<!-- crates.io version -->
[](https://crates.io/crates/{crate})
<!-- Docker pulls -->
[](https://hub.docker.com/r/{owner}/{image})
<!-- Coverage (Codecov) -->
[](https://codecov.io/gh/{owner}/{repo})
<!-- npm downloads -->
[](https://npmjs.com/package/{package})
```
### Tech Stack Badges
Pattern: brand color on LEFT (`labelColor`), gray `#555` on RIGHT.
```markdown
<!-- TypeScript -->
[](#)
<!-- Node.js -->
[](#)
<!-- Python -->
[](https://python.org)
<!-- Rust -->
[](https://rust-lang.org)
<!-- Go -->
[](https://go.dev)
<!-- React -->
[](https://react.dev)
<!-- Vue -->
[](https://vuejs.org)
<!-- Next.js -->
[](https://nextjs.org)
<!-- Docker -->
[](https://docker.com)
<!-- Tauri -->
[](https://v2.tauri.app)
<!-- Claude Code -->
[](https://docs.anthropic.com/en/docs/claude-code)
<!-- Tailwind CSS -->
[](https://tailwindcss.com)
<!-- Prisma -->
[](https://prisma.io)
<!-- PostgreSQL -->
[](https://postgresql.org)
<!-- SQLite -->
[](https://sqlite.org)
<!-- n8n -->
[](https://n8n.io)
<!-- Framer -->
[](https://framer.com)
```
### Social Badges (flagship repos only)
```markdown
[](https://linkedin.com/in/rebeccaraebarton)
[](https://x.com/rebeccarae)
```
### Clone Badge
```markdown
[](https://github.com/{owner}/{repo})
```
---
## Section Templates
### Title Block (Hero)
```markdown
<div align="center">
# Project Name
**One-line description under 120 characters stating what this does.**
[](#) [](#) [](#) [](#)
<br>
```bash
git clone https://github.com/{owner}/{repo}.git
```
<br>
<!-- Screenshot or demo (width="760") -->
<br><br>
[Why I Built This](#why-i-built-this) · [Getting Started](#getting-started) · [Features](#features) · [License](#license)
</div>
---
```
### Features List
```markdown
## Features
**Category One**
- **Feature name** — What it does and why it matters
- **Feature name** — What it does and why it matters
**Category Two**
- **Feature name** — What it does and why it matters
```
### Installation
```markdown
## Getting Started
### Prerequisites
- Node.js >= 22
- npm >= 10
### Install
```bash
# npm
npm install {package}
# yarn
yarn add {package}
# pnpm
pnpm add {package}
```
```bash
# pip
pip install {package}
# uv
uv add {package}
```
```bash
# cargo
cargo install {crate}
```
```bash
# go
go install github.com/{owner}/{repo}@latest
```
```bash
# git clone
git clone https://github.com/{owner}/{repo}.git
cd {repo}
npm install
```
```
### Quick Start
```markdown
## Quick Start
```typescript
import { Client } from "{package}";
const client = new Client({ apiKey: process.env.API_KEY });
const result = await client.doSomething({ input: "value" });
console.log(result);
```
```
### CLI Commands Table
```markdown
## Commands
| Command | Description |
|---------|-------------|
| `tool init [name]` | Initialize a new project |
| `tool build` | Build for production |
| `tool dev` | Start dev server with hot reload |
| `tool test` | Run test suite |
| `tool lint` | Lint and format |
### `tool init`
```bash
tool init [project-name] [--template <name>] [--no-git]
```
**Options:**
| Flag | Default | Description |
|------|---------|-------------|
| `--template` | `basic` | Starter template |
| `--no-git` | `false` | Skip git initialization |
```
### API Reference (Expandable)
```markdown
## API Reference
<details>
<summary><code>GET /v1/resources</code> — List all resources</summary>
**Parameters:**
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results (default: 20) |
| `offset` | integer | No | Pagination offset |
**Response:**
```json
{
"data": [],
"total": 100,
"limit": 20,
"offset": 0
}
```
</details>
<details>
<summary><code>POST /v1/resources</code> — Create a resource</summary>
**Body:**
```json
{
"name": "string (required)",
"type": "string"
}
```
**Response:** `201 Created`
</details>
```
### Environment Variables Table
```markdown
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `API_KEY` | Yes | -- | API key from dashboard |
| `PORT` | No | `3000` | Server port |
| `LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error` |
| `DATABASE_URL` | Yes | -- | PostgreSQL connection string |
Copy `.env.example` to `.env` and fill in values:
```bash
cp .env.example .env
```
```
### Architecture Overview
```markdown
## Architecture
```
repo/
├── src/
│ ├── core/ # Core business logic
│ ├── api/ # API routes and handlers
│ ├── lib/ # Shared utilities
│ └── index.ts # Entry point
├── config/ # Configuration files
├── scripts/ # Build and deploy scripts
└── tests/ # Test suites
```
Brief explanation of data flow or key design decisions (2-3 sentences).
```
### Contributing
```markdown
## Contributing
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/thing`)
3. Commit changes (`git commit -m 'Add thing'`)
4. Push (`git push origin feature/thing`)
5. Open a Pull Request
```
### License
```markdown
## License
MIT -- see [LICENSE](LICENSE) for details.
```
---
## Project Type Detection Signals
| Signal | Detected Type |
|--------|---------------|
| `bin` field in package.json | CLI tool |
| `exports` or `main` in package.json (no `bin`) | Library/SDK |
| `skills/` dir with SKILL.md files | Skill pack / collection |
| `templates/` dir with multiple template files | Collection / marketplace |
| `next.config.*` or `nuxt.config.*` | Web app (SSR) |
| `vite.config.*` or `webpack.config.*` | Web app (SPA) |
| `app/` or `pages/` dir + framework config | Web app |
| `routes/` or `openapi.yaml`/`swagger.json` | API service |
| `packages/` dir or `workspaces` in package.json | Monorepo |
| `Dockerfile` + `docker-compose.yml` (no app src) | Infrastructure / ops |
| `src-tauri/` or `tauri.conf.json` | Desktop app (Tauri) |
| `pyproject.toml` with `[project.scripts]` | Python CLI |
| `pyproject.toml` with `[project]` (no scripts) | Python library |
| `Cargo.toml` with `[[bin]]` | Rust CLI |
| `Cargo.toml` with `[lib]` | Rust library |
| `go.mod` + `main.go` at root | Go CLI |
| `go.mod` + no `main.go` at root | Go library |
| `.github/actions/` or `action.yml` | GitHub Action |
| `serverless.yml` or `sam-template.yaml` | Serverless function |
---
## Audit Scoring Rubric
Total: 100 points. Each category is weighted and scored independently.
| Category | Weight | Score 0 | Score 50 | Score 100 |
|----------|--------|---------|----------|-----------|
| **Description** | 15% | No description or generic placeholder | Description exists but vague or over 120 chars | Clear one-liner, explains what + who, under 120 chars |
| **Installation** | 20% | No install instructions | Install steps exist but missing prerequisites or package name wrong | Working install command, prerequisites with versions, copy-pasteable |
| **Usage/Examples** | 20% | No code examples | Examples exist but incomplete or use placeholder values | Working examples covering primary use case, syntactically valid |
| **Badges** | 10% | No badges | Some badges but broken URLs or inconsistent style | Relevant badges, all resolve, consistent `for-the-badge` style |
| **Structure** | 15% | Missing multiple required sections | Sections present but wrong order or names | All required sections, correct order, template-compliant names |
| **Completeness** | 10% | Placeholder text remaining, TODO markers | Most sections filled but some thin | All sections substantive, no placeholders, no TODO markers |
| **Freshness** | 10% | Stale version numbers, references removed features | Mostly current, minor drift | Version numbers current, all references accurate, badges valid |
**Scoring formula:** `sum(category_score * weight)` rounded to nearest integer.
**Grade thresholds:**
- 90-100: Excellent -- no action needed
- 70-89: Good -- minor improvements recommended
- 50-69: Needs work -- several sections require attention
- Below 50: Poor -- consider running generate mode
---
## Discoverability Reference
### GitHub Search Ranking Factors
Priority order for how GitHub search weights content:
1. **Repository name** — exact and partial matches rank highest
2. **Description** — the `About` field on the repo page
3. **Topics** — tagged topics visible below description
4. **README content** — full-text indexed but lowest weight
### Topic Best Practices
- Use lowercase, hyphenated terms (`cli-tool`, not `CLI Tool`)
- Prefer single-concept topics (`typescript`, `readme-generator`)
- Max 20 topics per repo (GitHub hard limit)
- Include: language, framework, domain, use-case
- Avoid: generic terms (`awesome`, `tool`), version numbers, duplicating the repo name
### Social Preview Image
- Dimensions: **1280 x 640 px** (2:1 ratio)
- Format: PNG or JPG, under 1MB
- Set via repo Settings > Social Preview
- Should include: project name, one-line description, visual identity
- Avoid: small text, busy backgrounds, screenshots at low resolution
### llms.txt Specification
A `llms.txt` file tells LLMs what a project does and how to use it.
- **Location:** repo root (`/llms.txt`)
- **Format:** plain text, structured sections
- **Sections:** Title, Description, Quick Start, API surface, Key concepts
- **Purpose:** LLM-optimized alternative to README -- dense, no marketing, no images
- **Spec:** https://llmstxt.org
- Also generate `llms-full.txt` for comprehensive reference if project is complex
### AEO (Answer Engine Optimization) Patterns
Structure README content so AI assistants and search engines can extract direct answers:
- **Semantic headings:** Use descriptive H2/H3 that match common questions (`## Installation`, `## How It Works`, not `## Section 3`)
- **Direct answers first:** Lead each section with a 1-2 sentence summary before details
- **Cited data points:** Include specific numbers, versions, benchmarks where relevant
- **Definition patterns:** "X is a Y that does Z" in the first paragraph
- **Comparison-friendly:** When relevant, name alternatives and state differentiators
- **Structured data:** Tables and lists over prose for reference material
---
## PII/Infrastructure Scrub Patterns
Regex patterns for detecting common leaks. Run against all generated README text before writing.
### Email Addresses
```regex
[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
```
Allowlist: `noreply@github.com`, `action@github.com`, `example.com` domain.
### IP Addresses (RFC 1918 Private Ranges)
```regex
# 10.x.x.x
10\.\d{1,3}\.\d{1,3}\.\d{1,3}
# 172.16-31.x.x
172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}
# 192.168.x.x
192\.168\.\d{1,3}\.\d{1,3}
# Tailscale (100.x.x.x CGNAT range)
100\.(6[4-9]|[7-9]\d|1[0-2]\d)\.\d{1,3}\.\d{1,3}
```
### API Keys and Tokens
```regex
# AWS access key
AKIA[0-9A-Z]{16}
# AWS secret key (generic 40-char base64)
[A-Za-z0-9/+=]{40}
# GitHub token (classic and fine-grained)
gh[ps]_[A-Za-z0-9_]{36,}
github_pat_[A-Za-z0-9_]{22,}
# Slack token
xox[bpors]-[A-Za-z0-9-]+
# Slack webhook
hooks\.slack\.com/services/T[A-Z0-9]+/B[A-Z0-9]+/[A-Za-z0-9]+
# Generic bearer/API key patterns
(sk|pk|api|key|token|secret|password)[_-]?[A-Za-z0-9]{20,}
# OpenAI
sk-[A-Za-z0-9]{48}
# Anthropic
sk-ant-[A-Za-z0-9-]{40,}
```
### Internal Hostnames
```regex
# Specific known hostnames (case-insensitive) — replace with your own
(?i)\b(internal-host-a|internal-host-b)\b
# Generic internal hostname patterns
\b[a-z]+-?(dev|staging|internal|local)\.[a-z]+\.(local|internal|lan)\b
```
### Private Key Material
```regex
-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----
```
### File Paths Containing Usernames
```regex
# macOS home directories
/Users/[a-zA-Z][a-zA-Z0-9._-]+/
# Linux home directories
/home/[a-zA-Z][a-zA-Z0-9._-]+/
# Windows user directories
C:\\Users\\[a-zA-Z][a-zA-Z0-9._-]+\\
```
### Client Names and Internal References
```regex
# Replace with your client names and internal codenames
(?i)\b(client-name-a|client-name-b|project-codename)\b
```
### Device Identifiers
```regex
\b[A-Z]{5,8}\b # Serial-like patterns (review matches manually)
```
---
## Voice Calibration Matrix
Adapt tone and structure based on detected project type.
| Type | Tone | Lead With | Avoid |
|------|------|-----------|-------|
| **CLI tool** | Direct, efficient | What it does + install command | Backstory, philosophy |
| **Library/SDK** | Technical, precise | Import statement + API surface | Marketing language, superlatives |
| **Collection/marketplace** | Catalog, organized | What's inside + how to browse/install | Personal narrative, long intros |
| **Web app** | Demo-focused, visual | Screenshot + try-it link | Implementation details upfront |
| **API service** | Reference-oriented | Base URL + auth + first request | Narrative prose, lengthy motivation |
| **Personal project** | Conversational, first-person | Why I built this + the problem | Corporate tone, passive voice |
| **GitHub Action** | Integration-focused | Usage YAML snippet | Architecture deep-dives |
| **Monorepo** | Navigational, structured | Package table + what each does | Treating it like a single project |
| **Desktop app** | User-focused | Download link + screenshot | Build-from-source as primary path |
| **Infrastructure** | Ops-oriented | Requirements + deploy command | End-user language |
### Voice Examples by Type
**CLI tool** -- lead sentence:
> `{tool}` finds unused dependencies in your Node.js project and removes them.
**Library** -- lead sentence:
> A TypeScript client for the {service} API with full type safety and automatic retry.
**Collection** -- lead sentence:
> 55 Claude Code skills for content marketing, developer tools, and design workflows.
**Personal project** -- lead sentence:
> I needed a way to track time without leaving the terminal, so I built one.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |