Tradução para pt-BR da coleção de agent skills de Matt Pocock. Obra derivada sob licença MIT, não afiliada ao autor original — veja NOTICE. A seção "Por que essas skills existem" abaixo preserva a voz em primeira pessoa do autor original; o restante do documento é instrução operacional deste repositório.
Skills de agente que eu uso todos os dias para fazer engenharia de verdade — não vibe coding.
Desenvolver aplicações de verdade é difícil. Abordagens como GSD, BMAD e Spec-Kit tentam ajudar assumindo o controle do processo. Mas, ao fazer isso, tiram o seu controle e tornam os bugs do processo difíceis de resolver.
Estas skills foram desenhadas para serem pequenas, fáceis de adaptar e componíveis. Funcionam com qualquer modelo. São baseadas em décadas de experiência em engenharia. Mexa nelas. Faça-as suas. Aproveite.
Se você quiser acompanhar mudanças nestas skills, e quaisquer novas que eu criar, pode se juntar a ~60.000 outros devs na minha newsletter (em inglês):
Esta tradução é instalada com o CLI skills.sh, que copia os arquivos de skill, editáveis, para o seu projeto.
npx skills@latest add matheusdmlopes/skills-ptbrEscolha as skills que quiser, e em quais agentes de código instalá-las. O instalador deixa você escolher quais skills levar — garanta que setup-matt-pocock-skills seja uma delas.
O instalador oferece todas as skills deste repositório, e nem todas estão traduzidas. Em pt-BR estão as skills promovidas listadas em .claude-plugin/plugin.json, mais claude-handoff e loop-me. As demais de in-progress/, todas as de misc/ e deprecated/, e as páginas em docs/ seguem no inglês original, herdadas sem alteração do repositório original. Para distinguir na hora de escolher, leia a description de cada item na lista — ela está escrita no idioma daquela skill.
Isso grava as skills no seu repositório como arquivos comuns, que você possui e pode editar. Nada é atualizado nas suas costas; busque as atualizações quando quiser com npx skills update.
Para trocar de idioma depois — por exemplo, voltar para o original em inglês —, reinstale a partir da outra origem. A reinstalação substitui integralmente a versão anterior:
npx skills@latest add mattpocock/skills # inglês (original)
npx skills@latest add matheusdmlopes/skills-ptbr # pt-BR (esta tradução)No seu agente, rode uma vez por repositório. Ele vai:
- Perguntar qual issue tracker você quer usar (GitHub, Linear, ou arquivos locais)
- Perguntar quais labels você aplica a tickets quando os tria (
/triageusa labels) - Perguntar onde você quer salvar quaisquer docs que criarmos
Se o passo 2 já deu "invalid command" pra você ao digitar /setup-matt-pocock-skills dentro do agy, não era bug desta tradução nem incompatibilidade permanente — era um bug do próprio agy, já corrigido. Versões antigas do CLI (1.0.1–1.0.8) tinham uma série de falhas documentadas no próprio changelog (agy changelog) em torno da descoberta e execução de comandos derivados de skill: skills que não recarregavam dinamicamente, sugestões do autocomplete que limpavam o campo sem executar o comando, descoberta de skill "fallback" que falhava quando o diretório de configuração padrão estava ausente. A partir da versão 1.0.8 essas falhas foram corrigidas, e a partir da 1.1.9 o mesmo mecanismo de expansão de slash-command passou a valer também no modo -p/print (agy atualiza sozinho, então é provável que você tenha simplesmente pego uma versão anterior a essa janela).
Testamos ao vivo com agy 1.1.13: /setup-matt-pocock-skills aparece no autocomplete (puxando a description do SKILL.md) e executa a skill de ponta a ponta, corretamente. Se ainda dermos erro na sua versão, rode agy update primeiro.
Dois detalhes que continuam valendo:
- O Antigravity lê skills de um diretório global por usuário (
~/.agents/skills), além de um local por repositório — por isso uma skill instalada aparece em qualquer projeto, não só no repositório onde foi instalada. - Desde a versão 1.1.12, o
agyreconhece a flagdisable-slash-command: trueno frontmatter doSKILL.md— mas ela faz o oposto do que este repositório precisa: esconde a skill do menu/, mantendo-a invocável implicitamente pelo modelo. Não existe ainda, no Antigravity, um equivalente exato aodisable-model-invocationdo Claude Code (que faz o oposto: bloqueia invocação implícita, mantém a explícita) — então skills marcadas aqui como user-invoked (como a própriasetup-matt-pocock-skills) podem, em tese, também ser acionadas pelo modelo por conta própria no Antigravity, mesmo sem confirmação disso em teste.
Eu construí estas skills como uma forma de corrigir modos de falha comuns que vejo no Claude Code, no Codex e em outros agentes de código.
"No-one knows exactly what they want"
David Thomas & Andrew Hunt, The Pragmatic Programmer
O Problema. O modo de falha mais comum no desenvolvimento de software é o desalinhamento. Você acha que o dev sabe o que você quer. Depois você vê o que ele construiu — e percebe que ele não te entendeu nada.
É a mesma coisa na era da IA. Existe uma lacuna de comunicação entre você e o agente. A correção para isso é uma sessão de sabatina — fazer o agente te perguntar detalhadamente sobre o que você está construindo.
A Solução é usar:
/grill-me— para usos fora de código/grill-with-docs— igual a/grill-me, mas adiciona mais vantagens (veja abaixo)
Estas são minhas skills mais populares. Elas ajudam você a se alinhar com o agente antes de começar, e a pensar profundamente sobre a mudança que está fazendo. Use-as toda vez que quiser fazer uma mudança.
With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.
Eric Evans, Domain-Driven Design
O Problema: No início de um projeto, os devs e as pessoas para quem estão construindo o software (os especialistas de domínio) normalmente falam idiomas diferentes.
Eu senti a mesma tensão com meus agentes. Agentes normalmente são jogados dentro de um projeto e instruídos a descobrir o jargão sozinhos, no processo. Então eles usam 20 palavras onde 1 bastaria.
A Solução para isso é uma linguagem compartilhada. É um documento que ajuda os agentes a decifrar o jargão usado no projeto.
Exemplo
Aqui está um exemplo de CONTEXT.md, do meu repositório course-video-manager. Qual dos dois é mais fácil de ler?
- ANTES: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
- DEPOIS: "There's a problem with the materialization cascade"
Essa concisão se paga sessão após sessão.
Isso está embutido em /grill-with-docs. É uma sessão de sabatina, mas que te ajuda a construir uma linguagem compartilhada com a IA, e a documentar decisões difíceis de explicar em ADRs.
É difícil explicar o quão poderosa essa técnica é. Pode ser a técnica mais legal deste repositório inteiro. Experimente, e veja.
Tip
Uma linguagem compartilhada tem muitos outros benefícios além de reduzir a verbosidade:
- Variáveis, funções e arquivos são nomeados de forma consistente, usando a linguagem compartilhada
- Como resultado, a base de código fica mais fácil de navegar para o agente
- O agente também gasta menos tokens pensando, porque tem acesso a uma linguagem mais concisa
"Always take small, deliberate steps. The rate of feedback is your speed limit. Never take on a task that's too big."
David Thomas & Andrew Hunt, The Pragmatic Programmer
O Problema: Digamos que você e o agente estejam alinhados sobre o que construir. O que acontece quando o agente ainda assim produz porcaria?
É hora de olhar para seus ciclos de feedback. Sem feedback sobre como o código que ele produz de fato roda, o agente vai estar voando às cegas.
A Solução: você precisa do conjunto usual de ciclos de feedback: tipagem estática, acesso a browser e testes automatizados.
Para testes automatizados, um ciclo red-green-refactor é fundamental. É quando o agente escreve um teste que falha primeiro, depois corrige o teste. Isso dá ao agente um nível consistente de feedback que resulta em código muito melhor.
Eu construí uma skill /tdd que você pode encaixar em qualquer projeto. Ela incentiva red-green-refactor e dá ao agente bastante orientação sobre o que faz um teste bom ou ruim.
Para depuração, também construí uma skill /diagnosing-bugs que empacota as melhores práticas de debugging num ciclo disciplinado, com portões fase a fase.
"Invest in the design of the system every day."
Kent Beck, Extreme Programming Explained
"The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
John Ousterhout, A Philosophy Of Software Design
O Problema: A maioria dos apps construídos com agentes são complexos e difíceis de mudar. Como agentes conseguem acelerar radicalmente a escrita de código, eles também aceleram a entropia do software. Bases de código ficam mais complexas numa velocidade sem precedentes.
A Solução para isso é uma abordagem radicalmente nova para o desenvolvimento com IA: se importar com o design do código.
Isso está embutido em cada camada destas skills:
/to-specte questiona sobre quais módulos você está tocando antes de criar uma spec
E, fundamentalmente, /improve-codebase-architecture varre uma base de código em busca de oportunidades de aprofundamento e te entrega as candidatas. Recomendo rodá-la na sua base de código a cada poucos dias. É uma varredura, não um resgate: numa base de código genuinamente antiga ela vai encontrar candidatas reais, mas não vai desembaraçar a lama para você.
Fundamentos de engenharia de software importam mais do que nunca. Estas skills são meu melhor esforço em condensar esses fundamentos em práticas repetíveis, para te ajudar a lançar os melhores apps da sua carreira. Aproveite.
Elas se dividem em um eixo — quem pode invocá-las. Skills User-invoked só são alcançáveis quando você as digita (ex.: /grill-me); seu papel é orquestrar. Skills Model-invoked podem ser invocadas por você ou acionadas automaticamente pelo agente quando a tarefa se encaixa; elas carregam a disciplina reutilizável. Uma skill user-invoked pode invocar skills model-invoked, mas nunca outra user-invoked.
Skills que uso diariamente para trabalho de código.
User-invoked
- ask-matt — Pergunte qual skill ou fluxo se encaixa na sua situação. Um roteador sobre as skills user-invoked deste repositório.
- grill-with-docs — Sessão de sabatina que também constrói o modelo de domínio do seu projeto, refinando a terminologia e atualizando
CONTEXT.mde ADRs no processo. - triage — Mova issues por uma máquina de estados de papéis de triagem.
- improve-codebase-architecture — Varra uma base de código em busca de oportunidades de aprofundamento, apresente-as como um relatório HTML visual, depois sabatine qual você escolher.
- setup-matt-pocock-skills — Configure este repositório para as skills de engenharia (issue tracker, labels de triagem, layout de docs de domínio). Rode uma vez por repositório antes de usar as outras skills de engenharia.
- to-spec — Transforme a conversa atual em uma spec e publique-a no issue tracker. Sem entrevista — apenas sintetiza o que você já discutiu.
- to-tickets — Divida qualquer plano, spec ou conversa em um conjunto de tickets de bala traçante, cada um declarando suas arestas de bloqueio — escritos como texto em um arquivo local, ou como links nativos de bloqueio em um tracker real.
- implement — Construa o trabalho descrito por uma spec ou conjunto de tickets, acionando
/tddnas costuras pré-acordadas e concluindo com/code-reviewantes de commitar. - wayfinder — Planeje um pedaço enorme de trabalho, maior do que uma sessão de agente comporta, como um mapa compartilhado de decision tickets no issue tracker — resolva-os um de cada vez até que o caminho até o destino esteja claro.
Model-invoked
- prototype — Construa um protótipo descartável para responder a uma questão de design — um único arquivo HTML compartilhável para questões de estado/lógica, ou várias variações de UI radicalmente diferentes alternáveis a partir de uma rota.
- diagnosing-bugs — Ciclo de diagnóstico disciplinado para bugs difíceis e regressões de performance: construa um ciclo de feedback que fica vermelho neste bug → minimize → hipotetize → instrumente → corrija → teste de regressão.
- research — Investigue uma pergunta contra fontes primárias de alta confiança e capture as descobertas como um arquivo Markdown citado no repositório, rodando como um agente em segundo plano.
- tdd — Desenvolvimento orientado a testes com um ciclo red-green-refactor. Constrói funcionalidades ou corrige bugs uma fatia vertical por vez.
- domain-modeling — Construa e refine ativamente o modelo de domínio de um projeto — conteste termos contra o glossário, estresse-teste com cenários de casos de borda, e atualize
CONTEXT.mde ADRs no processo. - codebase-design — Disciplina e vocabulário compartilhados para desenhar deep modules: muito comportamento atrás de uma interface pequena, posicionada em uma costura limpa, testável através dessa interface.
- code-review — Revisão em dois eixos do diff desde um ponto fixo: Standards (segue os padrões de código do repositório, mais uma base de smells de Fowler?) e Spec (implementa fielmente a issue/spec de origem?), rodando como subagentes paralelos para que nenhum contamine o outro.
- resolving-merge-conflicts — Trabalhe um merge ou rebase git em andamento hunk por hunk, resolvendo por intenção rastreada até a fonte primária de cada lado, depois finalize a operação — nunca
--abort. - wizard — Gere um wizard interativo em bash que guia um humano por passos que só ele pode realizar: provisionar infraestrutura, configurar credenciais ou secrets de CI, navegar um dashboard de terceiros pouco familiar, ou rodar uma migração ou cutover pontual.
Ferramentas gerais de fluxo de trabalho, não específicas de código.
User-invoked
- grill-me — Seja entrevistado implacavelmente sobre um plano ou design até que cada ramo da árvore de decisões esteja resolvido.
- handoff — Compacte a conversa atual em um documento de handoff para que outro agente possa continuar o trabalho.
- teach — Ensine ao usuário uma nova skill ou conceito ao longo de múltiplas sessões, usando o diretório atual como um espaço de ensino com estado.
- to-questionnaire — Transforme uma decisão que você não consegue responder sozinho em um questionário Markdown para a única pessoa que consegue — preenchido de forma assíncrona, ou junto em uma reunião. Ele sabatina você sobre o envio (para quem é, do que você precisa de volta), não sobre o assunto.
- wait-what — Acione isso no momento em que uma mensagem não for compreendida. O agente reapresenta o que disse com o contexto que está faltando, em linguagem simples, usando o vocabulário do seu
CONTEXT.md.
Model-invoked
- grilling — Entreviste o usuário implacavelmente sobre um plano, decisão ou ideia até que cada ramo da árvore de decisões esteja resolvido. A primitiva de entrevista reutilizável por trás de
grill-me,grill-with-docs,triage,wayfindereimprove-codebase-architecture. - writing-for-agents — Escrever documentos para agentes: skills, AGENTS.md/CLAUDE.md, e qualquer doc que um agente alcance por um ponteiro.