👨🏫 Origem do projeto
O mp-skill é a versão em português do repositório mattpocock/skills, criado por Matt Pocock — o mesmo cara por trás do Total TypeScript, dos artigos sobre TypeScript que provavelmente já te tiraram de algum apuro, e da newsletter AI Hero sobre IA aplicada a engenharia.
Matt começou a montar essas skills depois de bater de frente com os failure modes recorrentes do Claude Code e do Codex: o agente esquece contexto entre sessões, inventa APIs que não existem, pula testes, faz refactors gigantes sem necessidade, ou simplesmente "alucina" um plano e sai escrevendo código que não funciona.
Em vez de aceitar isso como "limitação do modelo", Matt decidiu codificar as soluções. Cada vez que descobria um padrão que evitava um failure mode, virava skill. Cada vez que precisava repetir uma instrução manualmente em três sessões seguidas, virava skill. O resultado é um repositório que parece pequeno mas resolve dezenas de problemas reais.
🎯 A premissa central
Skills são memória externa do agente. Em vez de explicar de novo, toda sessão, como você quer que ele faça TDD, como escreve commits, ou como abre PRs — você grava isso uma vez e a skill carrega no contexto certo, no momento certo.
- • Failure modes viram guardrails reutilizáveis, não anotações em CLAUDE.md
- • Cada skill é um arquivo Markdown — versionável, diff-able, revisável
- • O agente carrega só o que importa pra tarefa atual
💡 Por que skills > "vibe coding"
"Vibe coding" — deixar o agente improvisar sem direção — funciona em demos de cinco minutos. Em projeto real, três sessões depois você está corrigindo a mesma classe de erro pela quinta vez.
Skills mudam o jogo: você paga o custo cognitivo uma vez (escrever a skill) e colhe o benefício em cada sessão futura. É investimento, não improviso.
Matt documenta a evolução do projeto na newsletter dele. Vale a leitura — especialmente os posts em que ele explica por que uma skill nasceu (qual erro do agente ela tenta corrigir).
🔗 Newsletter: aihero.dev/s/skills-newsletter
🧩 Filosofia: small, composable, adaptable
Três adjetivos definem o projeto: small (pequenas), composable (composáveis) e adaptable (adaptáveis). Cada skill faz uma coisa, faz bem, e pode ser combinada com outras sem cerimônia.
Essa filosofia é uma resposta direta aos frameworks "tudo-em-um" que apareceram no ecossistema — GSD, BMAD-METHOD, Spec-Kit. Eles funcionam, mas vêm com um custo: você adota o processo deles inteiro ou nada.
✓ Skills (mp-skill)
- ✓ Pequenas — uma skill, um problema, ~200 linhas de Markdown
-
✓
Composáveis — use
/grill-me+/tdd+/handoffsem fricção - ✓ Adaptáveis — forke, edite, adicione sua regra, commite
- ✓ Opcionais — você escolhe quais instalar, ignora as outras
- ✓ Transparentes — abre o .md, lê, entende, ajusta
✗ Frameworks "tudo-em-um"
- ✗ Grandes — adoção exige reorganizar todo o projeto
- ✗ Monolíticos — partes acopladas, não dá pra usar só uma
- ✗ Opinionados — assumem um fluxo (PRD → tasks → code) que pode não ser o seu
- ✗ Caixa-preta — comportamento embutido em scripts/templates
- ✗ Lock-in — sair custa mais do que entrar
🔧 "Hack around with them"
Matt usa essa expressão no README: "these skills are meant to be hacked around with". Traduzindo: não trate como produto final. Trate como ponto de partida.
Cada skill é um arquivo Markdown de 100-300 linhas. Você abre, lê, ajusta o tom, troca um exemplo, adiciona uma seção específica do seu time, remove o que não usa. Sem build step, sem framework, sem permissão pra pedir.
Isso é o oposto do "instalei e segui o tutorial". É "trouxe pra dentro do meu projeto e fiz meu".
🗂️ Buckets: como skills são organizadas
O repositório agrupa skills em buckets (pastas) de acordo com maturidade e finalidade. Esse não é só um detalhe organizacional — define quais skills aparecem publicamente e quais ficam internas.
📁 Árvore de buckets
skills/ ├── engineering/ # daily code work — TDD, code review, debugging ├── productivity/ # daily non-code workflow — handoff, grill-me ├── misc/ # kept around but rarely used ├── personal/ # tied to author's setup, not promoted ├── in-progress/ # drafts not yet ready to ship └── deprecated/ # archived, kept for reference
As três primeiras (engineering, productivity, misc) são públicas: aparecem no README do projeto e na lista .claude-plugin/plugin.json. As três últimas (personal, in-progress, deprecated) ficam internas: existem no repo, mas não são oficialmente expostas como skills do plugin.
📋 Regra de promoção (do CLAUDE.md do mp-skill)
- Toda skill em engineering/, productivity/ ou misc/ precisa ter:
- • Entrada no
README.mdda raiz (linkando para oSKILL.md) - • Entrada no
.claude-plugin/plugin.json - • Entrada no
README.mddo próprio bucket (com descrição de uma linha)
- • Entrada no
- Skills em personal/, in-progress/, deprecated/ NÃO podem aparecer em nenhum desses dois lugares públicos.
Essa estrutura mantém o repositório honesto: o que está promovido foi testado e Matt usa de verdade; o que está em drafts é claramente identificado; o que foi descontinuado fica documentado mas não atrapalha quem está começando.
⚖️ Diferença vs GSD / BMAD / Spec-Kit
GSD (Get-Stuff-Done), BMAD-METHOD e Spec-Kit são frameworks populares pra "agentic coding". Eles funcionam — mas resolvem um problema diferente do que skills resolvem. Vale entender a diferença antes de escolher.
✓ mp-skill (skills compostas)
- ✓ Você escolhe quais skills usar em cada momento
- ✓ Convive com seu workflow atual sem reescrever nada
- ✓ Cada skill é independente — uma falha não derruba as outras
- ✓ Curva de adoção incremental: instala uma, usa, depois adiciona outra
- ✓ Saída fácil: deletar uma skill é apagar um arquivo
✗ Frameworks com processo embutido
- ✗ O framework escolhe a sequência de passos por você
- ✗ Exige reorganizar pastas, arquivos, agentes
- ✗ Componentes acoplados — quebrar um afeta os outros
- ✗ Curva de adoção tudo-ou-nada: aprende o método inteiro ou não usa
- ✗ Saída cara: remover o framework é refatoração
📊 Comparação por dimensão
| Dimensão | mp-skill | GSD / BMAD / Spec-Kit |
|---|---|---|
| Controle | Você decide quando cada skill entra | Framework dita a ordem dos passos |
| Flexibilidade | Alta — pega 1, ignora 9 | Baixa — pacote fechado |
| Curva | Incremental (skill por skill) | Íngreme (método completo de uma vez) |
| Customização | Editar Markdown | Reescrever templates / scripts |
| Acoplamento | Zero entre skills | Alto entre componentes |
| Quando faz sentido | Quando você já tem um jeito de trabalhar e quer reforçar | Quando você ainda não tem um processo e aceita adotar o deles |
Não é "um é melhor que o outro" — é problema diferente. Se você precisa de um processo completo de zero, framework. Se já tem processo e quer reforçar pontos fracos do agente, skills.
👥 Quem usa e para quê
Skills não são exclusivas de um perfil. O que muda é quais skills entram e em que ordem. Três perfis comuns:
🧑💻 Engenheiro solo
Side project, freela, startup early
- • Quer agente que não esqueça contexto entre sessões
- • Usa
/handoff,/grill-me,/tdd - • Adapta tudo pro estilo dele
👥 Time pequeno
2-8 devs, mesma codebase
- • Quer padronizar como o agente trabalha pra todo mundo
- • Forka o repo, commita as customizações
- • Cada PR de skill é revisado como código
🏢 Time enterprise
Compliance, code review formal
- • Skills viram política versionada ("agente NUNCA faz X")
- • Auditoria fica trivial: tudo em Markdown
- • Integra com revisão de PR existente
E a curva de adoção típica? Quase sempre segue a mesma ordem — instala o repo, testa uma skill, vê o ganho, adiciona a próxima. Em duas semanas, vira workflow.
⏱️ Timeline típica de adoção
Dia 1 — Instala o plugin
~10 minutos
Clona o repo, registra como plugin no Claude Code, confirma que /grill-me aparece. Ainda não usa — só verifica que carregou.
Dia 2-3 — Primeira skill: /grill-me
~30 minutos
Usa /grill-me antes de escrever código sério. Descobre que o agente faz perguntas que ele mesmo deveria ter feito antes. Vira hábito em 2-3 sessões.
Semana 1 — Adiciona /tdd
~1 hora pra internalizar
Usa /tdd em tarefas novas. Agente começa pelo teste, não pelo código. Para de "implementar e depois testar" — testa primeiro, sempre.
Semana 2 — Workflow completo
Já é hábito
Compõe: /grill-me → /tdd → /code-review → /handoff. Não pensa mais "qual skill?" — sabe.
📜 Licença e modelo de contribuição
O projeto é MIT. Tradução pragmática: você pode usar, copiar, modificar, distribuir, vender — em projeto pessoal, em empresa, em produto comercial. A única coisa exigida é manter o aviso de copyright e a licença no código.
Modelo de contribuição é fork-friendly. Matt aceita PRs, mas espera que cada PR seja focado: uma skill nova, uma correção numa skill existente, melhoria de docs. PRs gigantes ("reescrevi tudo") tendem a ser rejeitados — não por hostilidade, por filosofia: o projeto é pequeno de propósito.
🔀 Como abrir um PR contra mattpocock/skills
# 1. Fork no GitHub, depois: git clone https://github.com/SEU_USER/skills.git cd skills git checkout -b minha-skill # 2. Criar a skill em engineering/ ou productivity/ mkdir -p skills/engineering/minha-skill $EDITOR skills/engineering/minha-skill/SKILL.md # 3. Registrar nos dois lugares públicos obrigatórios: $EDITOR README.md # adicionar linha com link $EDITOR .claude-plugin/plugin.json # adicionar entrada $EDITOR skills/engineering/README.md # descrição de 1 linha no bucket # 4. Commit + push + PR git add . git commit -m "feat: add /minha-skill" git push origin minha-skill gh pr create --base main
💡 Antes de abrir PR
Leia o CONTRIBUTING.md (se existir) e dê uma olhada nos PRs recentes pra entender o que costuma ser aceito.
Skill nova precisa justificar qual failure mode ela resolve — esse é o critério principal. "Achei legal" não passa; "evita o agente esquecer X depois de Y" passa.
🇧🇷 mp-skill vs mattpocock/skills
Este repositório (mp-skill, mantido pelo inematds) é um fork ativo do mattpocock/skills com dois objetivos extras:
🌐 Tradução para PT-BR
Skills traduzidas pra português, mantendo nomes de comandos em inglês (/grill-me, /tdd) pra compatibilidade com o original.
Exemplos adaptados pra realidade BR quando faz sentido (datas, formatos, contexto cultural).
📚 Curso integrado
Esta página faz parte de um curso em 3 trilhas que ensina quando usar cada skill e como compor o workflow.
Trilha 1: Fundamentos · Trilha 2: mp-skill · Trilha 3: Workflow.
🔗 Quer o upstream original?
O repositório oficial do Matt está em github.com/mattpocock/skills. Skills novas e correções aparecem lá primeiro — o mp-skill faz rebase periódico pra puxar mudanças.
Se você quer contribuir com uma skill nova, abra contra o upstream, não contra o mp-skill. Aqui é só tradução + curso.
Em resumo: mp-skill = mattpocock/skills + PT-BR + curso. Mesma filosofia, mesmo conjunto base de skills, mesma estrutura de buckets — só com a barreira de idioma removida e material didático em volta.
📌 Resumo do Módulo
Próximo Módulo:
2.2 — Instalação e setup do mp-skill no Claude Code