readme-writer — Habilidade de README Focado em Humanos
Habilidade para escrever e melhorar READMEs voltados para humanos. Enquanto llms-txt-writer cuida da superfície dedicada à IA, esta habilidade assume a entrada canônica única para a superfície humana.
Adicionalmente, um fato importante: O README é a única superfície que o LLM pode assumir com segurança como base por meio da rota de grounding (colar URL do repo em pesquisa / chat). Portanto, o README deve ser "curto e visual para humanos", mas ao mesmo tempo deixar um pequeno piso de informações que permita ao LLM reconstruir o projeto mesmo lendo apenas o README — conciliar esses dois aspectos é o desafio central desta habilidade.
Quando Usar
- Criar ou melhorar README.md / README.ja.md
- Preparar a "página de aterrissagem inicial para humanos" de um repo / projeto
- Corrigir READMEs existentes que estão "mecânicos demais e incompletos para humanos" ou "tão superficiais para humanos que o LLM não consegue entender"
- Quando quiser um README curto e com foco visual, mas sem perder o piso de informações
Quando NÃO Usar:
- Documentos dedicados à IA como
llms.txt/llms-full.txt/ FAQ (→llms-txt-writer) - Prosa longa como artigos, ensaios, blogs (→
writing-ecosystem) - Design de graph.jsonld (→
jsonld-knowledge-graph)
O Eixo é "ATENÇÃO Humana × INFORMAÇÃO do LLM"
O verdadeiro eixo de oposição na otimização de README não é "informação para humanos vs. informação para LLM". É Atenção humana (curto, cativante, escaneável) × Informação do LLM (recuperável só com o README). Ambos convergem para as mesmas ações (descritas abaixo), então não é um trade-off, mas sim um design que captura ambos.
README é a única superfície lida com certeza (mas não é "única")
- Crawlers de busca / citação de IA na prática não leem llms.txt (vários logs de 2026 mostram zero requisições na maioria, e os principais vendors de busca declararam oficialmente não suporte).
graph.jsonldé tratado como texto simples em fetches diretos e não substitui os fatos do README (experimento controlado).- Portanto, não se deve esvaziar as informações do README sob o pretexto de que "a camada mecânica serve como backstop".
No entanto, uma calibração importante: "O LLM só lê o README" é forte demais. O correto é: "Em grounding genérico de paste-URL / busca, o README é a única superfície que se pode assumir com segurança". Outras rotas existem (índice de busca já chunkou outros arquivos / rastreamento de links do README / exposição de árvore de arquivos via GitHub connector ou API / conhecimento de pretraining). A conclusão mais forte é para grounding anônimo de live web e landing fetch direto. Por outro lado, coding agents roteados (Claude Code, Cursor, etc.) leem llms.txt on-demand, então llms.txt continua sendo um seguro para canais agentic — mas não é a porta de entrada para busca de IA.
Por que Separar "Lint Estrutural" de "Revisão Holística"
A qualidade de um README mistura dois tipos de propriedade. De acordo com Code-LLM Layering (estrutura é propriedade 100% precisa do código, significado é propriedade do LLM), os proprietários são separados. O eixo de julgamento é when-code-when-llm: "O mesmo byte pode ter significados diferentes em contextos diferentes?"
| Propriedade | Exemplo | Tipo | Proprietário |
|---|---|---|---|
| Estrutural | Número de H1s / níveis de heading / presença de alt-text / resolução de links locais / nomes de arquivos raster / número de badges / DOI dentro de details / linhas de prosa logo após H1 | structural | código (readme_lint.py) |
| Semântica | Se o lead cativa uma pessoa / clareza da proposta de valor / se o LLM consegue reconstruir o projeto só com o README / fluxo narrativo / se badges são vaidade | semantic | Revisão holística do LLM |
Não se cria uma pontuação numérica baseada em pesquisa para READMEs. As proporções de seção de llms.txt (ski-ramp, etc.) são sinais determinísticos validados por pesquisa de citação de LLM, mas "se um README é uma boa entrada" é um julgamento semântico e não há descobertas determinísticas equivalentes. Trazer métricas de superfície de IA (como densidade de entidades) para READMEs humanos é um anti-pattern.
No Entanto, "Legibilidade Estrutural para IA" é Ativamente Adotada (Regra dos Dois Lados)
"Não trazer métricas de superfície de IA" é apenas metade. O princípio é: "Como a ideia é transmitida pode ser otimizado (sem limite de intensidade). O que a ideia é nunca deve ser distorcido."**
- Adotado (sem limite de intensidade): Hierarquia de headings, design de informação, ancoragem de entidades (nome do autor / ORCID / DOI / identificadores canônicos escritos na prosa), ancoragem de vocabulário próprio/cunhado, lead do tipo answer-first, tabela de relance. Estes funcionam tanto para humanos quanto para LLMs na rota de grounding — zona de convergência.
- Proibido: keyword stuffing, atributos inflados, farming de perguntas como headings, glossário descartado, distorção de afirmações para se adequar a funções de recompensa de recuperação. Citações e estrelas não são métricas de sucesso, então não há objetivo a que a distorção sirva.
Piso Mínimo de Leitura do LLM (Pequeno, Inegociável, Sem Inchaço)
Regra: Supondo que o LLM leia apenas o README (sem llms.txt nem graph), ele deve ser capaz de reconstruir o projeto apenas com texto.
Elementos do piso (em prosa / markdown / Mermaid. Apenas imagens, apenas dentro de details, apenas links de destino NÃO são aceitos):
- Frase de identidade (primeiras 1-2 frases, legíveis isoladamente): "X é uma {categoria} que faz {o quê} para {quem}"
- Problema resolvido / público-alvo / diferencial
- Fatos canônicos: nome real, linguagem/stack/status. Repos de pesquisa/DOI: DOI + how-to-cite (BibTeX / CITATION) + definição de 3-6 conceitos centrais que sustentam o vocabulário
- Apenas um exemplo concreto: se for código, assinatura de função + trecho mínimo executável (não colocar implementação completa — causa inchaço + alucinação) / se for pesquisa, afirmação central + 2-3 números-chave
- Mapa de links para documentação profunda: apenas ponteiros. Não colocar fatos estruturais apenas em links / llms.txt / graph
Armadilha mais importante: O piso é um pequeno núcleo inegociável. Se a regra "não corte, reestruture" for aplicada com força excessiva, informações podem ficar acumuladas em Mermaid / details / seção de piso, fazendo o README inchar como um
llms-full.txtdisfarçado. O objetivo humano era curto. Corte ou realoque tudo que não for piso (→ orçamento de comprimento).
Ao gerar graph.jsonld / llms.txt a partir do README, não usar a prosa do README como fonte estrutural. Identificadores e arestas do graph devem ser derivados de CITATION.cff / .zenodo.json / um pequeno manifesto no frontmatter (cópias paralelas manuais geram drift).
As superfícies de metadados do GitHub (descrição do repo / topics / social-preview / arquivo CITATION / release / metadados de pacote) também são parte do piso que afeta o grounding. Não são configuradas no corpo do README (são da alçada de gh repo edit / release-doi), mas devem ser verificadas como checklist.
Visual-First (Mermaid em Primeiro Lugar, Raster por Último)
A interpretação correta de "curto e visual" não é "transformar prosa em imagem", mas sim "comprimir o muro de prosa em uma estrutura escaneável". E "Mermaid em primeiro lugar" ≠ "tudo vira Mermaid" — primeiro, decida se deve ser um diagrama. Escolha formatos que não quebrem em mobile (largura estreita) e que o LLM consiga capturar.
Escolha de Formato
| Conteúdo | Formato Ideal | Motivo |
|---|---|---|
| 3 etapas lineares / enumeração simples | prosa / lista / tabela pequena | Legível em todos os dispositivos (especialmente mobile). Não vale a pena fazer diagrama |
| Formato realmente de graph (relações, múltiplos ramos, matriz) | Mermaid (TD vertical) | Fonte é texto, LLM também lê. Scroll vertical é natural em smartphones, horizontal (LR) quebra |
| Diagrama grande / complexo | SVG commitado (com zoom/pan)/ subdivisão em subsistemas | Mermaid gigante atinge limite até em desktop e quebra em mobile |
| UI real / resultado de execução / foto | raster (PNG/JPG/WebP/GIF) | Apenas o que Mermaid não consegue representar |
Todo diagrama deve ter obrigatoriamente um equivalente textual de pelo menos uma frase (regra dura). Isso garante que chegue tanto a humanos quanto a LLMs: salva humanos em mobile onde o diagrama quebrou, extratores de LLM que pulam fences de mermaid como código opaco, e leitores de tela. O diagrama é um bônus visual acima disso, não o único portador da informação.
Pontos-chave do Mermaid
- GitHub renderiza nativamente como SVG com theme-aware. A fonte é texto (diffável, ~10 tokens/aresta) e legível por crawlers text-only que não veem pixels. Estruturas enterradas em prosa/graph (matriz de conceitos, binding de fases, estágios de pipeline) se tornam Mermaid: ficam mais curtas e com maior densidade de informação.
- Mobile-first: use
TD(vertical).LR(horizontal) tende a quebrar em larguras estreitas. - Limite de renderização é baseado em caracteres (
maxTextSizepadrão 50.000) + arestas, não em número de nós ("limite de 50-100 nós" é lenda urbana). Se estiver perto, divida em subsistemas. Projetos especiais README não são renderizados. - Extratores podem descartar Mermaid, então o equivalente textual acima garante o significado separadamente.
Raster / Outros
- Raster não deve carregar informações estruturais. Alt-text é obrigatório (piso duro: a rota de texto só lê alt — imagem sem alt é invisível para o LLM. Não é só uma questão de acessibilidade).
- Dark/light: usar
<picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>.<img alt>é duplamente estrutural. - Assets de imagem devem ser commitados no repo com caminho relativo. Evitar hotlinks externos (quebra de camo) e
<svg>/<embed>/<object>inline ou animados (GitHub sanitiza). - Badges: apenas 2-4 de alto sinal (CI / version / license / para repos de pesquisa: DOI). Evitar badges de vaidade. Limitar número para não acumular fileiras em largura estreita.
- Repos CLI: usar asciinema → agg GIF + legenda de uma frase. Repos UI: screenshot/GIF + alt-text.
Diagramas bespoke raros podem ser gerados como SVGs commitáveis via Claude Artifacts / Claude Code svg ou diagram skill e colocados em
assets/.
Orçamento de Comprimento (Sem Meta de Palavras)
Não estabelecer meta de palavras ("ponto ideal de 500-1500 palavras", "README visual aumenta estrelas (pesquisa GitHub)" são ambas descartadas como fabricadas/sem fonte). Em vez disso:
- Above-the-fold (primeira tela = 30 segundos para decidir "é para mim?"): hero opcional → H1 → tagline de uma linha (proposta de valor = linha mais seguramente extraída pelo LLM) → ≤4 badges funcionais → fatos do piso → quick start copy-paste. Racional profundo vem depois.
- Ordem varia com o tipo de repo: "quickstart → rationale" é para software. Para artigos / datasets / conceitos / repos de ensaio DOI, não se aplica. Não force ordem fixa; apenas garanta que "identidade + fatos canônicos vêm antes do racional profundo". O lint
identity_leadverifica estruturalmente apenas a existência de uma frase de lead, não força ordem. - O volume total depende de uma variável: se o site de documentação canônica / ADRs absorvem o conteúdo profundo. Mova o "porquê" profundo / racional de design para ADRs /
docs//llms-full.txt/ paper depositado, deixando no README apenas um ponteiro de uma linha (deslocamento de explicação do Diátaxis). Isso é o tratamento direto para "README de repo de pesquisa com 450 linhas". <details>é apenas para conteúdo secundário a granel (tabela de opções / FAQ / troubleshooting / glossário completo). Organiza a visão humana enquanto ainda é legível pelo LLM. Mas não colocar o piso lá (perda de primazia + não encontrável com Ctrl+F. Rotas raw-markdown leem, mas sumarizadores de páginas renderizadas podem despriorizar o recolhido).
Workflow (Filtro de Código → Revisão LLM → Gate Humano)
1. Filtro de Código — readme_lint.py (Determinístico, Apenas Estrutural)
uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"
Argumento é o caminho absoluto do README. --json para saída legível por máquina. Código de saída gate de propriedade do código (0=limpo ou apenas warnings / 1=erro de severidade presente / 2=não encontrado ou grande demais).
Itens de verificação (não são pontuações, são issues específicas. Severidade em 2 níveis):
erro (derruba o gate, estrutura dura)
single_h1— Exatamente 1 H1heading_levels— Não pular níveis de headingalt_text— Todas as imagens têm alt (piso duro: sem alt = invisível para LLM)local_link— Links relativos locais / src de imagens existem
warning (conselho, não derruba o gate) — Detecta estruturalmente, mas "se é realmente um problema" é julgamento, então apenas a superfície. Julgamento semântico delegado à revisão LLM:
raster_diagram_hint— Nome de arquivo raster sugestivo de diagrama (architecture/flow/diagram/pipeline .png/.jpg/.webp/.gif) → sugere Mermaid. SVG, screenshot, logo são excluídosbadge_budget— Muitos badges (padrão >6). Apenas quantidade (se é vaidade ou não, é LLM)details_floor_leak— Dentro de<details>: tokens de DOI / BibTeX / CITATION (indício de vazamento do piso. "Se é realmente piso" é julgamento LLM)identity_lead— Sem frase de lead em prosa entre H1 e a primeira seção (não força ordem. Ausência de H1 é tratado por single_h1)doi_citation_pairing— Tem DOI mas não tem how-to-cite (seção de Citação / BibTeX / CITATION.cff) (não força DOI em repos não-pesquisa — só dispara quando DOI existe)
2. Revisão Holística do LLM (Rubrica como Lente, Sem Pontuação, Foco no Sinal)
Após o lint passar, o Claude lê o README holisticamente e produz achados concretos + diffs concretos com as seguintes lentes:
- 🚀 Recuperação só com o README (carro-chefe, maior alavancagem) — Lendo apenas o texto do README, verifica se consegue recuperar (identidade / público-alvo / problema / diferencial / se aplicável: DOI e citação / 3-6 conceitos centrais / 1 exemplo / link para o próximo passo). Lista especificamente o que falta (ex: "Público-alvo não está escrito"). Sem pontuação. Esta é a operacionalização do piso mínimo de leitura do LLM.
- O Quê / Quem / Porquê do Lead — A primeira tela deixa claro "o que é, para quem, por que se importar"
- Gancho Humano / Proposta de Valor — O valor é expresso em termos concretos, não abstratos
- Narrativa / Escaneabilidade — Parágrafos, headings, listas, Mermaid são acompanháveis por humanos
- Verificação de Concisão (Verificação Inversa Mais Importante) — Conteúdo não-piso foi realocado? Informações acumuladas em Mermaid / details / piso inchando como
llms-full.txtdisfarçado? - Adequação Visual — Diagrama é Mermaid? (Se raster: possível Mermaid? Tem equivalente textual?) Badges são de alto sinal? (Não são vaidade?)
- Consistência de Fatos — Afirmações não contradizem a camada mecânica (llms.txt / graph.jsonld)? → Delegado a
context-sync
Motivo para não dar pontuação (sinal-primeiro + dissolução de scaffold): Apenas fornecer "informação que muda a próxima ação". Lead: 6/10 não muda ação. "Lead não diz para quem é" muda ação. Saída em formato diff, granularidade que permite aprovação sim/não. Para separação autor-revisor, é desejável que a revisão seja executada em um processo de agente diferente do implementador (mesmo padrão de editor / essay-reviewer).
3. Verificação de Consistência de Fatos → context-sync
A verificação se os fatos do README são consistentes com llms.txt / llms-full.txt / graph.jsonld (evitar cloaking) é de responsabilidade do context-sync. Esta habilidade não reimplementa isso.
4. Gate Humano
Humano aprova o diff e aplica.
O Que Esta Habilidade NÃO Faz (Limites)
- Não escreve
llms.txt/llms-full.txt(→llms-txt-writer) - Não projeta
graph.jsonld(→jsonld-knowledge-graph) - Não faz detecção/sincronização de drift entre superfícies (→
context-sync/release-doi) - Não edita artigos / ensaios (→
writing-ecosystem) - Não configura description / topics / social-preview do repo (alçada de
gh repo edit/release-doi. Esta habilidade apenas os apresenta como checklist) - Não produz pontuação / nota / grade de qualidade
Anti-patterns
- Dar apenas pontuação numérica sem propostas concretas (armadilha de tipo recomendador)
- Fazer o LLM julgar itens que são puramente estruturais, ou substituir julgamentos semânticos por regex (ver
when-code-when-llm) - Trazer métricas numéricas de superfície de IA (ski-ramp / densidade de entidades / farming de headings interrogativos) para READMEs humanos (reduz legibilidade)
- Interpretar "prioridade visual" como transformar prosa em imagem (diagramas raster são invisíveis para LLM text-only = esconder informações do agente. Usar Mermaid)
- Aplicar "não corte, reestruture" com força excessiva, criando um
llms-full.txtdisfarçado (piso é pequeno, acima dele corte/realoque sem piedade) - Esvaziar o piso do README assumindo que a camada mecânica (llms.txt/graph) serve de backstop (não é lida na rota de grounding)
- Derivar
llms.txt/graphda prosa do README (drift. Derivar de manifest) - Adicionar fatos para humanos / apelos de monetização (danifica autenticidade + contradiz camada mecânica = cloaking. Pode mudar a embalagem, mas não a afirmação)
Verificação
cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing
fixtures/sample_clean.md (exemplo de boas práticas com 0 issues, usando diagramas Mermaid) e fixtures/sample_issues.md (exemplo que dispara todas as 9 verificações) podem ser usados para confirmar o comportamento básico.
Relacionados
llms-txt-writer— O writer da superfície de IA correspondente (possuigeo_check.pybaseado em pesquisa). Esta habilidade é a superfície humana.when-code-when-llm— Eixo de julgamento structural / semanticcontext-sync— Consistência de fatos / drift entre README ↔ camada mecânica (verificação de fatos delegada a este)jsonld-knowledge-graph— Design de graph.jsonldwriting-ecosystem— Orquestrador de prosa longa para humanosinspiration.md— Origem do design, proveniência de pesquisa primária, fontes de evidência externa (separado do corpo do SKILL.md para portabilidade)