A Claude Code skill that teaches AI agents to write excellent READMEs — so you never ship a bare-bones one again.
"A README is the single most important document in any codebase — it's read 10x more than any other file."
You: Write a README for this project
AI: I'll analyze your project structure and generate a README following best practices...
Before — what you'd write in 30 seconds:
# my-api-client
A client for the Foo API. Install with `npm install my-api-client`.
See source code for usage.
After — what Claude produces with this skill:
<p align="center"><img src="assets/logo.svg" height="80"></p>
<h1 align="center">my-api-client</h1>
<p align="center">A lightweight, typed client for the Foo API with retries and streaming.</p>
[Badges: build | version | license]
## Demo
[Terminal GIF showing a 3-line script that fetches data]
## Key Features
- Zero dependencies, tree-shakeable
- Full TypeScript support with generated types
- Automatic retry with exponential backoff
## Quick Start
npm install my-api-client
## Usage
[3 real-world examples with input → output]
## Contributing | License| If you are... | This skill helps you... |
|---|---|
| Open source maintainer | Write READMEs that attract contributors and reduce issue noise |
| Solo developer | Ship professional documentation in minutes, not hours |
| Team lead | Standardize README quality across all team repos |
- Cognitive Funneling — arrange information wide-to-narrow so readers can decide in 30 seconds
- Golden Structure Template — the 12-section order proven by the best open-source projects
- Show Don't Tell — demo format for every project type: GIF, conversation, before/after, Mermaid
- vhs Auto-Install + Record — detects OS, installs vhs if missing, creates
.tapescript, records terminal GIF automatically - Logo & Dark/Light Mode — generate SVG logos with
<picture>for GitHub theme adaptation - Multi-Platform Install — templates for Claude Code, Cursor, Codex, Gemini CLI
- Mandatory Execution Sequence — 7-step enforced workflow that cannot be skipped or reordered
- Pre-Completion Verification — automated checks (file existence, structure sync, no Chinese in README.md) that must ALL pass before claiming done
- Self-Scoring & Iteration — auto-scores against a 100-point rubric, iterates until 90+, outputs improvement roadmap
- Audience Routing — "Who Is This For" tables that guide different readers to the right section
- Security Section Guide — required for plugins/CLIs that execute code
- 19 Common Mistakes — checklist of pitfalls with concrete fixes
/plugin marketplace add weiliu1031/writing-readme
/plugin install writing-readme@writing-readmeOther install methods
git clone https://github.com/weiliu1031/writing-readme.git ~/.claude/skills/writing-readme/add-plugin writing-readme
You: Write a README for this project
Claude analyzes your project structure, identifies the type (CLI / library / API / GUI / plugin), and generates a complete README — with logo, badges, demo section, features, install, usage examples, contributing guide, and license. For CLI projects, it also generates a vhs .tape script for terminal GIF recording.
You: Improve this README — it's missing a demo and the install section is too long
Claude evaluates against the checklist, identifies gaps, and rewrites weak sections while preserving your existing content.
You: Score this README against best practices
Claude rates each section (logo, badges, demo, features, install, usage, contributing, license) and outputs actionable improvement suggestions with a numeric score.
graph LR
A["Your Project"] --> B["Analyze<br/>project type"]
B --> C["Apply Golden<br/>Structure"]
C --> D["Generate Assets<br/>logo · vhs GIF · mermaid"]
D --> E["Write README<br/>EN + CN"]
E --> F["Self-Score<br/>/100"]
F --> G{"≥ 90?"}
G -->|No| H["Fix & Re-score"]
H --> F
G -->|Yes| I["Output score +<br/>improvement suggestions"]
The skill is built on 10 modules distilled from awesome-readme and the top 40 most-starred GitHub repos and skill projects:
| Module | Source | What it teaches |
|---|---|---|
| Hook / Opening | garrytan/gstack, torvalds/linux | Grab attention with quotes, pain points, or bold claims |
| Cognitive Funneling | Art of README | Arrange info wide→narrow, let readers short-circuit exit |
| Golden Structure | 90+ curated README examples | The 12-section order that works for every project |
| Show Don't Tell | electron-markdownify, GoFiber, sniffnet | GIF, conversation demo, before/after, input→output |
| vhs Auto-Record | charmbracelet/vhs | Auto-install vhs, create .tape, record terminal GIF |
| Logo & Visuals | openclaw (dark/light mode), nerd-fonts | <picture> theme adaptation, SVG generation, badge layout |
| Multi-Platform Install | planning-with-files, gstack | Collapsible install for Claude Code / Cursor / Codex / Gemini |
| Audience Routing | torvalds/linux, humanizer | "Who Is This For" tables, role-based navigation |
| Self-Scoring Loop | Original | 100-point rubric, auto-iterate to 90+, output improvement roadmap |
| Common Mistakes | Top 10 Reasons | 15 pitfalls: no demo, wall of text, external URLs, missing security |
| Asset Type | How | Example |
|---|---|---|
| SVG Logo (dark + light) | Writes .svg pair to assets/ + <picture> tag |
Project initials with theme-adaptive colors |
| Terminal GIF | Auto-installs vhs → writes .tape → records GIF |
CLI tool demo, fully automated |
| Mermaid Diagram | Inline in README, GitHub renders natively | Architecture, data flow, state machines |
| SVG Diagram | Writes .svg to assets/ |
Custom pipeline or component diagrams |
| Screenshot Placeholder | HTML + instructions for user | GUI apps where Claude can't capture screen |
| Score Report | Self-evaluates against 100-point rubric | Dimension breakdown + improvement roadmap |
This skill runs within Claude Code's sandboxed environment and:
- Does NOT execute arbitrary code outside the sandbox
- Does NOT send data to external services
- Does NOT require network access
- Only reads project files to analyze structure for README generation
Contributions welcome! If you know a README pattern, tool, or anti-pattern that should be included:
- Fork this repo
- Edit
skills/writing-readme/SKILL.md - Open a pull request explaining what you added and why — include a link to the README that inspired it
Bug reports and feature requests via Issues.