Gerador de README para GitHub
O README é a primeira página de portfólio de um projeto. Não é um índice de manual, nem um contêiner de lista de funcionalidades. Ele deve responder três coisas em muito pouco tempo:
- O que é isso.
- Por que vale a pena ver.
- Como eu começo a usar.
Este Skill tem como objetivo gerar READMEs nota 100: claros, estéticos, contidos, confiáveis, que fazem o projeto ser compreendido como um trabalho completo.
Primeiros Princípios
O README é um ponto de entrada de confiança e navegação, não uma documentação completa. Ele deve ajudar quem abre o repositório pela primeira vez a fazer um julgamento rápido:
- Que problema este projeto resolve.
- Se é adequado para mim.
- Se posso executar, instalar ou continuar imediatamente.
Projetos open source com mais de 1w estrelas geralmente não vencem pela quantidade de informação, mas pela clareza da primeira tela, um caminho de uso direto, uma entrada de documentação confiável e informações comunitárias contidas. Imagens, badges, informações do autor e conceitos de design são apenas auxiliares; uma vez que atrasam a compreensão, são ruído.
A troca central deste Skill: o README primeiro explica o projeto, depois o embeleza; o visual serve à compreensão, não a substitui.
Padrão do Trabalho
Use a tabela de pontuação abaixo para restringir toda a saída:
| Dimensão | Pontos | Critério |
|---|---|---|
| Compreensão em 15s | 25 | A primeira tela deve mostrar o nome do projeto, valor e público-alvo |
| História do projeto | 20 | Não é uma lista de funcionalidades, mas sim o contexto, motivação e resultados |
| Expressão visual | 20 | Imagens parecem trabalhos de portfólio, não capturas de tela de processos com letras pequenas |
| Início rápido | 15 | Caminho de instalação e uso curto, claro e copiável |
| Produto confiável | 10 | Mostrar resultados reais, limites de capacidade ou saídas |
| Conter ruído | 10 | Remover repetições, slogans, explicações excessivas e decoração |
READMEs com menos de 90 pontos não são entregues; primeiro remova o ruído, amplie o foco e reorganize a narrativa.
Linha de base de projetos com muitas estrelas
Por padrão, aprenda com projetos open source de alto desempenho estas estruturas:
- Nome do projeto + proposta de valor em uma frase.
- Poucos badges necessários, sem acumular decoração de status.
- Início rápido ou entrada de documentação no início.
- Exemplos apenas quando reduzem o custo de aprendizado.
- Contribuição, comunidade, segurança, licença de forma clara e concisa.
- Projetos de UI / produto podem colocar capturas de tela; bibliotecas, SDKs, ferramentas de infraestrutura, poucas ou nenhuma imagem.
Não transforme o README em um manifesto de design, manual completo, mural de funcionalidades, cartão de visitas social ou relatório de fluxo de trabalho interno.
Princípios de Design
Obrigatório
- H1 deve ser o nome oficial do projeto, seguido imediatamente por uma proposta de valor.
- O README começa explicando o valor do projeto, depois coloca detalhes de instalação.
- Imagens devem expressar apenas um ponto principal, mas devem funcionar como cartão de visita do projeto: permitir que o leitor veja o nome e o posicionamento rapidamente.
- Por padrão, no máximo duas imagens: uma capa e uma imagem de capacidade principal ou resultado.
- O GitHub reduz o tamanho das imagens na exibição; o texto principal na imagem deve ser projetado com tamanho de pôster.
- A descrição das funcionalidades deve ser específica, mas sem exageros; se puder mostrar com resultados, não se vanglorie.
- Mantenha as informações do autor e da licença concisas, sem acumular cartão de visitas social.
Deve ser evitado
- Títulos em ASCII art.
- Emojis decorativos em títulos ou tabelas de autores.
- Longos parágrafos de frases vazias como "somos muito profissionais".
- Mais de 6 cartões pequenos empilhados em uma única imagem.
- Fluxogramas cheios de etapas, comandos e letras pequenas.
- Usar o terceiro fluxograma como produto padrão; a forma de trabalho geralmente é mais clara em texto corrido.
- Usar o Image Gen como ferramenta de diagramação de texto longo.
- Transformar o README em um manual completo do produto; a documentação detalhada deve ir para
docs/.
Fluxo Geral
Fase 0 Leitura do projeto e reconhecimento de padrões
Fase 1 Destilação da história do projeto
Fase 2 Escolha do método de geração visual
Fase 3 Geração de ativos visuais de nível profissional
Fase 4 Montagem do README
Fase 5 Sugestão de metadados GitHub
Fase 6 Validação e entrega
Fase 0: Leitura do projeto e reconhecimento de padrões
Primeiro, leia o projeto, não escreva um modelo diretamente.
Verifique:
ls
find . -maxdepth 2 -type f | sed 's#^\./##' | sort | head -80
Leia prioritariamente:
README.mdpackage.json/pyproject.toml/go.mod/Cargo.tomldocs/- Arquivos de entrada principais
- Exemplos, capturas de tela, arquivos de demonstração
Determine o cenário e o orçamento visual:
| Cenário | Como determinar | Estratégia | Limite de imagens |
|---|---|---|---|
| Novo README | Sem README ou README muito curto | Gerar completo, mas manter caminho curto | 1-2 |
| Atualizar README | README existente com conteúdo válido | Manter conteúdo único, reescrever estrutura e primeira tela | 0-2 |
| Reforço de portfólio | Usuário enfatiza estética, história, exibição | Priorizar narrativa e desempenho da capa | 2 |
| Modo apenas documentação | SDK, biblioteca, ferramenta de backend, infraestrutura | Poucas imagens, focar em instalação, API, entrada de documentação | 0-1 |
| Exibição de UI / produto | Com interface, captura de tela, demo, resultado visual | Usar resultados reais ou capa para ajudar na compreensão | 1-2 |
Ao atualizar um README existente, não exclua conteúdo chave já presente do usuário. Primeiro extraia o conteúdo que pode ser mantido, depois reorganize.
Revisão de ruído
Antes de escrever o README, marque quais conteúdos devem ser movidos para fora ou excluídos:
| Conteúdo | Tratamento padrão |
|---|---|
| Tabela de pontuação de design, princípios de trabalho, metodologia interna | Colocar em SKILL.md ou docs/, não no README |
| Árvore de arquivos gerada, variáveis de modelo, detalhes de script | Manter apenas quando o usuário precisar de documentação de desenvolvimento |
| Terceiro fluxograma | Excluir, substituir por 2-4 linhas de texto ou lista curta |
| Muitos links sociais | Manter apenas entrada principal como GitHub / site |
| Lista de funcionalidades muito genérica | Consolidar em 3 capacidades orientadas a resultados |
| Longo contexto antes da instalação | Encurtar, antecipar o início rápido |
Fase 1: Destilação da história do projeto
Colete ou deduza 7 campos:
| Campo | Descrição |
|---|---|
project_name | Nome oficial do projeto |
tagline | Proposta de valor em uma frase, curta e com julgamento |
origin | Contexto em que o projeto surgiu: por que foi necessário |
audience | Quem vai usá-lo |
promise | Que resultado ele ajuda o usuário a obter |
proof | Capacidade real, captura de tela, saída, exemplo, métrica |
start | Caminho mais curto para começar |
Não faça muitas perguntas. Se puder deduzir do projeto, deduza diretamente; só pergunte ao usuário quando afetar a precisão da narrativa.
Estrutura de narrativa recomendada
Nome do projeto
Proposta de valor em uma frase
Capa visual (decidir conforme tipo de projeto)
O que é isso
Por que é necessário
O que você vai obter
Início rápido
Exemplo ou saída
Como funciona (texto corrido, sem imagem padrão)
Instalação
Licença
Autor
Se o projeto for mais ferramenta, biblioteca ou infraestrutura, mova "Início rápido" para depois de "Por que é necessário". A ordem do README deve servir à ação do leitor, não à completeza do modelo.
Fase 2: Escolha do método de geração visual
Imagens do README têm dois tipos:
- Capa do trabalho: transmite o tom, tema, ponto de memória.
- Diagrama de explicação estrutural: transmite etapas, capacidade, comparação, fluxo.
Escolha o modo com base na intenção do usuário:
| Modo | Cenário de aplicação | Estratégia de imagem |
|---|---|---|
portfolio | Recomendação padrão, adequado para projetos que precisam mostrar sensação de trabalho completo | 1 capa + 1 imagem de capacidade principal |
clean-doc | SDK, biblioteca, ferramenta de backend, infraestrutura séria | 0-1 imagem, priorizar início rápido e exemplo |
visual-story | Ferramenta de IA, ferramenta de design, produto independente, exibição de trabalho | Máximo 2 imagens, Codex Image Gen responsável pelo ponto de memória |
structured | Usuário solicita explicitamente infográfico, gráfico de comparação, fluxograma | 1-2 pôsteres HTML/CSS, garantir precisão do texto |
Por padrão, primeiro determine o tipo de projeto, não force o modo portfolio. A prioridade de geração de ativos visuais é fixa:
- Codex Image Gen Skill: use a capacidade de geração de imagens integrada do Codex primeiro para gerar ativos visuais.
- Leve: imagens de exibição do README devem ser convertidas para WebP primeiro, depois escrever o caminho de referência no README.
- Fallback HTML para PNG: somente quando o Image Gen não estiver disponível, a saída não atender aos requisitos ou o usuário solicitar explicitamente texto estruturado preciso, então degrade para captura de tela de modelo HTML/CSS.
Não torne a captura de tela HTML o caminho padrão. É um backup confiável, não a opção visual preferida.
Fase 3: Geração de ativos visuais de nível profissional
A saída padrão usa dois nomes de arquivo estáveis:
assets/banner.webp
assets/features.webp
Assim, o caminho de referência do README é estável, independentemente de a imagem vir do Codex Image Gen ou do fallback de captura de tela HTML.
Responsabilidades das imagens
| Imagem | Objetivo | Método recomendado |
|---|---|---|
banner.webp | Cartão de visita do projeto, estabelece nome, posicionamento e ponto de memória | Codex Image Gen prioritário |
features.webp | Imagem de divulgação de capacidade principal, resultado ou fluxo necessário | Codex Image Gen prioritário; fallback HTML para precisão textual |
Não gere workflow.png ou workflow.webp por padrão. Se o usuário solicitar explicitamente um fluxograma, mescle o conteúdo do fluxo em features.webp ou coloque no texto corrido, sem adicionar uma terceira imagem.
Estilo visual padrão
Todos os ativos visuais do README usam o mesmo estilo:
Fundo preto, minimalista, iluminação cinematográfica, alto contraste, grande espaço em branco, baixo brilho, três cores: branco, cinza, dourado quente, sensação de capa de revista premium.
Textura da imagem: fundo preto profundo #050505, granulação de papel, profundidade de campo rasa, névoa volumétrica, luz de contorno fina, realces metálicos seletivos.
Nível de qualidade: padrão de designer de 10k estrelas.
Restrições de design:
- Fundo predominantemente preto profundo
#050505. - Cores apenas: branco, cinza, dourado quente; não introduza gradiente arco-íris, neon azul-roxo ou cores decorativas de alta saturação.
- Use grande espaço em branco e luz local, não empilhe elementos.
- A imagem deve conter uma pequena quantidade de texto de alto valor, assumindo a função de divulgação e posicionamento, sem explicações longas.
- Quanto menos texto, melhor: cada imagem retém apenas a informação que o leitor ainda deve lembrar depois de sair do README.
- Não coloque parágrafos, comandos, tabelas, empilhamento de números de versão ou descrições densas.
Estratégia de texto do cartão de visita do projeto
Use o padrão "imagem cartão de visita do projeto", não imagem de atmosfera pura.
| Imagem | Texto recomendado | Limite |
|---|---|---|
banner.webp | Nome do projeto + frase de posicionamento + 1-3 tags curtas | 18 palavras em inglês ou 28 caracteres em chinês |
features.webp | 2-3 frases de resultado, opcionalmente um título curto | Cada frase 2-5 palavras |
Bom texto deve parecer título de capa, não manual de instruções:
- O nome do projeto deve estar claro, priorize colocá-lo em
banner.webp. - A frase de posicionamento diz o resultado, não o slogan, por exemplo "Portfolio-grade README design for open source projects".
- Tags apenas para palavras de maior valor de busca e memória, por exemplo
Story,Visual,Signal. - Chinês pode ser usado, mas pouco; nomes de projeto em inglês e tags curtas em inglês geralmente são mais estáveis.
- Se o Image Gen escrever o texto errado, tente novamente uma vez; se ainda não estiver preciso, mantenha a imagem de fundo do Image Gen e use fallback HTML/CSS para texto preciso.
- Não sacrifique a precisão do nome do projeto e posicionamento por "geração totalmente AI".
Tamanho mínimo de fonte
Ao projetar em 1920×1080:
| Elemento | Tamanho mínimo |
|---|---|
| Título principal | 92px |
| Título principal em chinês | 80px |
| Título do cartão grande | 48px |
| Descrição do corpo | 28px |
| Tag auxiliar | 22px |
| Rodapé | 20px |
Não use texto abaixo de 18px. Ficará ilegível após o redimensionamento do GitHub.
O produto do Codex Image Gen só precisa manter 16:9 e nitidez suficiente. Não force a reamostragem de uma boa imagem para 1920×1080 apenas por causa disso. Imagens de exibição do README devem ser salvas como WebP primeiro; 1920×1080 é o tamanho do modelo de fallback HTML para PNG.
Fallback HTML para PNG
Use apenas quando o Image Gen não estiver disponível, o usuário solicitar texto estruturado preciso ou a saída do Image Gen não passar na verificação:
node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/convert_webp_assets.mjs assets/banner.png assets/banner.webp assets/features.png assets/features.webp
Modelos de:
templates/banner.html
templates/features.html
Variáveis do modelo:
{{PROJECT_NAME}}
{{TAGLINE}}
{{PRIMARY_COLOR}}
{{CATEGORY}}
{{PLATFORM}}
{{LANGUAGE}}
{{VERSION_INFO}}
{{TECH_CARDS}}
{{FEATURE_CARDS}}
{{FEATURE_COUNT}}
Estrutura dos cartões:
{{TECH_CARDS}}usado no lado direito da capa, recomenda-se 2-3, apenas tags curtas e uma descrição.{{FEATURE_CARDS}}apenas 2-3 cartões grandes, o primeiro pode terfeatured.- Se precisar expressar fluxo de trabalho, use os 3 estágios de resultado de
features.webp, não adicione uma terceira imagem.
Método Codex Image Gen / gpt-image-2
Por padrão, chame a capacidade de geração de imagens integrada do Codex primeiro, não codifique scripts de API temporários no projeto.
Conteúdo adequado para Image Gen:
- Capa do README.
- Imagem de atmosfera do produto.
- Visual de portfólio.
- Imagem de conceito abstrato.
- Usar imagem existente para extensão de estilo.
Conteúdo inadequado para Image Gen:
- Fluxograma preciso.
- Grande quantidade de texto em chinês ou várias descrições.
- Comandos, versões, tabelas.
- Texto longo ou imagem de interface que precisa ser preciso palavra por palavra.
Estrutura de prompt recomendada:
Use case: productivity-visual
Asset type: GitHub README visual asset, 16:9
Project: <project_name>
Story: <origin + promise>
Visual direction: black background, minimalist, cinematic lighting, high contrast, large negative space, low brightness, premium magazine cover
Texture and lighting: #050505 deep black background, subtle paper grain, shallow depth of field, volumetric haze, thin rim light, selective metallic highlights
Palette: white, gray, warm gold only
Composition: one strong visual idea, restrained, spacious, no dense UI
Quality bar: 10k-star designer portfolio quality
Text policy: include only high-value name-card text. Use the exact project name, one short positioning line, and optional 1-3 short labels. No paragraphs, commands, tables, tiny captions, or decorative text.
Avoid: emoji, clutter, fake interface text, tiny labels, generic gradients, bright neon, overdesigned dashboards
Se o Image Gen não suportar, não puder ser chamado ou a saída apresentar texto errado/desvio de estilo, tente novamente com um prompt de texto mais curto; se ainda não estiver preciso, volte para o fluxo de fallback HTML para PNG para texto preciso.
Leveza das imagens
Imagens de exibição do README usam WebP por padrão. WebP geralmente é melhor que PNG para carregamento no README; PNG só é usado como produto intermediário do fallback de captura de tela HTML, para imagens transparentes ou quando precisar de preservação sem perdas.
Comando padrão:
npm run webp
Se o projeto não tiver script de conversão WebP, use cwebp, sips ou ferramenta leve disponível primeiro. Não introduza dependências pesadas só para conversão. Se não puder converter, mantenha PNG e explique o motivo.
Verificação visual
Após gerar cada imagem, verifique:
- Ainda legível quando reduzida à largura de exibição do README do GitHub.
- Uma imagem conta apenas um ponto principal.
- Sem empilhamento de letras pequenas.
- Nome do projeto e frase de posicionamento visíveis à primeira vista.
- Texto na imagem sem erros de ortografia, caracteres ilegíveis ou pseudo-texto.
- Sem decoração excessiva.
- Estilo visual consistente com a história do projeto.
- Imagem do Image Gen sem texto errado ou marcas d'água extras.
- Imagem ainda nítida após compressão, sem faixas de cor perceptíveis, ruído destrutivo ou bordas de texto borradas.
Fase 4: Montagem do README
Estrutura padrão:
<div align="center">
# Nome do Projeto
**Proposta de valor em uma frase**
<img src="assets/banner.webp" alt="[Nome do Projeto] — [Proposta de valor]" width="100%">
[](./LICENSE)
</div>
---
## O que é isso
[2-3 frases explicando o projeto, contexto, resultado.]
## Por que é necessário
[Fale sobre o problema real, não liste uma checklist de anti-padrões.]
## O que você vai obter
<img src="assets/features.webp" alt="[3 capacidades principais]" width="100%">
## Como funciona
[2-4 linhas explicando como funciona; não coloque uma terceira imagem por padrão.]
## Início rápido
[Caminho executável mais curto.]
## Instalação
[Dependências e comandos de instalação.]
## Licença
[MIT](./LICENSE)
## Sobre o autor
[Informação concisa do autor.]
Regras:
- Não ultrapasse 3 badges, a menos que o projeto realmente precise de indicadores de status.
- Não repita a mesma lista de funcionalidades após as imagens.
- Não coloque "princípios de design", "estrutura do projeto", "conteúdo gerado" no README; mantenha apenas o que é útil para o leitor.
- Não coloque um terceiro fluxograma por padrão; duas imagens já são suficientes para transmitir a sensação de trabalho e informações principais.
- Se houver explicação detalhada, coloque em
docs/, o README é apenas a entrada.
Fase 5: Recomendação de metadados GitHub
A Descrição do Repositório e os Tópicos são a entrada para a pesquisa do GitHub, associação Trending, referência de pesquisa AI e julgamento rápido humano. Não são conteúdo do README, não os escreva em README.md; saia apenas como sugestão independente na resposta final.
Objetivo dos primeiros princípios
- Description responde: para quem este projeto cria qual resultado.
- Topics responde: em quais baldes de pesquisa este projeto deve ser colocado.
- Quantidade recomendada determinada pela qualidade do sinal, não pela quantidade; 7-9 de alta qualidade geralmente são melhores do que encher 20.
- Trending / SEO / GEO equilíbrio: cobrir termos de pesquisa populares, mas manter a precisão factual do projeto para facilitar a referência AI.
Regras de geração de Description
Gere 3 candidatos e avalie cada um:
[Verbo] [resultado específico] para [público-alvo] — [1-3 palavras-chave precisas]
Restrições rígidas:
- Inglês primeiro, ≤ 160 caracteres.
- Começa com verbo: Design / Generate / Build / Create / Convert / Automate.
- Inclui as 2-3 palavras-chave mais centrais do projeto.
- Sem emoji, exclamação, adjetivos de marketing.
- Não escreva capacidades que não possam ser sustentadas pelos fatos do projeto.
Pontuação:
| Dimensão | Pontos | Julgamento |
|---|---|---|
| Precisão | 40 | Se é fiel à capacidade real do projeto |
| Valor de busca | 25 | Se cobre termos comuns de pesquisa no GitHub / Google |
| Capacidade de citação AI | 20 | Se pode ser compreendido diretamente por ChatGPT / Claude / Perplexity |
| Conter | 15 | Se não tem exagero ou palavras vazias |
Classificação por estrelas:
| Pontuação | Estrelas |
|---|---|
| 90-100 | 5 estrelas, recomendado usar |
| 80-89 | 4 estrelas, utilizável mas pode ser mais conciso |
| 70-79 | 3 estrelas, apenas como alternativa |
| < 70 | Não recomendado |
Regras de geração de Topics
Primeiro crie um pool de candidatos, depois filtre a recomendação final.
Fontes de candidatos:
- Tipo de projeto:
agent-skill,cli-tool,developer-tools,documentation - Tecnologia central:
nodejs,playwright,codex,image-generation - Área de aplicação:
readme,github-readme,open-source,portfolio - Tendências atuais: AI agent, image generation, developer tooling, documentation automation
- Palavras-chave que aparecem nos arquivos reais do projeto e na narrativa do README
Regras de filtro:
- Recomende 7-9, no máximo 10, a menos que o projeto realmente abranja vários domínios claros.
- Topic deve ser em minúsculas, apenas letras, números e hífen.
- Remova palavras muito genéricas:
software,tool,app,github,project,ai. - Remova palavras repetidas:
readmeegithub-readmepodem coexistir;open-sourceeopensourcemantenha apenas um. - Não adicione topic irreais apenas para seguir tendências.
Cada topic com classificação por estrelas e motivo:
| Estrelas | Significado |
|---|---|
| 5 estrelas | Fortemente relacionado, alto valor de busca, deve ser adicionado |
| 4 estrelas | Relacionado e com valor de descoberta, pode ser adicionado |
| 3 estrelas | Alguma relação, mas não central |
| 2 estrelas | Relação fraca, geralmente não recomendado |
| 1 estrela | Ruído, não adicionar |
Formato de saída:
Recomendação de GitHub Description:
1. ★★★★★ <description>
Motivo: ...
2. ★★★★☆ <description>
Motivo: ...
Recomendação final: <description>
Recomendação de GitHub Topics:
Adicionar:
- ★★★★★ github-readme — Descreve com precisão o propósito do projeto
- ★★★★★ agent-skill — Alinhado com a forma do projeto
- ★★★★☆ image-generation — Adicionar quando o projeto suportar Image Gen
Não recomendar adicionar:
- ★★☆☆☆ ai — Muito genérico, ruído na busca
- ★★☆☆☆ github — Muito genérico, não ajuda na categorização
Atualização opcional via gh CLI
Se o usuário tiver gh instalado, o diretório atual já for um repositório Git e for possível resolver o remote do GitHub, pode sugerir que o usuário permita que o Agent use gh repo edit para atualizar. Não atualize por conta própria; primeiro forneça o conteúdo a ser executado e aguarde a confirmação do usuário.
Verifique:
gh --version
git remote -v
Formato do comando sugerido:
gh repo edit OWNER/REPO \
--description "<final-description>" \
--add-topic topic-one \
--add-topic topic-two \
--add-topic topic-three
Se precisar substituir topics antigos, primeiro leia os topics atuais, depois remova apenas os itens explicitamente não recomendados:
gh repo view OWNER/REPO --json description,repositoryTopics
gh repo edit OWNER/REPO --remove-topic old-topic --add-topic new-topic
Observação: git não pode atualizar metadados do repositório
O comando git não pode modificar a Description ou Topics do repositório GitHub. Motivo: Description e Topics são metadados da plataforma GitHub, não configurações de commit, branch, tag ou remote do repositório Git.
git remote -v só pode ser usado para identificar OWNER/REPO, não para atualizar metadados.
Se não houver gh, apenas forneça os valores recomendados e peça ao usuário para atualizar na página do GitHub; não forneça comandos alternativos complexos.
Não salve essas recomendações no arquivo README; elas pertencem a sugestões operacionais para o usuário no momento da entrega.
Fase 6: Validação e entrega
Antes de entregar, valide:
node --version
npm run showcase
file assets/banner.webp assets/features.webp
git status --short
Se alterar o modelo ou imagem real, regenere o WebP e abra para verificar.
O relatório final deve dizer apenas:
- O que foi alterado.
- Qual foi o resultado.
- Quais validações foram executadas.
- Se ainda há pontos que precisam de decisão do usuário.
Não escreva detalhes de implementação e processos冗长 para o usuário.

