GitHub README Guide is a practical, battle-tested playbook for writing professional open-source READMEs. It was distilled from two sources of truth: a deep dissection of the cc-switch README (a phenomenon-grade open-source project) and the full open-sourcing journey of vision-mcp — every rule in this guide was applied and verified in real production.
The guide ships in two forms: a human-readable document and an installable AI skill (playbook) so you can use it both for learning and for instant invocation when writing your next README.
- 📐 Structure template — The 9-section skeleton from top-grade repos: centered header → highlights → architecture → quick start → config → FAQ → dev guide → structure → license
- 🛡️ shields.io badge engineering — Static vs. dynamic badges, color semantics, URL encoding traps, linking, and the three taboos
- 🌐 Multi-language support —
README_ZH/JA/DEconventions, cross-linking, and translation principles - 📋 Pre-release checklist — Verify commands, badges, license, dead links, and releases before publishing
- 🤖 Dual form — Human-readable guide + installable AI skill for instant use
| File | What it is |
|---|---|
github-readme-guide-zh.md |
The full 9-chapter guide (Chinese) |
github-readme-guide-en.md |
The full 9-chapter guide (English) |
skill/SKILL.md |
The AI playbook — install it into Reasonix / Claude-style skill directories |
Open github-readme-guide-zh.md — 9 chapters covering everything from the one-line positioning statement to the badge URL cheat sheet.
Copy skill/SKILL.md into your AI tool's skill directory (e.g. Reasonix: E:\ReasonixData\skills\github-readme\SKILL.md, or register the folder in config.toml under [skills] paths). Then just say:
/github-readme # or: "帮我写 README"
The playbook loads automatically and walks you through structure, badges, and the pre-release checklist.
Is this guide really "professional"?
Every rule was applied live while open-sourcing vision-mcp: 4-language READMEs, 6 badges (2 dynamic), a v1.1.0 release with a downloadable exe, and verified live badge data. What survives in the guide is what actually worked.
Why is the guide in Chinese?
The source material (cc-switch dissection and the vision-mcp journey) was produced in Chinese. English speakers can still follow the structure, badges, and checklists — they are language-agnostic.
Can I contribute a translated version?
Absolutely! PRs for an English full translation or other languages are welcome.
├── README.md # This page (self-demonstrating the guide)
├── github-readme-guide-zh.md # The full 9-chapter guide
├── skill/
│ └── SKILL.md # Installable AI playbook
├── CHANGELOG.md # Version history
└── LICENSE # MIT
Issues and PRs are welcome! For new features, please open an issue first to discuss.
MIT © Ameng