good-readme
GitHub用于创建或优化GitHub项目的README文档。支持新建README和审核改进现有README两种模式，强调清晰的价值主张、快速上手指南及真实代码示例，遵循30秒原则提升文档质量与可读性。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill good-readme -g -y
SKILL.md
Frontmatter
{
"name": "good-readme",
"license": "MIT",
"metadata": {
"author": "adewale",
"version": "0.1.0"
},
"references": [
"references\/anatomy.md",
"references\/examples.md",
"references\/quality-checklist.md",
"references\/anti-patterns.md"
],
"description": "Create and improve README documents for GitHub projects. Use when the user wants to write a new README, improve an existing one, audit README quality, or asks about documentation best practices for their repository."
}
good-readme
Philosophy
Core principle: A README is the front door to your project. It should answer "what is this, why should I care, and how do I use it?" within 30 seconds. Every section earns its place by serving a reader's real need — don't pad with boilerplate.
Good READMEs are scannable, honest, and audience-aware. They lead with a clear value proposition, show real usage examples, and respect the reader's time. A developer evaluating your project will decide in under a minute whether to invest further — the README is your pitch.
Bad READMEs are walls of text with no structure, auto-generated boilerplate nobody reads, or sparse one-liners that force readers to dig through source code. Equally bad: over-documented READMEs that duplicate what's in /docs or include every API method inline.
See anatomy.md for section-by-section guidance, examples.md for patterns from well-regarded projects, anti-patterns.md for common mistakes, and cloudflare.md for Cloudflare ecosystem conventions.
Modes
This skill operates in two modes:
1. Create — New README
For projects that have no README or need one written from scratch.
Before writing anything:
- Read the project's source code to understand what it does
- Identify the target audience (end users, developers, both?)
- Check for existing docs, config files, and CI setup that reveal project conventions
- Look at package.json / Cargo.toml / pyproject.toml / go.mod etc. for project metadata
- Ask the user: "Who is this README for, and what's the one thing you want them to understand?"
Writing process:
- Draft the title + one-line description (the hook)
- Write a concise "What & Why" section (2-4 sentences max)
- Add a quick-start that gets the reader from zero to working in minimal steps
- Include real, tested code examples — not pseudocode
- Add installation instructions appropriate to the ecosystem
- Only add sections that this specific project needs (see anatomy.md)
- Present draft to user for review before finalizing
2. Improve — Existing README
For projects with a README that needs enhancement.
Audit first:
- Read the current README completely
- Read the project source to check if README is accurate and current
- Score against the quality checklist
- Identify gaps, outdated content, and unnecessary sections
- Present findings to user with specific recommendations
Then improve:
- Fix factual inaccuracies first (wrong install commands, outdated API examples)
- Address structural issues (missing sections, poor ordering)
- Improve clarity and scannability (headers, code blocks, lists)
- Remove boilerplate that adds no value
- Verify all code examples work
- Present changes to user for approval
Key Principles
- Lead with value — The first 3 lines determine if someone keeps reading
- Show, don't tell — Code examples > prose descriptions
- Be honest about scope — State what the project does AND what it doesn't do
- Respect ecosystem conventions — npm projects look different from Rust crates
- Keep it maintained — A README that lies is worse than no README
- Link, don't duplicate — Point to docs/ for deep dives, keep the README focused
- Test your examples — Broken code examples destroy trust instantly
Per-Section Checklist
[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions
Version History
- e0220ca Current 2026-07-05 23:20
