O repositório mattpocock/skills reúne práticas de engenharia de software transformadas em instruções reutilizáveis para agentes de código. Em vez de pedir que um agente “faça um app” e aceitar uma sequência opaca de passos, o pacote propõe pequenos workflows para entender requisitos, manter um glossário do domínio, escrever especificações, quebrar o trabalho em issues, testar por interfaces públicas e revisar o resultado.
Há uma correção importante de número: na consulta feita em 5 de novembro de 2026, o GitHub exibia cerca de 258,8 mil estrelas e 21,8 mil forks para o projeto. Portanto, ele é extremamente popular, mas a marca de 300 mil ainda não estava refletida na página pública consultada. O interesse é relevante porque o projeto virou uma referência prática para quem usa Claude Code, Codex, Copilot, Gemini CLI e outros agentes em projetos reais.

O que são “skills” para agentes de código
Uma skill é um documento de instruções acionável pelo agente. Ela não é uma biblioteca que adiciona funções ao seu aplicativo e tampouco substitui o modelo de IA. Seu papel é fornecer um processo: quando usar uma técnica, quais evidências buscar, onde registrar decisões e quais erros evitar.
No caso de Skills for Real Engineers, Matt Pocock organiza essas instruções em arquivos SKILL.md. Há dois grupos principais: engineering, focado em planejamento, testes, bugs, arquitetura e revisão; e productivity, voltado a alinhamento, ensino, handoff e redação para agentes. O repositório também mantém áreas misc, in-progress e deprecated, que não têm o mesmo status de recomendação.
Por que esse repositório chamou tanta atenção
A proposta confronta um problema conhecido do desenvolvimento assistido por IA: gerar código ficou rápido, mas entendimento, validação e manutenção não ficaram automáticos. Um agente pode produzir telas e arquivos em minutos, porém ainda pode interpretar mal a necessidade, testar detalhes internos frágeis, inventar abstrações prematuras ou entregar uma mudança que não corresponde ao que foi pedido.
O projeto não tenta impor uma metodologia monolítica. O README critica sistemas que “tomam posse” do processo inteiro e propõe habilidades pequenas, editáveis e combináveis. Em termos práticos, você pode usar apenas uma disciplina de TDD em um repositório, ou iniciar um trabalho grande com entrevista, glossário e decisões arquiteturais registradas.
Os fluxos mais relevantes para engenharia de verdade
| Skill | Quando usar | Resultado esperado |
|---|---|---|
grill-with-docs | Antes de mudar um produto ou código com requisitos ambíguos | Entrevista guiada, glossário e ADRs |
to-spec | Quando a conversa já definiu o que precisa ser feito | Especificação conectada ao rastreador de issues |
to-tickets | Para quebrar uma especificação em fatias executáveis | Issues com dependências explícitas |
tdd | Ao implementar comportamento verificável | Ciclos curtos de teste falhando e implementação mínima |
diagnosing-bugs | Ao investigar defeitos ou regressões difíceis | Reprodução, hipótese, instrumentação, correção e teste de regressão |
code-review | Depois de uma mudança, PR ou branch | Revisões separadas de padrão de código e aderência à especificação |
improve-codebase-architecture | Para procurar oportunidades de melhorar um sistema existente | Relatório de candidatos a módulos mais profundos |
grill-with-docs: alinhar antes de produzir código
O ponto de entrada mais interessante para um projeto novo é grill-with-docs. A skill é deliberadamente curta: ela chama as disciplinas de grilling e domain-modeling. A primeira conduz uma entrevista intensa para reduzir ambiguidades; a segunda transforma vocabulário e decisões em documentação reutilizável.
O resultado desejado não é “uma reunião longa com a IA”. É um repositório que passa a ter termos consistentes. Se uma equipe chama um processo de “materialização”, “onboarding” ou “pedido elegível”, o agente deixa de reinventar descrições longas a cada sessão. Nomes de funções, variáveis, casos de teste e documentos passam a usar o mesmo modelo de domínio.
O setup inicial: rastreador, rótulos e documentos de domínio
Antes das skills de engenharia, o projeto recomenda executar /setup-matt-pocock-skills uma vez por repositório. Ela não é um instalador automático que escreve arquivos sem contexto. O documento manda primeiro explorar o repositório, identificar se já há AGENTS.md ou CLAUDE.md, checar o remoto Git, localizar ADRs e descobrir se existe um monorepo.
Depois disso, a configuração registra três coisas: onde o trabalho será acompanhado, quais rótulos representam o estado de triagem e onde ficam glossário e decisões arquiteturais. GitHub, GitLab e arquivos Markdown locais são opções previstas. Isso resolve um problema comum de agentes: criar arquivos de planejamento em lugares aleatórios que ninguém lê depois.
# Claude Code: bundle gerenciado e atualizado pelo plugin
claude plugin install mattpocock-skills@claude-plugins-official
# Codex: marketplace e plugin indicados pelo README atual
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
# Installer para agentes compatíveis, com arquivos editáveis no projeto
npx skills@latest add mattpocock/skills -a <agent>O último comando requer atenção. Ele executa um pacote via npm e copia instruções para o ambiente escolhido. Em um projeto comercial, trate essa etapa como qualquer dependência de desenvolvimento: revise a origem, escolha quais skills instalar, faça commit dos arquivos adicionados e revise o diff antes de deixar um agente obedecer às novas instruções.
Plugin atualizado ou arquivos que você controla?
O próprio repositório separa duas filosofias. O plugin para Claude Code é um bundle gerenciado, atualizado automaticamente; a instalação via skills.sh/npx skills copia arquivos que você pode editar e atualizar quando decidir. Instalar os dois ao mesmo tempo pode duplicar as skills e criar instruções concorrentes.
Para equipes que precisam de repetibilidade, a alternativa editável costuma ser mais auditável: o conteúdo fica versionado ao lado do código e cada mudança aparece no Git. Para quem quer acompanhar rapidamente as atualizações do autor em um ambiente individual, o plugin reduz trabalho operacional. A decisão não é técnica apenas: envolve segurança, governança e quem pode alterar a forma como o agente trabalha.
TDD sem testes acoplados à implementação
A skill tdd defende um ciclo vermelho → verde: primeiro o teste falha, depois vem apenas a implementação mínima para fazê-lo passar. A parte mais útil é a ênfase em seams, ou fronteiras públicas onde o comportamento é observado sem entrar nos detalhes internos.
Antes de escrever um teste, a skill pede que o time escolha e confirme as interfaces que serão testadas. Isso evita duas armadilhas: testar métodos privados e mocks internos, que quebram em qualquer refactor; ou escrever testes tautológicos, nos quais a expectativa repete a mesma lógica da implementação.
// Em vez de testar uma função interna ou uma tabela do banco,
// exercite o contrato que o consumidor realmente usa.
const result = calculateShipping({ country: 'BR', subtotal: 250 })
expect(result).toEqual({ amount: 0, label: 'Frete grátis' })O exemplo não vem do repositório; ele ilustra o princípio: o valor esperado deve nascer de uma regra de negócio conhecida, não ser recalculado no próprio teste. A skill também recomenda trabalhar em fatias verticais, uma hipótese verificável de cada vez, e deixa refactoring para a etapa de revisão.
Revisão em dois eixos: padrão e especificação
code-review separa a revisão em duas perguntas que normalmente se misturam: o código segue os padrões do projeto? E ele realmente atende a especificação ou issue que o originou? A skill propõe duas análises paralelas, cada uma com seu foco.
Na revisão de padrões, além das regras próprias do repositório, ela usa uma base inspirada em code smells de Martin Fowler: nomes misteriosos, duplicação, inveja de funcionalidade, grupos de parâmetros que deveriam virar tipo, obsessão por primitivas, switches repetidos, cirurgia de espingarda e generalidade especulativa. A documentação deixa claro que esses cheiros são heurísticas, não condenações automáticas.
Na revisão de especificação, o agente compara o diff com o que foi pedido e procura requisitos ausentes, comportamento que excedeu o escopo e implementações aparentemente corretas que não entregam o resultado solicitado. Separar os relatórios ajuda a não chamar de “bom código” algo que resolve o problema errado.
Prós e contras para usar no seu repositório
✅ O que você ganha
- Processos pequenos: é possível instalar somente o que resolve uma dor real.
- Documentação que o agente reutiliza: glossário e ADRs evitam que decisões antigas desapareçam entre sessões.
- Disciplina de verificação: TDD, diagnóstico e revisão tornam o agente menos dependente de “parece certo”.
- Portabilidade: o repositório declara suporte a diversos agentes e mantém formatos de instalação para vários ecossistemas.
- Licença MIT: o código pode ser estudado, adaptado e redistribuído dentro dos termos da licença.
⚠️ O que você não ganha
- Um agente mais inteligente por si só: as skills melhoram processo, mas não corrigem falta de contexto, credenciais, testes ou acesso a serviços.
- Especificação automática perfeita: entrevistas e documentação dependem de respostas boas da equipe.
- Segurança automática: uma skill é texto instrucional; ela precisa ser tratada como código de terceiros para fins de revisão e confiança.
- Uma metodologia obrigatória: o pacote é modular, mas pode gerar fricção se uma equipe adotar regras sem adaptar ao ritmo e aos controles já existentes.
Requisitos e escolha de instalação
| Componente | Mínimo | Recomendado | Por quê |
|---|---|---|---|
| Agente compatível | Claude Code, Codex ou outro suportado pelo instalador | Um agente usado diariamente pela equipe | As skills dependem do mecanismo de carregamento de cada harness |
| Git | Repositório local | Branch e revisão de diff | Permite auditar os arquivos de instrução |
| Rastreador | Opcional | GitHub Issues, GitLab ou fluxo local definido | Habilita specs, triagem e tickets com continuidade |
| Documentação | Um local decidido pela equipe | GLOSSARY.md e docs/adr/ versionados | Evita que conhecimento de domínio fique preso ao chat |
| Segurança | Revisão humana | Allowlist de skills e atualizações revisadas | Instruções de agentes podem alterar ações e acesso a arquivos |
Um caminho seguro para testar sem contaminar seu projeto
- Crie uma branch ou repositório de laboratório. Não comece instalando um bundle autoatualizável no repositório que faz deploy em produção.
- Instale um conjunto mínimo. Comece por
setup-matt-pocock-skills,grill-with-docs,tddecode-review. - Leia os arquivos instalados. Confira gatilhos, caminhos que a skill lê ou altera, chamadas a CLI e qualquer instrução para subagentes.
- Defina fronteiras. Proíba publicação, deploy, alteração de infraestrutura e acesso a segredos sem aprovação explícita.
- Teste uma mudança pequena. Use uma correção com critério objetivo de aceite e compare qualidade, tempo e manutenção com o fluxo normal.
- Versione a configuração. Se usar a opção editável, trate mudanças nas skills como revisão de código.
Troubleshooting: cinco erros comuns
- ❌ A mesma skill aparece duas vezes. Causa: plugin gerenciado e arquivos instalados coexistem. Solução: escolha um modelo por agente e remova a duplicação antes de continuar.
- ❌ O agente cria issues no repositório errado. Causa: o setup não validou o remoto ou o rastreador. Solução: revise a configuração do issue tracker e teste comandos de leitura antes de permitir criação.
- ❌ O agente pergunta demais e não entrega. Causa: uma skill de entrevista foi usada para uma tarefa já especificada. Solução: transforme a conversa existente em spec com
to-specou limite o escopo da entrevista. - ❌ Testes quebram em todo refactor. Causa: foram escritos contra detalhes internos. Solução: redefina a seam como interface pública e elimine mocks de implementação.
- ❌ Atualização mudou o comportamento do agente. Causa: bundle ou marketplace atualiza automaticamente. Solução: fixe ou revise versões em ambiente de teste antes de propagar a atualização para a equipe.
FAQ
Isso é um framework de agentes?
Não. É uma coleção de instruções e workflows. Ela não hospeda modelos, não cria um servidor próprio e não substitui seu agente de código.
Funciona só com TypeScript?
Não. O autor é conhecido pelo ecossistema TypeScript, mas as disciplinas de requisito, domínio, testes, diagnóstico e revisão são independentes da linguagem.
Posso editar as skills?
Sim, quando instalar arquivos editáveis pelo fluxo indicado. A licença MIT permite adaptação, mas alterações precisam ser revisadas como qualquer mudança que orienta um agente.
Preciso usar todas as skills?
Não. A modularidade é o ponto central. Uma equipe pode adotar apenas o setup e a revisão, ou combinar entrevista, especificação, tickets e implementação conforme a necessidade.
É seguro instalar automaticamente?
Não existe resposta universal. Instalação automática reduz manutenção, mas atualizações podem mudar instruções. Projetos sensíveis devem preferir revisão de arquivos, ambiente de teste e permissões mínimas.
Vale a pena?
Sim, especialmente para equipes que já perceberam que “vibe coding” não escala para software mantido por anos. O mérito do mattpocock/skills não está em prometer que IA escreve todo o produto sozinha. Está em recolocar atividades tradicionais de engenharia, como esclarecimento de requisitos, linguagem de domínio, feedback rápido, testes e revisão, dentro do fluxo do agente.
Na análise do NoticIA, a popularidade do repositório faz sentido porque ele atende uma necessidade concreta: transformar conversas e código gerado em trabalho rastreável, testável e revisável. Mas ele deve entrar como uma camada de processo sob controle da equipe, não como um pacote de prompts confiado sem auditoria.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
