convez.ai
SkillEscrita & ConteúdoIntermediário
adewale

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 GitHub
InicialPluginScore · de 0 a 100

Um 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-readme

1 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

Estrelas
16
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.1.1
Issues abertas
3
Contribuidores
1

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

skills.sh

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/clientInstall or use
Codexcp -R skills/good-readme ~/.codex/skills/good-readme
OpenCodecp -R skills/good-readme ~/.config/opencode/skills/good-readme or use .opencode/skills/good-readme in a project
Pipi install https://github.com/adewale/good-readme or pi --skill skills/good-readme
Gemini CLIgemini skills install https://github.com/adewale/good-readme --path skills/good-readme or copy to .gemini/skills/good-readme
Claude Codenpx 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

FilePurpose
skills/good-readme/SKILL.mdSkill definition — philosophy, modes, and workflow checklists
skills/good-readme/references/anatomy.mdSection-by-section guide for every part of a README
skills/good-readme/references/examples.mdPatterns extracted from well-regarded open-source projects
skills/good-readme/references/quality-checklist.md22-criterion scoring rubric (100-point scale)
skills/good-readme/references/anti-patterns.md15 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

Ver o original no GitHub

Bom para

Relacionados