readme-writer

Escreve ou reescreve um README de projeto que converte visitantes em usuários e contribuidores — pitch de uma linha, badges, início rápido de 60 segundos, exemplos reais, funcionalidades, FAQ, contribuição e licença — e faz lint para seções ausentes, links relativos quebrados, âncoras do sumário sem heading correspondente, alt text faltando e primeiro bloco de código tardio. Use quando o usuário pedir para escrever, melhorar, revisar ou reestruturar um README, disser que ninguém entende ou dá estrelas no projeto, ou estiver preparando um lançamento open source.

O que é readme-writer?

O README Writer é uma skill para agentes de IA (como Claude Code, Cursor ou Codex) que automatiza a criação, reescrita e revisão de READMEs de projetos. Seu objetivo é transformar um README em uma ferramenta de conversão: fazer um visitante passar de 'o que é isso?' para executar o primeiro comando em menos de um minuto, e depois mostrar como ir além e como contribuir. A skill suporta qualquer projeto — independente da linguagem ou ecossistema — e funciona em três etapas principais: coleta de fatos a partir do código, linting do README existente (se houver) e escrita seguindo uma estrutura testada (pitch, badges, quick start, funcionalidades, exemplos, FAQ, contribuição e licença). Ela inclui um linter próprio que verifica seções obrigatórias, links relativos quebrados, âncoras do sumário sem heading correspondente, imagens sem alt text e a posição do primeiro bloco de código (que deve aparecer antes da linha 60). A skill é especialmente útil quando o usuário relata baixo engajamento (visitas mas sem estrelas, instalações ou contribuidores) ou está se preparando para um lançamento. Ela também gera um resumo final com fatos não verificados e placeholders que o usuário precisa preencher (como GIFs ou screenshots).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more Produtividade e Colaboração skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

README writer

Um README tem um trabalho: levar um visitante de "o que é isso?" a executar o primeiro comando em menos de um minuto, e depois mostrar como ir além e como ajudar.

Quando usar

  • Escrevendo um README para um projeto novo, ou reescrevendo um muito resumido ou confuso
  • Revisando um README antes de um lançamento ou de uma versão 1.0
  • O usuário diz que o projeto tem visitas, mas não recebe estrelas, instalações ou contribuidores

Quando não usar

  • Documentação de referência de API (gere-a a partir do código; crie links a partir do README)
  • Tutoriais longos ou documentação de arquitetura: coloque-os em docs/ e crie links

Fluxo de trabalho

  1. Colete fatos antes de escrever. Leia o manifesto (pyproject.toml, package.json, composer.json, Cargo.toml...), a saída --help da CLI ou o ponto de entrada principal, a documentação existente e a licença. Encontre o comando de instalação real e um exemplo real. Nunca invente flags, saídas, benchmarks ou funcionalidades.

  2. Pergunte ao usuário apenas o que o código não pode dizer: para quem é o projeto, o único problema que ele resolve e por que é melhor que a alternativa óbvia. Se não estiverem disponíveis, escreva um pitch neutro a partir do código e marque-o para revisão.

  3. Faça lint do README atual (se houver). scripts/ é relativo a esta skill:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. Escreva usando a estrutura em structure.md, começando a partir do template. A ordem importa: título + badges, pitch, (imagem de demonstração), início rápido, funcionalidades, uso/exemplos, configuração, FAQ, roadmap, contribuição, licença.

  5. Aplique as regras de escrita:

    • Pitch: uma frase, com menos de 200 caracteres, sem palavras de hype. Padrão: "<nome> é um(a) <categoria> que <faz X> para <público>, <principal diferencial>."
    • Primeiro bloco de código acima da linha 60. Todo comando deve ser copiável e real.
    • Mostre a saída após comandos quando ajudar (# => ... ou um bloco separado).
    • Use tabelas para opções e comparações, listas para funcionalidades (benefício primeiro).
    • Vincule, não cole: documentações longas, changelogs e referências de API vão para outro lugar.
    • Toda imagem deve ter alt text; prefira um SVG ou um GIF curto do fluxo principal.
  6. Badges. Use apenas badges que sejam verdadeiros e mantidos, nesta ordem: status da CI, versão mais recente (PyPI/npm/Packagist/release), downloads (opcional), licença. Exemplos em structure.md.

  7. Refaça o lint até que não haja erros. Resolva avisos ou informe ao usuário por que não.

  8. Verifique os links que o linter não consegue: URLs absolutas e âncoras. Teste clicando ou explique quais não foram verificados.

Saída

  • O README.md novo ou atualizado (mostre um resumo diff para reescritas).
  • O resultado final do lint.
  • Uma lista curta de fatos que você não pôde verificar e placeholders que o usuário deve preencher (GIF de demonstração, screenshots, números de benchmark).

Regras de lint

RegraNívelSignificado
titleerro/avisoexatamente um H1
pitcherro/avisoum primeiro parágrafo curto abaixo do título
badgesavisonenhum badge encontrado
installerro/avisoseção de instalação (ou início rápido), com um bloco de código
quickstarterro/avisoseção de uso, início rápido ou exemplo, com código
codeerronenhum bloco de código
scrollavisoprimeiro bloco de código após --max-scroll linhas (padrão 60)
contributing, licenseavisoseção ausente
faq, tocinformaçãosugerido
alt-textavisoimagem sem alt text
broken-linkerrolink relativo para um arquivo ausente, ou link vazio
broken-anchorerrolink #anchor (sumário) que não corresponde a nenhum heading ou id/name HTML, usando regras de slug do GitHub
placeholderavisoTODO, TBD ou lorem ipsum deixados

Saída com código 1 em caso de erros (e com avisos, se --strict).

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas