Esse fluxo não é invenção minha. Ele vem de um conjunto de skills escrito pelo Matt Pocock, e este acervo inteiro é construído com ele. A demonstração deste artigo é o próprio blog que você está lendo: ele nasceu por esse caminho, e a spec, os tickets e os pull requests estão abertos no GitHub.

Uma skill é uma pasta com instruções​

Mecanicamente, uma skill é uma pasta com um arquivo SKILL.md dentro. O front matter carrega name e description, e o corpo é prosa que o agente passa a seguir quando a skill entra em jogo. Algumas trazem arquivos irmãos que o corpo aponta e o agente só abre quando precisa, como o tests.md e o mocking.md da tdd.

Você invoca uma skill digitando /nome. E vale entender uma distinção que o conjunto leva a sério: nem toda skill pode ser invocada pelo agente.

Onze das vinte e cinco não têm restrição, e o agente alcança sozinho quando a situação pede. São as que funcionam como referência viva, como a grilling, a tdd e a code-review.

As outras catorze carregam disable-model-invocation: true no front matter, e só rodam se você digitar: to-spec, to-tickets, implement, triage, wayfinder e handoff estão todas nessa lista. Não é detalhe de configuração, é a arquitetura da coisa. Publicar uma spec, cortar tickets e abrir um pull request têm consequência fora da conversa, e o conjunto decidiu que começam por uma tecla sua.

O que o agente apura, e o que você decide​

A divisão de trabalho está escrita na grilling, e é a frase que mais mudou o meu jeito de trabalhar:

Finding facts is your job, never the user's. [...] The decisions are the user's.

Traduzindo: o agente nunca deve perguntar quantos registros o índice de busca tem ou se o plugin aceita determinada opção. Ele vai lá e mede, despachando um subagente quando o fato está longe. O que ele pergunta é o que só você pode responder, e pergunta com uma recomendação em cima.

A segunda peça é onde a decisão fica guardada. Uma conversa some quando a janela de contexto fecha. Uma issue não. Por isso quase toda skill lê ou escreve no issue tracker, e é ele, não o histórico do chat, que funciona como memória do trabalho.

A instalação e o setup, uma vez por repositório​

Instalar é pôr as pastas onde o agente procura por skill. Aqui elas estão em ~/.claude/skills/, a pasta do usuário, então valem em qualquer repositório da máquina. A própria setup-matt-pocock-skills conta com isso: ela decide se pula a pergunta dos labels checando se existe uma pasta triage ao lado da dela.

O setup roda uma vez por repositório, e não é um script determinístico: explora, apresenta o que achou, confirma com você e só então escreve.

A exploração é conhecida: git remote -v, a existência de AGENTS.md e CLAUDE.md, um CONTEXT.md na raiz, docs/adr/, e sinais de monorepo. Depois vêm até três perguntas, cada uma já com a resposta recomendada na frente. A skill pula a que a exploração já resolveu:

1. Onde as issues vivem

   GitHub pela CLI gh, GitLab pela glab, markdown local em .scratch/, ou um tracker descrito por você em um parágrafo.

2. O vocabulário de triagem

   Os cinco papéis canônicos são needs-triage, needs-info, ready-for-agent, ready-for-human e wontfix. Você mantém os nomes ou mapeia para os labels do seu tracker.

3. Onde a documentação de domínio mora

   Contexto único, com um CONTEXT.md e docs/adr/ na raiz, é o padrão. Multi-contexto só entra em jogo se a exploração achou monorepo.

No fim ela escreve docs/agents/issue-tracker.md, docs/agents/domain.md e docs/agents/triage-labels.md, mais um bloco ## Agent skills no CLAUDE.md ou no AGENTS.md, o que já existir.

Aqui as respostas foram GitHub pela gh, vocabulário canônico sem apelido nenhum, e contexto único. É por isso que um agente que chega neste repositório sabe, sem perguntar, o que "publicar no issue tracker" quer dizer. O arquivo sai do modelo que a própria skill carrega, um por tracker:

gh issue create --title "..." --body "..."

glab issue create --title "..." --description "..."

O arquivo é seu depois de escrito: aqui o corpo multi-linha passou a ir por --body-file, no lugar do heredoc do modelo.

O pipeline, etapa a etapa​

O caminho que quase todo trabalho percorre tem seis paradas. A demonstração é real: cada link abre o artefato correspondente deste repositório.

1. Grilling: a conversa que fecha as decisões

   Duas portas levam ao mesmo lugar. /grill-with-docs roda junto com a domain-modeling e deixa rastro no glossário e nos ADRs; /grill-me é a mesma entrevista sem rastro.

   Ela acontece em rodadas. O agente monta uma árvore de decisões e pergunta de uma vez toda a fronteira, as decisões cujos pré-requisitos já estão resolvidos. Cada pergunta sai numerada, com a recomendação do agente logo abaixo:

   ❓ **Q1** - **<título da pergunta>**: <corpo da pergunta>
   
   ➡️ <a resposta que o agente recomenda>
   

   Isso muda a sua participação: você não escreve a decisão, ratifica ou veta. Dá para responder uma rodada inteira com "sigo as recomendações, exceto a 3 e a 15". A sessão termina quando a fronteira esvazia, e o agente não age até você confirmar.

2. /to-spec: a conversa vira uma issue

   A to-spec não entrevista ninguém: ela sintetiza o que já está na conversa. Antes de escrever, esboça as costuras onde a feature vai ser testada, prefere costura existente a costura nova, e confere com você.

   A spec sai num formato fixo, de Problem Statement a Further Notes, e é publicada como issue com o label ready-for-agent. As decisões de implementação não citam caminho de arquivo nem trecho de código, porque esses envelhecem rápido.

   A spec deste blog é a issue O Blog nasce como quinta aba, e não é uma instância de docs, com dezessete subdecisões numeradas, uma por pergunta que a rodada de grilling fechou. A da landing deste site, já encerrada, é a issue A landing volta, e a raiz deixa de ser um salto.

3. /to-tickets: a spec vira fatias verticais

   Uma spec inteira não cabe numa sessão. A to-tickets corta em tracer bullets: cada fatia atravessa todas as camadas, é demonstrável sozinha, e cabe numa janela de contexto nova. Fatia horizontal, de uma camada só, é o que ela evita.

   Cada ticket declara as arestas de bloqueio. A skill mostra a proposta numerada, pergunta se a granularidade e as arestas estão certas, e itera até você aprovar. Só então publica, em ordem de dependência. Aqui a fronteira aparece na interface do GitHub sem convenção de texto nenhuma.

   Foi assim que a spec do blog virou quatro tickets: o blog nasce, sem bloqueio, e depois as páginas próprias, busca e llms.txt e este artigo que você está lendo, os três bloqueados apenas pelo primeiro.

   Ligar as arestas é um segundo passe, por um motivo mecânico: uma issue precisa existir para ser referenciada. A to-tickets só manda usar a relação nativa do tracker; quem carrega o comando é o arquivo que o setup escreveu, e ele pede o id interno da issue, nunca o número:

   gh api --method POST \
     repos/<owner>/<repo>/issues/<filho>/dependencies/blocked_by \
     -F issue_id=<id-do-bloqueador>
   

4. /implement: o ticket vira código

   O arquivo da implement tem quinze linhas, e cabe nelas o ciclo inteiro. Implemente o que o ticket descreve, use /tdd nas costuras já combinadas, rode a checagem de tipos com frequência e a suíte inteira no fim, chame /code-review e faça o commit.

   A tdd que ela dirige tem três regras de laço: vermelho antes de verde, uma fatia por vez, e refatoração pertence à revisão. E uma que vale ler devagar: nenhum teste é escrito numa costura que você não combinou antes. É o que faz o esforço cair no caminho crítico em vez de cair em toda borda.

   O resto é convenção deste repositório, não da skill: worktree antes da primeira edição, npm run build antes do primeiro push, pull request em rascunho e merge automático no verde.

5. /code-review: dois eixos que não se contaminam

   A revisão roda contra um ponto fixo que você escolhe e dispara dois subagentes em paralelo.

   O eixo Standards pergunta se o código segue os padrões documentados do repositório, mais uma linha de base de doze cheiros do Fowler, tratados como julgamento e nunca como violação dura.

   O eixo Spec pergunta outra coisa: o diff faz o que a issue de origem pediu? Ele procura requisito faltando, comportamento que ninguém pediu, e requisito que parece implementado mas está errado.

   Os dois relatórios aparecem lado a lado e não são fundidos nem reordenados: código que segue todo padrão e implementa a coisa errada passa num eixo e falha no outro.

   O ticket das páginas próprias deste blog rendeu o exemplo: no celular, o sumário tinha virado ausente em vez de recolhido. O build estava verde e o código seguia todo padrão da casa, então nada em Standards teria como apontar aquilo. O que a issue pedia era recolhido, e essa é a única pergunta que o eixo Spec faz.

6. /triage e /handoff: as duas saídas

   A triage move issues por uma máquina de estados de dois papéis de categoria e cinco de estado. Ela vale para o que chega de fora, e só para isso: ticket que a to-tickets produziu já nasce pronto para agente.

   A handoff é para quando a sessão acaba antes do trabalho. Ela compacta a conversa num markdown fora do repositório, com uma seção de skills sugeridas. A instrução mais importante dela é o que não fazer: não duplicar o que já está numa spec, numa issue ou num commit.

Quando a ideia não cabe numa sessão​

As skills de apoio, e quando usar cada uma​

O pipeline acima não usa o conjunto inteiro. As que sobram existem para situações específicas, e a ask-matt é o roteador que diz qual delas serve.

Duas delas mudam mais o resultado do que o nome sugere.

A diagnosing-bugs recusa hipótese antes do laço. A fase 1 dela é construir um comando que já fica vermelho neste bug. Se você se pegar lendo código para montar teoria antes desse comando existir, pare.

A writing-for-agents trata da palavra-guia, um termo que o modelo já traz do pré-treino e que ancora um comportamento inteiro em um token só. É por isso que a diagnosing-bugs fala em laço vermelho em vez de "um laço em que você confia": troca um portão vago por um estado observável.

O que muda no dia a dia​

As rodadas ficam curtas. Eu respondo cinco a quinze perguntas numeradas, quase sempre ratificando, e a sessão anda sozinha por horas.

A decisão fica escrita. Quando eu esqueço por que o blog não tem página de autor, a resposta não está na minha memória nem no chat: está numa subdecisão numerada da issue da spec.

O paralelismo é de verdade. Como cada ticket cabe numa sessão nova e as arestas de bloqueio são explícitas, mais de uma sessão pega tickets diferentes ao mesmo tempo. A condição para não quebrar é isolamento: cada sessão entra num worktree próprio antes da primeira edição.

O portão fica claro. A CI aqui tem um passo só, npm run build, e é ele que decide se o pull request entra. Não existe régua, varredura nem hook de commit, e o que sobrou de regra de escrita está em prosa no AGENTS.md e nos arquivos de regra ao lado dele.

E o mais desconfortável: você lê muito mais do que escreve. Julgar uma recomendação, conferir uma medição e vetar uma decisão ruim é trabalho de leitura, e quem espera pensar menos vai se frustrar.

Lições deste acervo​

Nada aqui vem da skill. São coisas que este repositório aprendeu apanhando, e que ficaram escritas para não serem aprendidas de novo.

1. A convenção em português não fecha a issue

   O corpo do commit é escrito em português, e uma frase como "Fecha #198" não dispara automatismo nenhum do GitHub. Sem o trailer Closes #198 em inglês, a issue continua aberta depois do merge.

2. Merge sem apagar a branch

   gh pr merge --auto --squash, e nunca com --delete-branch. A flag troca o checkout local para a main, que pode estar ocupada por outro worktree. No dia em que estiver, o comando falha na etapa local depois de o merge já ter acontecido no GitHub.

3. Duas runs vermelhas pela mesma causa, e para

   Sem teto, um agente queima a sessão inteira consertando em laço. Duas falhas pelo mesmo motivo dizem que a premissa está errada, não que falta mais uma tentativa.

4. O servidor de desenvolvimento mente sobre link quebrado

   onBrokenLinks: 'throw' não roda em docusaurus start, que devolve 200 para qualquer rota. Link quebrado só aparece no build, e é por isso que o build vem antes do primeiro push.

Por onde começar​

O menor caminho completo é este: instale o conjunto, rode /setup-matt-pocock-skills uma vez, e leve uma ideia pequena por /grill-with-docs, /to-spec, /to-tickets e /implement, sem pular a revisão no fim. A ideia pequena importa: a mecânica se aprende mais rápido num assunto cuja spec cabe numa tela.

O sintoma já estava no código antes de eu decidir nada: o plugin de blog do Docusaurus vinha desligado, com um comentário dizendo que nenhum consumidor tinha pedido um. Este artigo é esse consumidor.

O que este ticket abriu​

O Blog entrou como a quinta aba, por último na faixa, e não como mais uma instância de documentação: é o plugin oficial de blog, que já vinha junto do preset instalado, então nenhuma dependência nova entrou no projeto. Cada artigo mora numa pasta própria, com o título só no front matter, nunca como # título no corpo. Cada um carrega pelo menos uma tag de assunto, de um catálogo fechado, e a primeira delas é a que aparece em destaque na listagem.

A regra de voz da documentação, "você mais imperativo, zero primeira pessoa", não alcança o blog. Aqui a voz é minha, artigo a artigo, e este texto mistura primeira e terceira pessoa por escolha, não por descuido. O que não muda é o zero travessão: essa regra vale em qualquer texto publicado deste site, blog incluído.

As páginas ainda são as padrão do tema Docusaurus enquanto escrevo isto. Um próximo ticket troca a cara delas por componentes deste próprio repositório, sem nenhum swizzle: todo componente de blog do tema é território unsafe para essa técnica, e o orçamento disso aqui é zero.

O que era antes​

Uma receita cujo servidor tinha código próprio dependia de um clone. O overpower mantinha esse clone em ~/.overpower/mcp/, um diretório por receita, escopo de máquina por natureza: o clone vivia ali, e o arquivo de configuração escrito para cada projeto apontava para ele.

O que muda na 0.31.0​

Agora a receita declara source:, com quatro chaves: git, ref, runner e entrypoint. O overpower monta a linha do runner a partir delas, com o server.args da receita aposto no fim, e não clona nada. O ~/.overpower/mcp/ deixou de existir, e é por isso que uma receita com fonte volta a instalar em escopo de projeto: o arquivo que cada máquina escreve sai idêntico, porque não depende mais de um clone local.

O ref é obrigatório, e o runner é vocabulário fechado: só uvx ou npx, recusados por nome fora dessas duas opções. transport, server.command e a precondição de runner passaram a derivados: declarar qualquer um deles ao lado de source: também é recusa por nome, porque os dois jeitos de descrever o mesmo servidor deixariam de concordar em algum momento.

O source: antigo, com a chave url, e o token de substituição que ele usava pararam de ser lidos. Sem janela de compatibilidade: uma receita escrita no formato anterior falha, nomeando o que precisa mudar.

O que isso resolve no dia a dia​

O doctor perdeu as duas conferências que existiam para o clone e ganhou uma no lugar: re-roda a precondição do runner contra o PATH, offline. E o list --from passou a mostrar a origem e a ref na linha do servidor, o que antes exigia abrir o arquivo da receita para saber.

O registro completo, com todas as versões, está no changelog do overpower.