Agent skills para planejar, entregar e publicar com agentes

Uma skill é uma pasta com um SKILL.md. O frontmatter tem name e description, e o corpo tem as instruções que o agente carrega quando a tarefa combina com a descrição. Juntei as minhas no repositório pedrosatin/skills, e elas funcionam no Claude Code, no Codex, no Gemini CLI, no OpenCode e no Cursor.

Como o agente decide usar uma skill

O agente lê só o name e a description de todas as skills instaladas. O corpo entra no contexto quando a descrição combina com o pedido. Por isso a descrição precisa dizer o que a skill faz e quando usá-la, em poucas linhas. Uma descrição longa gasta contexto em toda conversa, mesmo quando a skill não é usada.

Algumas skills só rodam quando eu digito o comando. Elas tem disable-model-invocation: true no frontmatter: setup, board, to-spec, to-tickets, pr-loop, babysit-prs, teach e show-me. O agente não as aciona por conta própria, porque pr-loop e babysit-prs mesclam PRs e não devem rodar por uma frase solta como “revisa essas PRs”.

Instalação

Há dois caminhos:

# skills.sh instala em todos os agentes configurados
npx skills add pedrosatin/skills

# ou symlinks a partir de um clone
git clone https://github.com/pedrosatin/skills.git
./skills/link.sh

O link.sh cria ~/.agents/skills/<nome>, que aponta para cada pasta de skills/. Em sessão interativa, ele detecta os outros harnesses instalados (Claude Code, Codex e Gemini) e pergunta se deve criar os links neles também. ./link.sh --all liga todos os detectados sem perguntar, e ./link.sh -y roda sem interação, no modo padrão. Ele pula diretórios que já existem e links que apontam para fora do repositório. Rodar de novo depois de um git pull é seguro, e o script remove links quebrados.

O OpenCode lê ~/.agents/skills direto. Claude Code, Codex e Gemini leem pelos symlinks que o script cria na pasta de skills de cada um.

O fluxo de planejamento

Começo pelo /setup, que roda uma vez por projeto, e depois sigo a ordem abaixo quando começo uma funcionalidade.

/setup prepara o projeto. Cria .scratch/ e os documentos em docs/agents/, adiciona um bloco ao AGENTS.md (ou CLAUDE.md), confere o graphify e gera o Project Hub, um .scratch/index.html com o quadro de tarefas. Ele pede confirmação antes de gravar.

grilling faz o agente me interrogar sobre o plano. As perguntas vêm em rodadas pela interface de perguntas do próprio agente (AskUserQuestion no Claude Code), então respondo escolhendo opções. Cada rodada só traz decisões cujos pré-requisitos já foram resolvidos. Termina quando não sobra nenhuma ramificação em aberto. No fechamento, grava os termos combinados no GLOSSARY.md e confirma comigo, pela mesma interface, cada decisão que merece um ADR.

/to-spec transforma a conversa em uma especificação. Sintetiza o que já foi decidido, sem entrevistar. Se o fechamento do grilling ficou para trás, primeiro grava no disco os termos e os ADRs que a conversa já decidiu. Antes de escrever, propõe as fronteiras de teste. São as superfícies externas em que o comportamento será observado. O arquivo vai para .scratch/<funcionalidade>/spec.md.

/to-tickets quebra a spec em fatias verticais. Cada ticket atravessa todas as camadas (schema, API, interface, testes), pode ser verificado sozinho e cabe numa janela de contexto limpa. Cada um declara os tickets que o bloqueiam. O resultado é um arquivo por ticket em .scratch/<funcionalidade>/issues/. O agente me mostra a divisão e só publica depois que eu aprovo.

/board abre o Project Hub no navegador. Se o quadro ainda não existe, o script sugere rodar /setup primeiro.

O fluxo de entrega

