aelena/llms-txt

O que llms-txt faz?

Crie um arquivo llms.txt de alta qualidade na raiz de um repositório, seguindo o padrão proposto por llmstxt.org. O arquivo é um índice curado e legível por máquina do projeto — uma "tabela de conteúdos para LLMs" — que cabe confortavelmente na janela de contexto do modelo.

Por que isso existe

LLMs que leem um repositório às cegas precisam adivinhar o que é importante. llms.txt permite que um projeto diga a eles: aqui está o projeto, aqui está o resumo, aqui estão os documentos canônicos em ordem de prioridade, aqui estão os recursos secundários que podem ser ignorados se o contexto estiver apertado. É o robots.txt para a era dos modelos — exceto que ajuda o modelo a fazer seu trabalho melhor, não pior.

Invocação

Gatilho	Comportamento
/llms-txt ou /llms-txt-gen	Gera llms.txt na raiz do repositório
/llms-txt full	Também gera llms-full.txt (documentos completos concatenados, sem truncamento)
/llms-txt validate	Valida um llms.txt existente contra o padrão
/llms-txt update	Atualiza um llms.txt existente com o estado atual do repositório, preservando edições manuais
Linguagem natural: "crie um llms.txt", "torne este repositório amigável para LLMs", "gere o índice llm"	Mesmo

Parar / desabilitar

Não é realmente aplicável — este é um gerador único, não um modo de sessão. Apenas não o invoque.

Fluxo de execução

1. Descobrir candidatos. Execute scripts/discover.sh para enumerar:

   • Arquivos de metadados do projeto: README*, package.json, pyproject.toml, Cargo.toml, Gemfile, go.mod, etc.
   • Markdowns raiz: README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE, ARCHITECTURE.md, etc.
   • Conteúdo do diretório docs/ (.md, .mdx, .rst)
   • Outros markdowns em profundidade 2–3 (excluindo node_modules, .git, vendor)

2. Ler e sintetizar. Leia o README e o arquivo de metadados principal. Extraia:

   • Nome do projeto (de package.json:name, pyproject.toml:[project].name ou README H1)
   • Resumo de uma frase (do primeiro parágrafo do README ou package.json:description)
   • Contexto mais longo (1–2 parágrafos da introdução do README, sem cabeçalhos)

3. Categorizar candidatos em seções H2. Padrões razoáveis:

   • Docs — documentação primária voltada ao usuário
   • Examples — código de exemplo, tutoriais, guias rápidos
   • API Reference — documentação de API gerada ou escrita manualmente
   • Optional — recursos secundários (CHANGELOG, guias de contribuição, RFCs, notas internas)

   A seção ## Optional tem significado especial no padrão: LLMs com orçamentos de contexto apertados devem pulá-la. Coloque qualquer coisa não essencial lá.

4. Gerar llms.txt seguindo o formato em format.md. Estrutura estrita:

   # Nome do Projeto
   
   > Resumo de uma frase em um blockquote.
   
   Contexto opcional de 1-2 parágrafos, sem cabeçalhos.
   
   ## Seção
   - [Título](url relativa ou absoluta): descrição de uma linha
   - [Título](url): descrição
   
   ## Optional
   - [Título](url): descrição
   

5. Validar com scripts/validate.sh. Se houver erros, corrija e revalide.

6. Pré-visualizar o arquivo gerado para o usuário antes de escrevê-lo. Peça confirmação.

7. Escrever em ./llms.txt. Se o arquivo já existir, faça um diff e pergunte antes de sobrescrever — preserve quaisquer seções manuais que o usuário adicionou.

8. llms-full.txt opcional (apenas se o argumento full for fornecido): concatene o conteúdo completo de cada documento vinculado em um único arquivo, com cabeçalhos # File: <caminho> entre eles. Esta é a variante "me dê tudo".

Salvaguardas de segurança

• Nunca sobrescreva um llms.txt existente sem pré-visualização + confirmação. Ele pode conter curadoria manual.
• Nunca inclua segredos no arquivo gerado. Pule qualquer arquivo candidato que corresponda a .env*, *.pem, *key*, credentials*, *.secret. Avise o usuário se encontrado.
• Nunca vincule a caminhos privados (qualquer coisa dentro de .git/, node_modules/, vendor/, target/, build/, dist/).
• Não invente URLs. Todos os links devem apontar para arquivos reais no repositório (caminhos relativos) ou URLs explicitamente presentes no README. Não adivinhe a página inicial do projeto.
• Respeite .gitignore. Se um arquivo candidato estiver no gitignore, não o indexe.

Regras de estilo para o arquivo gerado

• H1 é o nome do projeto, nada mais. Não um slogan, não uma tagline.
• O resumo no blockquote é uma frase, presente, factual. Sem linguagem de marketing.
• Descrições em itens de link são uma linha, ~12 palavras no máximo. Diga ao LLM por que este arquivo importa, não o que ele diz literalmente.
• A ordem importa dentro de uma seção — o mais importante primeiro. O modelo pode parar de ler no meio.
• Sem emojis, sem markdown decorativo, sem listas aninhadas. O formato é intencionalmente plano.
• Prefira caminhos relativos para arquivos no repositório (docs/getting-started.md), URLs absolutas apenas para recursos externos.

Arquivos neste skill

• SKILL.md — este arquivo
• format.md — a referência de formato llmstxt.org, destilada
• scripts/discover.sh — enumera arquivos candidatos para indexação
• scripts/validate.sh — valida um llms.txt gerado contra o básico do padrão