Communitygithub.com

shimo4228/readme-writer

Skill do Claude Code: escreve e melhora READMEs voltados para humanos — a única entrada canônica para humanos, busca e AI Overviews. Contraparte para superfície humana de llms-txt-writer. Lint estrutural determinístico + revisão holística de LLM sem pontuação (AKC ADR-0008 Code-LLM Layering).

O que é readme-writer?

Este skill do Claude Code foca na criação e melhoria de READMEs voltados para humanos, atuando como a superfície de entrada canônica única para projetos, complementar ao `llms-txt-writer` que cuida das superfícies para IA. Sua principal função é equilibrar a necessidade de um README visualmente atraente e conciso para humanos com a exigência de que o LLM (Large Language Model) consiga reconstruir o projeto lendo apenas esse README, o que é chamado de 'piso mínimo de leitura para LLM'. Para isso, o skill opera em duas camadas: uma verificação estrutural determinística (lint) feita por código, que checa elementos como número de headings e presença de alt text, e uma revisão semântica holística feita pelo próprio LLM, que avalia aspectos como clareza da proposta de valor e a capacidade de recuperação do projeto. O skill também emprega uma abordagem 'visual-first', priorizando diagramas Mermaid (que são legíveis por humanos e LLMs) sobre imagens raster, e impõe orçamento de comprimento baseado na realocação de informações profundas para documentos canônicos (como ADRs ou docs), evitando que o README se torne um `llms-full.txt` disfarçado. O resultado é um README que serve tanto como uma porta de entrada eficaz para humanos quanto como uma fonte confiável de informações para LLMs em grounding.

Funciona com✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

Perguntar na sua IA favorita

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

Documentação

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?"

PropriedadeExemploTipoProprietário
EstruturalNú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 H1structuralcódigo (readme_lint.py)
SemânticaSe 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 vaidadesemanticRevisã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):

  1. Frase de identidade (primeiras 1-2 frases, legíveis isoladamente): "X é uma {categoria} que faz {o quê} para {quem}"
  2. Problema resolvido / público-alvo / diferencial
  3. 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
  4. 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
  5. 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.txt disfarç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údoFormato IdealMotivo
3 etapas lineares / enumeração simplesprosa / lista / tabela pequenaLegí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 / complexoSVG commitado (com zoom/pan)/ subdivisão em subsistemasMermaid gigante atinge limite até em desktop e quebra em mobile
UI real / resultado de execução / fotoraster (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 (maxTextSize padrã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_lead verifica 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 H1
  • heading_levels — Não pular níveis de heading
  • alt_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ídos
  • badge_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.txt disfarç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.txt disfarç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/graph da 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 (possui geo_check.py baseado em pesquisa). Esta habilidade é a superfície humana.
  • when-code-when-llm — Eixo de julgamento structural / semantic
  • context-sync — Consistência de fatos / drift entre README ↔ camada mecânica (verificação de fatos delegada a este)
  • jsonld-knowledge-graph — Design de graph.jsonld
  • writing-ecosystem — Orquestrador de prosa longa para humanos
  • inspiration.md — Origem do design, proveniência de pesquisa primária, fontes de evidência externa (separado do corpo do SKILL.md para portabilidade)

Habilidades Relacionadas