/pr-loop executa os itens do backlog um por vez. Para cada item, um subagent implementa em um worktree isolado e cria um commit local. Em seguida o agente principal roda o clean-crap sobre o diff e testa o comportamento do produto. Ele percorre o fluxo na interface, roda o comando do CLI ou chama a API. Quando a mudança é visual, guarda capturas de antes e depois. Com esse resultado ele escreve o rascunho da descrição da PR. Um segundo subagent revisa o código e a prosa em modo somente leitura, e um terceiro aplica as correções. Depois da correção, o agente principal testa o produto de novo e atualiza o rascunho.

Push, PR e merge ficam com o agente principal, que tem a conversa inteira e a minha autorização. Pedir o loop autoriza o trabalho até abrir a PR. Cada merge precisa de um sim meu, a não ser que eu tenha aprovado o lote antes, com algo como “mescla tudo”.

Foi assim que fechei a PR que encurtou as descrições das próprias skills. O loop rodou os passos, a revisão pediu para restaurar um gatilho e deixar explícita a autorização do merge, e só mesclei depois de responder que sim.

clean-crap mede a complexidade de cada função JavaScript e TypeScript, cruza com a cobertura do LCOV e calcula o CRAP. Quando alguma função passa do limite, o pr-loop manda um subagent quebrar a função ou cobrir os ramos sem teste antes da revisão. São no máximo duas rodadas de correção. Na terceira falha, a decisão volta para mim.

pr-description escreve a descrição da PR a partir do diff e das verificações que rodaram de fato. No modo rascunho, grava só um arquivo local. No modo publicação, cria a PR ou edita a que já existe para a branch, com as capturas anexadas como evidência.

/babysit-prs revisa todas as PRs abertas do repositório, mescla as seguras e deixa as arriscadas como rascunho, com comentário.

/show-me desenha esboços, árvores de chamada e diagramas curtos para a pergunta do momento. A pr-description usa as mesmas referências visuais quando a PR pede um diagrama.

Regras que valem em todo commit

publication-hygiene roda antes de qualquer commit, push ou ação em PR. Confere título, corpo, trailers, autoria e arquivos novos. Remove o que denuncia a ferramenta usada, como trailers de coautor, rodapés automáticos, URLs de sessão e arquivos de plano. Autor e committer continuam sendo eu.

unslop-br revisa texto em português. Corta gerundismo de cauda, travessão, adjetivos inflados e a construção “não é X, é Y”. Rodo essa skill em PRs, READMEs e posts antes de publicar.

validate-agent-config confere as minhas configurações de agente. Verifica arquivos de instrução, symlinks, imports com @ e o frontmatter das skills. O script sai com código 1 quando encontra erro.

writing-for-agents é uma rubrica para documentos que um agente lê, como skills, AGENTS.md e CLAUDE.md. Uso quando crio ou edito uma skill.

O que veio de outros repositórios

Parte do conjunto é de terceiros e mantém a licença original, listada no ATTRIBUTION.md. grilling, to-spec, to-tickets, research, teach e writing-for-agents vêm das skills do Matt Pocock. archify vem de tt-a1i/archify, graphify de Graphify-Labs/graphify, humanizer de blader/humanizer e show-me de humanlayer/skills. As minhas, sob MIT, são unslop-br, publication-hygiene, pr-description, babysit-prs, pr-loop, clean-crap, validate-agent-config, setup e board. A pr-description adapta a skill pr do Matt Pocock.

As instruções estão em inglês, com exceção do unslop-br, cujas regras e exemplos são de português. Alguns gatilhos e a interface do Project Hub também estão em português. O agente responde no idioma da conversa.

Como começar

Instale, abra um projeto e digite /setup. Depois descreva uma funcionalidade e peça para o agente fazer o grilling. Quando as decisões estiverem fechadas, rode /to-spec, /to-tickets e /board para ver o quadro. Com os tickets prontos, /pr-loop entrega um por vez, e cada PR já sai com a descrição e as evidências do que foi testado.

Repositório · skills.sh