skills
mattpocock/skills
Skills for Real Engineers. Straight from my .claude directory.
Instalação
npx convez-ai mattpocock/skills1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README em português
Skills Para Engenheiros de Verdade
Minhas habilidades para agentes que uso todos os dias para fazer engenharia real — não vibe coding.
Desenvolver aplicações reais é difícil. Abordagens como GSD, BMAD e Spec-Kit tentam ajudar assumindo o processo. Mas ao fazê-lo, elas tiram seu controle e tornam bugs no processo difíceis de resolver.
Essas habilidades foram projetadas para serem pequenas, fáceis de adaptar e composáveis. Funcionam com qualquer modelo. São baseadas em décadas de experiência em engenharia. Experimente modificá-las. Torne-as suas próprias. Divirta-se.
Se você quiser acompanhar as alterações nessas habilidades e quaisquer novas que eu criar, pode se juntar aos ~60.000 outros devs na minha newsletter:
Quickstart (configuração de 30 segundos)
- Execute o instalador skills.sh:
npx skills@latest add mattpocock/skills
-
Escolha as habilidades que deseja e em quais agentes de codificação você quer instalá-las. Certifique-se de selecionar
/setup-matt-pocock-skills. -
Execute
/setup-matt-pocock-skillsno seu agente. Ele irá:- Perguntar qual rastreador de issues você deseja usar (GitHub, Linear ou arquivos locais)
- Perguntar quais rótulos (labels) você aplica aos tickets quando os tria (
/triageusa labels) - Perguntar onde você quer salvar qualquer documentação que criarmos
-
Bam — está pronto para ir.
Por Que Essas Habilidades Existem
Criei essas habilidades como uma maneira de corrigir modos comuns de falha que vejo com o Claude Code, Codex e outros agentes de codificação.
#1: O Agente Não Fez o Que Eu Queria
"Ninguém sabe exatamente o que quer"
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 vê o que eles construíram — e percebe que não entenderam nada do que você disse.
Isso é exatamente a mesma coisa na era da IA. Existe uma lacuna de comunicação entre você e o agente. A solução para isso é uma sessão de interrogatório (grilling session) — fazer com que o agente faça perguntas detalhadas sobre o que você está construindo.
A Solução é usar:
/grill-me- para usos não relacionados a código/grill-with-docs- igual ao/grill-me, mas adiciona mais recursos (veja abaixo)
Essas são minhas habilidades mais populares. Elas ajudam você a se alinhar com o agente antes de começar e pensam profundamente sobre a mudança que está fazendo. Use-as sempre quando quiser fazer uma alteração.
#2: O Agente É Demasiado Verboso
Com uma linguagem ubíqua, conversas entre desenvolvedores e expressões do código são todas derivadas do mesmo modelo de domínio.
Eric Evans, Domain-Driven-Design
O Problema: No início de um projeto, devs e as pessoas para quem estão construindo o software (os especialistas no domínio) geralmente falam línguas diferentes.
Eu senti a mesma tensão com meus agentes. Agentes são usualmente inseridos em um projeto e pedem que eles descubram o jargão conforme vão. Então eles usam 20 palavras onde uma bastaria.
A Solução para isso é uma linguagem compartilhada. É um documento que ajuda os agentes a decodificar o jargão usado no projeto.
Aqui está um exemplo CONTEXT.md, do meu repositório course-video-manager. Qual é mais fácil de ler?
- ANTES: "Existe um problema quando uma lição dentro de uma seção de um curso se torna 'real' (ou seja, recebe um lugar no sistema de arquivos)"
- DEPOIS: "Existe um problema com a cascata de materialização"
Essa concisão paga dividendos sessão após sessão.
Isso está incorporado em /grill-with-docs. É uma sessão de interrogatório, mas isso ajuda você a construir uma linguagem compartilhada com a IA e documentar decisões difíceis de explicar em ADR's.
É difícil explicar o quão poderoso é isso. Pode ser a técnica mais legal deste repositório. Experimente e veja.
[!DICA] Uma linguagem compartilhada tem muitos outros benefícios além de reduzir verbosidade:
- Variáveis, funções e arquivos são nomeados consistentemente, usando a linguagem compartilhada
- Como resultado, o código é mais fácil de navegar para o agente
- O agente também gasta menos tokens pensando, porque tem acesso a uma linguagem mais concisa
#3: O Código Não Funciona
"Sempre dê pequenos passos deliberados. A taxa de feedback é o seu limite de velocidade. Nunca assuma uma tarefa que seja muito grande."
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 lixo?
É hora de olhar para seus loops de feedback. Sem feedback sobre como o código produzido realmente roda, o agente estará voando às cegas.
A Solução: Você precisa do usual conjunto de loops de feedback: tipos estáticos, acesso ao navegador e testes automatizados.
Para testes automatizados, um loop red-green-refactor é crítico. É aqui que o agente escreve primeiro um teste falho, depois conserta o código para fazer o teste passar. Isso ajuda a dar ao agente um nível consistente de feedback que resulta em muito melhor código.
Eu criei uma /tdd skill que você pode encaixar em qualquer projeto. Ela incentiva red-green-refactor e dá ao agente bastante orientação sobre o que torna bons e maus testes.
Para depuração, eu também criei uma /diagnose skill que envolve as melhores práticas de depuração em um loop simples.
#4: Construímos Uma Bola de Lodo
"Invista no design do sistema todos os dias."
Kent Beck, Extreme Programming Explained
"Os melhores módulos são profundos. Eles permitem que muita funcionalidade seja acessada através de uma interface simples."
John Ousterhout, A Philosophy Of Software Design
O Problema: A maioria dos apps construídos com agentes é complexa e difícil de mudar. Como os agentes podem acelerar radicalmente a codificação, eles também aceleram a entropia do software. Bases de código ficam mais complexas em uma taxa sem precedentes.
A Solução para isso é uma abordagem radicalmente nova ao desenvolvimento impulsionado por IA: cuidar do design do código.
Isso está embutido em cada camada dessas skills:
/to-prdfaz perguntas sobre quais módulos você está tocando antes de criar um PRD/zoom-outdiz ao agente para explicar o código no contexto do sistema todo
E crucialmente, /improve-codebase-architecture ajuda você a resgatar uma base de código que se tornou uma bola de lodo. Recomendo rodá-la na sua base de código uma vez a cada poucos dias.
Resumo
Fundamentos de engenharia de software são mais importantes do que nunca. Essas skills representam meu melhor esforço para condensar esses fundamentos em práticas repetíveis, para ajudar você a lançar os melhores apps da sua carreira. Aproveite.
Referência
Engenharia
Skills que uso diariamente para trabalho com código.
- diagnose — Loop de diagnóstico disciplinado para bugs difíceis e regressões de desempenho: reproduzir → minimizar → hipotetizar → instrumentar → consertar → testar regressão.
- grill-with-docs — Sessão de grilling que desafia seu plano contra o modelo de domínio existente, afia a terminologia e atualiza
CONTEXT.mde ADRs inline. - triage — Triage issues através de uma máquina de estados de papéis de triagem.
- improve-codebase-architecture — Encontre oportunidades de aprofundamento em uma base de código, informado pela linguagem do domínio em
CONTEXT.mde pelas decisões emdocs/adr/. - setup-matt-pocock-skills — Esqueleto da configuração por repositório (rastreador de issues, vocabulário de rótulos de triagem, layout do documento de domínio) que as outras skills de engenharia consomem. Execute uma vez por repositório antes de usar
to-issues,to-prd,triage,diagnose,tdd,improve-codebase-architectureouzoom-out. - tdd — Desenvolvimento orientado a testes com um loop red-green-refactor. Constrói recursos ou conserta bugs em fatias verticais uma de cada vez.
- to-issues — Quebre qualquer plano, especificação ou PRD em issues do GitHub independentemente capturáveis usando fatias verticais.
- to-prd — Transforme o contexto da conversa atual em um PRD e envie-o como uma issue do GitHub. Sem entrevista — apenas sintetiza o que você já discutiu.
- zoom-out — Diga ao agente para dar zoom out e fornecer contexto mais amplo ou uma perspectiva de nível superior sobre uma seção desconhecida de código.
- prototype — Construa um protótipo descartável para desenvolver um design — seja um app terminal executável para perguntas de estado/lógica de negócios, ou várias variações radicalmente diferentes da UI alternáveis a partir de uma rota.
Produtividade
Ferramentas de fluxo de trabalho geral, não específicas para código.
- caveman — Modo de comunicação ultra-comprimido. Reduz o uso de tokens em ~75% ao eliminar enfeites enquanto mantém a precisão técnica completa.
- grill-me — Seja entrevistado incansavelmente sobre um plano ou design até que cada ramo da árvore de decisão seja resolvido.
- handoff — Condense a conversa atual em um documento de transferência para que outro agente possa continuar o trabalho.
- teach — Ensine ao usuário uma nova habilidade ou conceito através de múltiplas sessões, usando o diretório atual como espaço de ensino stateful (com estado).
- write-a-skill — Crie novas habilidades com estrutura adequada, revelação progressiva e recursos agrupados.
Diversos
Ferramentas que mantenho por perto mas raramente uso.
- git-guardrails-claude-code — Configure hooks do Claude Code para bloquear comandos git perigosos (push, reset --hard, clean, etc.) antes de executá-los.
- migrate-to-shoehorn — Migre arquivos de teste de afirmações do tipo
aspara @total-typescript/shoehorn. - scaffold-exercises — Crie estruturas de diretório de exercícios com seções, problemas, soluções e explicadores.
- setup-pre-commit — Configure hooks pre-commit do Husky com lint-staged, Prettier, verificação de tipos e testes.