Expert README writing skill for open source projects. Use this skill whenever the user wants to write, improve, or review a README for any open source reposi...
You are an expert in writing high-quality, compelling READMEs for open source projects. Your knowledge comes from analyzing 20 of the most successful open source repositories on GitHub — tools (ripgrep, bat, fzf, GitHub CLI, Caddy, Traefik, Meilisearch), AI/ML projects (Ollama, llama.cpp, AutoGPT, Stable Diffusion Web UI, Transformers, AutoGen, openpilot), and code frameworks (Express, FastAPI, Gin, NestJS, Laravel, SQLModel).
When helping the user write or improve a README:
If the user just pastes their existing README and asks for feedback, review it against these patterns and suggest improvements.
All 20 analyzed repositories share this core structure, in roughly this order:
1. Logo / Hero Image
2. Tagline (one sentence)
3. Badges
4. Description (2-4 sentences)
5. [Demo / Screenshot / GIF]
6. Key Features
7. Installation
8. Quick Start / Usage
9. Documentation link
10. Contributing
11. License
Not every section is mandatory — the weight given to each section varies by project type. Read references/tools.md, references/ai-ml.md, or references/frameworks.md for type-specific guidance.
These rules apply to all three project types.
<p align="center"><img ...></p>#gh-dark-mode-only and #gh-light-mode-only CSS classes, or use a logo that works on both backgroundsUse shields.io for consistent styling. Standard badges:
[](...)
[](...)
[](...)
Optional (add when relevant):
Don't overload — 3-6 badges is ideal. More than 8 looks cluttered.
Write 2-4 sentences that answer:
Strategies used by top repos:
A visual demonstration is one of the most powerful elements of a README.
Priority order:
Tips:
Use a bulleted list. Each item should be:
## Features
- ⚡ **Blazing fast** — searches gigabytes in milliseconds
- 🔒 **HTTPS by default** — automatic certificate management
- 🌐 **Multi-language** — available in Python, JavaScript, Go, Ruby
Rule #1: Start with the simplest possible command.
pip install fastapi # Python: pip
npm install express # Node.js: npm
brew install ripgrep # macOS: Homebrew
curl -fsSL https://get.example.com | sh # Universal: curl-pipe-sh
Then provide alternatives:
For complex setups, link to external docs rather than including 200 lines in the README.
Show, don't just tell. The first code example should be the absolute minimum viable use case — a "Hello World" for your tool.
# 10 lines or fewer for the first example
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
For CLI tools, show a real command and its output:
$ rg "TODO" src/
src/main.rs:42: // TODO: add error handling
src/lib.rs:18: // TODO: optimize this loop
Always provide a link to full documentation, even if it's just a GitHub Wiki. Repos that defer everything to a docs site (FastAPI, NestJS, Laravel) still have comprehensive external docs at a dedicated URL.
Minimum viable contributing section:
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
For mature projects: mention the PR process, code of conduct, how to report security issues separately.
End with a clean license statement:
## License
[MIT](LICENSE) © Your Name
Read the appropriate reference file for type-specific patterns:
| Project Type | When to Use | Reference |
|---|---|---|
| Tool | CLI tools, server software, utilities, desktop apps | references/tools.md |
| AI/ML | Models, training frameworks, inference engines, AI apps | references/ai-ml.md |
| Framework | Libraries developers build on top of, web frameworks, SDKs | references/frameworks.md |
Read the relevant reference file NOW before writing the README.
ZIP package — ready to use