honest-readmelisted

Write READMEs and project docs that describe what the thing is and how to run it, without marketing fluff or badge spam. Use this WHENEVER you create or edit a README, a repo description, a docs landing page, or a package summary. Superlatives ("blazingly fast", "production-ready", "powerful", "seamless"), rows of decorative badges, emoji-prefixed headings, and a "Features" list of vague adjectives are the tell that a model or a template wrote it. Replace them with a plain one-line description, a real install and usage example, and claims that are specific and true. Pair with no-filler-phrases for the prose.
TheArmagan/skills · ★ 1 · AI & Automation · score 64

Install: claude install-skill TheArmagan/skills

# Honest README A README exists to answer three questions fast: what is this, how do I run it, and how do I use it. Most AI-written or template READMEs bury those under a hero of badges, a tagline like "Blazingly fast, production-ready, developer-first toolkit", and a "Features" list where every bullet is an adjective. That styling reads as generated, and worse, it tells the reader nothing. The rule: every line earns its place by informing the reader. If a sentence would be just as true of a hundred other projects, cut it or make it specific. ## Cut these - **Superlatives and hype:** "blazingly fast", "lightning-fast", "powerful", "robust", "seamless", "elegant", "production-ready", "battle-tested", "enterprise-grade", "next-generation". Either show the claim (a benchmark number, a real constraint) or drop it. - **Badge spam:** a wall of shields.io badges for every CI, coverage, license, downloads, and "made with love". Keep at most the few a maintainer actually checks (build status, version, license). Decorative badges go. - **Emoji-prefixed headings:** `## 🚀 Features`, `## ✨ Installation`. Plain headings. (If you want an icon in a hosted doc, see `prefer-icons`.) - **Vague feature lists:** "Fast. Simple. Flexible. Modern." A reader cannot act on these. Replace with what the thing actually does. - **Filler intros:** "In today's fast-paced world of software development...". Start with what the project is. ## Write these instead - **One plain sentence up