Good README - Escritor e Auditor de Documentação
adewale/good-readme
Escreve e melhora READMEs com base em análise real do código
Ver no GitHubUm skill para Claude Code que escreve READMEs do zero ou audita documentação existente contra um rubric de 100 pontos. Analisa o código real do projeto para gerar exemplos funcionais e identificar inaccurácias, gaps e oportunidades de melhoria na documentação.
Instalação
npx convez-ai adewale/good-readme1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar README completo para novo projeto analisando estrutura do código
- Auditar qualidade de documentação com relatório estruturado de pontuação
- Validar exemplos de código contra codebase real para precisão
- Identificar gaps em documentação e priorizar melhorias
Veredito

Skill bem estruturada que resolve um problema real: documentação de qualidade baseada em análise de código, não templates vazios. Útil para desenvolvedores que criam projetos e querem documentação profissional sem esforço manual repetitivo.
README
A tradução para o português deste README ainda está na fila.
good-readme
An Agent Skill for writing and improving GitHub README documents.
Give it a project with no README and it writes one from scratch — grounded in real analysis of the source code, not boilerplate templates. Give it a project with an existing README and it audits quality against a 100-point rubric, catches inaccuracies, and makes targeted improvements.
Install
npx skills add adewale/good-readme
Skills appear on skills.sh automatically after users install the repo with the skills CLI. Install counts and leaderboard rankings come from anonymous CLI telemetry; opt out with DISABLE_TELEMETRY=1. The repo page customization in skills.sh.json is picked up after the repository is seen by telemetry and the cache refreshes.
Agent compatibility
The installable skill directory is skills/good-readme. It uses the Agent Skills SKILL.md format and is configured for Codex, OpenCode, Pi, Gemini CLI, and Claude Code.
| Agent/client | Install or use |
|---|---|
| Codex | cp -R skills/good-readme ~/.codex/skills/good-readme |
| OpenCode | cp -R skills/good-readme ~/.config/opencode/skills/good-readme or use .opencode/skills/good-readme in a project |
| Pi | pi install https://github.com/adewale/good-readme or pi --skill skills/good-readme |
| Gemini CLI | gemini skills install https://github.com/adewale/good-readme --path skills/good-readme or copy to .gemini/skills/good-readme |
| Claude Code | npx skills add adewale/good-readme or copy to .claude/skills/good-readme |
Usage
Open your coding agent in any project directory and ask:
Write a README for this project
Audit this project's README and suggest improvements
Score this README and tell me what to fix first
The skill activates automatically when you ask about READMEs, documentation quality, or writing project docs.
Example: Audit output
The improve mode scores your README across six categories and returns a structured report:
## README Quality Audit
**Project:** my-project
**Score:** 62 / 100
**Rating:** Adequate
| Category | Score | Max |
|-----------------------------|-------|-----|
| First Impressions | 14 | 20 |
| Getting Started | 12 | 20 |
| Usage & Examples | 10 | 20 |
| Structure & Scannability | 11 | 15 |
| Accuracy & Maintenance | 10 | 15 |
| Completeness | 5 | 10 |
### Priority Improvements
1. Quick-start — no working example after install steps — add a 3-step quick-start
2. Code examples — imports are missing — make examples copy-pasteable
3. Value proposition — description says what, not why — add one sentence on the problem it solves
What It Does
Create mode — for projects without a README:
- Reads source code, config files, and package metadata to understand what the project does
- Asks who the audience is, then drafts a README tailored to them
- Produces real, tested code examples — not pseudocode
- Follows ecosystem conventions (npm vs Rust vs Python vs Go)
Improve mode — for projects with an existing README:
- Audits against a 22-criterion quality checklist scored out of 100
- Checks code examples against the actual codebase for accuracy
- Identifies gaps, outdated content, and unnecessary sections
- Presents specific recommendations before making changes
What's Included
| File | Purpose |
|---|---|
skills/good-readme/SKILL.md | Skill definition — philosophy, modes, and workflow checklists |
skills/good-readme/references/anatomy.md | Section-by-section guide for every part of a README |
skills/good-readme/references/examples.md | Patterns extracted from well-regarded open-source projects |
skills/good-readme/references/quality-checklist.md | 22-criterion scoring rubric (100-point scale) |
skills/good-readme/references/anti-patterns.md | 15 common README mistakes and how to fix them |
Contributing
Contributions welcome. If you'd like to improve the skill's reference materials or add new patterns:
git clone https://github.com/adewale/good-readme.git
cd good-readme
Open a PR with your changes. For larger additions (new reference files, changes to the scoring rubric), please open an issue first to discuss.
License
MIT — see LICENSE