Para nós, direto ao ponto. Para os agentes, tudo.

Hoje, agentes escrevem a maior parte das descrições dos meus pull requests, das respostas em revisões e das minhas issues. Eles escrevem bem, mas escrevem muito.

Ninguém lê uma descrição de pull request longa. Quem revisa passa os olhos nas primeiras linhas, rola a página e aprova, ou pergunta algo que o texto já respondia. Já o próximo agente que pegar a conversa quer tudo: o que mudou, por quê, o que foi testado e o que não foi.

Ou seja, todo texto tem dois leitores. Parei de tentar escrever para os dois no mesmo bloco.

Duas frases no topo, o resto recolhido

Todo texto que publico a partir de um agente agora tem o mesmo formato:

1. Um resumo de uma ou duas frases, para pessoas. As skills chamam isso de lead.
2. Um divisor.
3. O texto completo num bloco recolhido, para agentes ou para quem quiser ler tudo.
4. Um rodapé com o nome da skill que escreveu o texto.

No GitHub, o bloco é um elemento <details>. No Linear, um gerenciador de tarefas usado por muitos times de software, é um bloco >>>. Nos dois casos, quem revisa vê duas frases e uma caixa fechada.

Aqui vai um exemplo real, o meu pull request para a extensão do Homebrew no Raycast. O resumo diz o que mudou e o que revisar. As imagens de antes e depois ficam logo abaixo dele, e todo o resto fica recolhido.

Um detalhe: a ferramenta de linha de comando do GitHub só envia imagens para quem pode escrever no repositório. Quando você manda um pull request do seu fork para o projeto de outra pessoa, normalmente não pode. Então a skill publica a tabela com um aviso em cada célula de imagem e diz qual arquivo vai onde. Depois você cola as imagens no navegador, onde qualquer pessoa que contribui consegue adicioná-las.

Antes	Depois
📎 Cole dia-before.png aqui	📎 Cole dia-after.png aqui
dia mostra o AirMedia primeiro. O Dia fica umas três páginas abaixo.	dia mostra o Dia primeiro, depois os nomes que começam com "dia".

Alguns textos são tão curtos que um bloco recolhido só repetiria o que já está ali. A resposta a um comentário de revisão pode ter uma linha só: “Corrigido em b72e019. Pode revisar de novo.” Aí o agente publica só essa linha, sem divisor, sem bloco recolhido e sem rodapé.

As primeiras frases dizem o que fazer

O resumo diz duas coisas: o que mudou e o que o leitor precisa fazer, por exemplo “Dá uma olhada nos tempos de espera entre as tentativas.” ou “Confere a cor do erro no modo escuro.” Se não há nada a fazer, ele diz só o que mudou.

O agente escreve o resumo por último, depois dos detalhes. Escrito primeiro, ele vira uma introdução: “Este PR adiciona…”. Escrito por último, ele resume algo que já existe, e a ação fica fácil de ver.

A ideia de começar pela próxima ação vem da skill i-have-adhd. Funciona para quem tem TDAH e para quem não tem. Quem revisa com pressa tem o mesmo problema.

Os detalhes continuam completos

O bloco recolhido não resume nada. Se o repositório tem um template de pull request, o bloco segue esse template, título por título. Quem mantém o projeto escreveu o template para uma revisão cuidadosa, então ele continua lá. Só sai do caminho. Sem template, a skill usa os próprios títulos: Resumo, Por quê, Mudanças, Como foi testado e O que não foi testado (e por quê).

Assim, quem revisa tem dois caminhos. Para uma olhada rápida, o resumo e as capturas de tela bastam: o que mudou, como ficou e o que conferir. Para uma revisão cuidadosa, a pessoa abre o código e o bloco, e encontra o template que pediu, preenchido.

“O que não foi testado” é a parte mais importante. CI verde só prova o que o CI roda. Um agente que diz o que não verificou dá a quem revisa algo concreto para olhar. A skill inclui essa seção mesmo quando o template não pede.

Como as pessoas não abrem o bloco por padrão, ele pode ser tão longo quanto precisar. Ninguém precisa escolher entre um texto curto e um texto completo.

Aberto, o pull request do Homebrew segue o template do Raycast: Description e Screencast, e o checklist no final. Entre eles, a skill acrescentou How it was tested, com os comandos exatos e os resultados, e Not tested (and why).

Seus idiomas, na sua ordem

Nem todo mundo num time lê inglês com facilidade, e nem todo mundo escreve em inglês. Por isso, as skills escrevem nos seus idiomas: um idioma principal, que vem primeiro, e outros abaixo dele.

Na primeira vez que você roda uma delas, ela faz duas perguntas no idioma em que você escreve para o agente e salva as respostas como padrão:

Em qual idioma seus textos devem começar?

inglês

Adicionar outros idiomas abaixo dele?

sim: japonês

Depois disso, eu mudo para um texto só, com palavras comuns: “só inglês”, “japonês primeiro”, “use só português”. Quando o japonês vem primeiro, o original em inglês vem depois de 原文:, para quem lê saber qual texto vale.

Testei com a correção do Homebrew lá de cima. O pull request de verdade continua em inglês, para não atrapalhar o projeto open source em que eu estava contribuindo. No meu fork, abri a mesma mudança em inglês e japonês, e criei uma issue no Linear do mesmo jeito.

O texto no meu próprio idioma é escrito primeiro, e toda tradução parte do texto final. Uma tradução feita a partir de um rascunho se afasta da versão final.

Antes de publicar, um pequeno script verifica o texto. Em todos os idiomas, ele limita o tamanho das frases: 30 palavras, ou 80 caracteres em idiomas escritos sem espaços, como o japonês. No inglês, ele também procura travessões, contrações e palavras vagas como “should”, e confere as partes do formato: os resumos, o divisor, os blocos e o rodapé. Ele não consegue verificar o sentido, então a skill também pede ao agente que releia só o resumo. As regras de inglês partem das skills simple-english e unslop.

Uma skill, uma função

São quatro skills, e cada uma cuida de uma coisa:

• post cuida do texto: o formato, o idioma, o estilo e a verificação.
• github e linear cuidam da plataforma: a sintaxe e os comandos.
• create-pr cuida do fluxo do pull request: o intervalo exato de commits, as verificações, o título e as imagens de antes e depois logo abaixo do resumo. Para o texto, ela usa a post.

Quando o GitHub muda a forma de exibir alguma coisa, só a github muda. Quando quero um resumo melhor, só a post muda. Mais tarde, uma skill gitlab pode entrar ao lado da github, e uma jira ao lado da linear, sem mexer nas outras.

O rodapé diz qual skill rodou, por exemplo clins:create-pr. Quem gostar do resultado sabe o que rodar para ter o mesmo.

Experimente

A demo mostra o que cada skill escreve, com exemplos inventados no GitHub e no Linear, incluindo um pull request que alterna entre quatro pares de idiomas.

As skills são open source. Instale para qualquer agente de código com:

npx skills add clins1994/skills

Issues e pull requests são bem-vindos. O guia de contribuição lista alguns pontos de partida.