rmb is a CLI for building and rating great READMEs. It scores any README against 50+ research-backed criteria — locally, no AI, no API calls — and bootstraps the rmb skill into your coding agents (Pi and Claude Code) so they can author README files (logo, header, and all 14 sections) that actually score well.

📋 Table of Contents

• Features
• Quick Start
• Why rmb?
• README Scoring
• Agent Setup
• Usage
• Documentation
• Installation
• Contributing
• License
• Acknowledgements

🎯 Why rmb?

Most open source READMEs are mediocre. Research shows that a great README can 5× your star conversion rate — but most projects never invest the time. rmb attacks that from both ends:

1. Measure what you have — There's no objective way to know if your README is good. rmb score gives a deterministic, research-backed score with specific, ranked recommendations — no LLM, no API calls, results in milliseconds.
2. Build a better one — rmb install bootstraps the rmb skill into your coding agent, so it can author READMEs (logo, header, all 14 sections) against the same research the scorer checks.

✨ Features

• 📊 README scoring — Scores any README against 50+ criteria across 5 categories — no LLM required
• 🎯 Actionable feedback — Every failed check comes with a specific, ranked recommendation
• 🤖 Agent bootstrap — One command drops the rmb README skill into Pi and Claude Code
• 🔒 Fully local — Scoring is deterministic and offline; no AI, no API keys, no telemetry
• ⚙️ CI-friendly — --json output and --check --threshold for failing builds on low scores

🚀 Quick Start

# Install the CLI
cargo install banger-readme

# Score a README
rmb score .

# Bootstrap the rmb skill into your agents (Pi + Claude Code)
rmb install

📊 README Scoring

rmb score evaluates READMEs against 50+ deterministic criteria — no AI, no API calls, instant results.

╔══════════════════════════════════════════════════╗
║         README Score: 85/100  [A]               ║
║         "Excellent — well above average"         ║
║         Top 5% of open source READMEs            ║
╚══════════════════════════════════════════════════╝

┌─ Content Completeness ────── 32/35 ─────┐
│ ✅ Logo/Banner    ✅ Badges    ✅ One-liner  │
│ ✅ Demo           ✅ Features  ✅ Quick Start│
│ ✅ TOC            ✅ Why       ✅ Install    │
│ ✅ Usage          ✅ API Ref   ✅ Contrib    │
│ ✅ License        ✅ Acknowledgements       │
└──────────────────────────────────────────┘

Five scoring categories:

Category	Weight	What It Checks
Content Completeness	35 pts	14 essential sections from logo to acknowledgements
Visual Design	25 pts	Logo, badges, emojis, images, collapsible sections, dark/light mode
Project Hygiene	20 pts	LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CI, tests
Cognitive Funneling	15 pts	Section ordering: broad→specific, one-liner before install, license at bottom
Anti-Patterns	−15 pts	Deductions for placeholders, duplicate titles, badge abuse, wall of text

🤖 Agent Setup

rmb install bootstraps the rmb README skill into your coding agents. Once installed, your agent can author READMEs — generating logos and headers, structuring all 14 sections, and following the same research rmb score checks against.

# Bootstrap into both Pi and Claude Code (default)
rmb install

# Only Pi
rmb install --pi-only

# Only Claude Code
rmb install --claude-only

It fetches the bundled banger-readme plugin from GitHub and installs it to:

Target	Location
Pi coding harness	~/.pi/agent/skills/banger-readme/
Claude Code	~/.claude/plugins/cache/ (skills symlinked into ~/.claude/skills/)

Re-running rmb install replaces the existing installation, so it doubles as an update command.

📖 Usage

🔍 Scoring a README

# Score the README in the current directory
rmb score .

# Score a remote README
rmb score https://raw.githubusercontent.com/user/repo/main/README.md --no-hygiene

# Machine-readable JSON output
rmb score . --json

# CI mode: fail if score below threshold
rmb score . --check --threshold 70

🤖 Bootstrapping into agents

# Install the rmb skill into both Pi and Claude Code
rmb install

# Only one target
rmb install --pi-only
rmb install --claude-only

📖 Documentation

Document	Description
Scoring Engine Design	Full architecture and detection rules for rmb score
README Best Practices Research	Index of all research on what makes a great README
Why READMEs Matter	The data, psychology, and philosophy
Anatomy of a README	The 14-section structure in detail
Project Hygiene	License, contributing, CoC, security, tests
Aesthetics & Visual Design	Formatting, visual elements, linkification
Emerging Patterns	Trends for 2024–2026
Anti-Patterns	What repels users and common mistakes
Exemplary READMEs	Curated examples by category
Examples Audit	How 31 production READMEs rank against criteria

🛠️ Installation

From Source

git clone https://github.com/kerryhatcher/banger-readme
cd banger-readme
cargo build --release

The binary will be at target/release/rmb.

Via Cargo

cargo install banger-readme

Running Tests

cargo test
cargo clippy -- -D warnings
cargo fmt -- --check

💬 Getting Help

• Questions? Open a GitHub Discussion
• Bug? File an issue
• Security issue? See SECURITY.md

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, project structure, code standards, and the pull request process.

📄 License

MIT — see LICENSE for details.

🙏 Acknowledgements

Built with research from:

• Awesome README — 21.2k stars, curated list of 100+ exemplary READMEs
• Art of README — Foundational essay on README psychology
• Readme Driven Development — Tom Preston-Werner
• Daytona's 4,000-star launch guide
• Elegant READMEs — Yegor Bugayenko