🧬 Anatomia de uma skill

Uma skill é, na prática, um arquivo de texto com instruções que você dá ao agente pra ele realizar uma tarefa sempre do mesmo jeito. O formato mais comum é um arquivo chamado SKILL.md (texto simples, em Markdown). Ele tem duas partes: um cabeçalho curto (o frontmatter) e o corpo, que são as instruções de verdade. Vamos abrir cada parte no tópico 2.

Por que isso importa tanto nesta trilha? Porque a skill é onde você codifica a sua maneira de trabalhar e devolve isso pro harness — sem precisar repetir tudo a cada conversa. Matt Pocock trata as skills como o coração do harness moderno: elas funcionam em vários agentes (Claude Code, Codex e outros) e se instalam com npx skills latest add. O erro comum de iniciante é confundir skill com "prompt longo que eu colo toda vez". Não: a skill fica salva, é versionável, dá pra distribuir pro time e — o ponto central deste módulo — ela pode ser acionada por você ou pela própria IA. Quem aperta o gatilho muda tudo.

Toda skill tem duas partes bem separadas. A primeira é o frontmatter: um bloquinho no topo, entre --- e ---, com dois campos essenciais — name (o nome curto) e description (uma frase dizendo o que a skill faz e quando usá-la). A segunda parte é o corpo: tudo depois do cabeçalho, em texto livre. É lá que mora o passo a passo, as regras, os exemplos.

A diferença prática entre as duas é crucial e volta no resto do módulo: o corpo só é lido quando a skill é acionada; já a description do frontmatter pode ficar "à vista" do modelo o tempo todo, pra ele decidir sozinho se chama a skill. Nas palavras de Pocock, "toda skill vaza a sua description na janela de contexto". Ou seja: o rótulo custa contexto mesmo quando a skill não é usada; o corpo, não. Guarde isso — é a semente do módulo 3.2 ("custo de contexto da skill"). O erro comum aqui é escrever uma description gigante "pra garantir": ela vira peso morto no contexto. Boa description é curta e diz exatamente o gatilho.

---
name: commit-conventional
description: Cria a mensagem de commit no padrao Conventional Commits
  a partir das mudancas em stage. Use quando o usuario pedir "commita",
  "faz o commit" ou "gera a mensagem de commit".
---

# Commit Conventional

Quando acionada, faca nesta ordem:

1. Rode `git diff --staged` e leia o que mudou.
2. Escolha o tipo: feat | fix | docs | refactor | test | chore.
3. Escreva o titulo: `tipo(escopo): resumo no imperativo` (ate 72 chars).
4. No corpo, explique o PORQUE da mudanca em 1-3 linhas (nao o "o que").
5. Se houver breaking change, adicione `BREAKING CHANGE:` no rodape.
6. Mostre a mensagem final e PERGUNTE antes de rodar `git commit`.

Regras:
- Nunca invente arquivos que nao estao no diff.
- Portugues, voz imperativa, sem emoji no titulo.

Exemplo real de SKILL.md: entre os --- está o frontmatter (rótulo); abaixo, o corpo (o procedimento).

O primeiro dos dois tipos de skill é a procedure. A regra de ouro: quem aciona é você. Você invoca a skill de propósito — digitando o nome dela, escolhendo no menu, rodando um comando — e ela faz o modelo "se comportar de um jeito" que você definiu. Nas palavras de Pocock, procedures são skills que "fazem o modelo se comportar de um jeito" e que você dispara. Exemplos do dia a dia dele: a skill grill-me (que vira o modelo num entrevistador), a two-PRD e a to-issues — ele encadeia as três na ordem que ele quer.

Por que isso importa? Porque com procedures você fica no volante. Você decide qual procedimento entra, quando entra e em que sequência. Não há surpresa: o modelo não puxa nada por conta própria. Pocock é explícito sobre preferir esse modo: "I know my skills, I don't want to delegate my thinking" — eu conheço minhas skills, não quero delegar meu pensamento. O erro comum é achar que isso é "trabalho a mais". Na verdade é controle: você troca um pouco de automação por previsibilidade total, e ainda evita que descrições fiquem vazando no contexto (tema do 3.2).

O segundo tipo é a ability. Aqui a regra de ouro vira do avesso: quem aciona é o modelo. Ele lê a description das skills disponíveis e, quando "acha" que uma se encaixa na tarefa, a puxa sozinho — sem você pedir. O exemplo que Pocock dá é uma skill de coding standards (padrões de código): o modelo a invoca automaticamente quando vai escrever React, porque a descrição diz algo como "use ao escrever componentes React". A skill então lembra o modelo de regras como "não deve usar useEffect, deve usar outra coisa".

A vantagem é a automação: a regra certa entra na hora certa, sem você lembrar de invocar. A desvantagem — e é por isso que Pocock pesa a mão — é que o modelo decide, e cada ability precisa manter sua description à vista pra ser "encontrável". Como vimos, isso vaza contexto: 100 skills viram 100 descrições penduradas na janela. Outra escola, a Superpowers (do projeto Obra), abraça justamente esse modo — modelo no controle. Pocock prefere o oposto. O erro comum é encher o setup de abilities "porque é automático" e descobrir tarde que o contexto ficou poluído e o comportamento, imprevisível.

Agora junte tudo. Procedure e ability não são duas coisas diferentes — são duas portas de entrada pra mesma skill. O conteúdo (o corpo) pode ser idêntico; o que muda é quem tem a chave. Por isso Pocock fala em "dois tipos de skill" mas, no fundo, é uma decisão de design por skill: deixo o modelo invocar (ability) ou tranco essa porta e só eu invoco (procedure)? O ajuste técnico que tranca a porta do modelo é o disable model invocation — você o vê em detalhe no módulo 3.2.

A consequência prática é grande. Toda porta de modelo aberta tem um custo: a description daquela skill fica pendurada no contexto pra o modelo poder encontrá-la. Trancar a porta (procedure pura) zera esse custo e te devolve previsibilidade. Pocock, por preferir estar "no volante", deixa a maioria das portas-do-modelo trancadas e mantém o conhecimento com o humano — ele cita a skill engineering zoom out como uma das que ele esconde do modelo. Não é regra universal: é o estilo dele. O erro comum é nem perceber que existe essa escolha — a pessoa instala 50 skills, todas como ability, e o contexto vira uma feira.

Fechando: a escolha não é "qual é melhor", é "quem deve decidir nesta skill". Use ability quando a regra é genérica, sempre desejável e barata de errar (ex.: padrões de estilo que sempre valem) — vale a comodidade de o modelo puxar sozinho. Use procedure quando você quer estar no volante: tarefas de raciocínio, encadeamento de etapas, ou qualquer coisa onde a previsibilidade importa mais que a automação. Pocock encadeia grill-me → two-PRD → to-issues como procedures justamente por isso. E lembre do custo: cada ability mantém sua description vazando no contexto, então trancar portas (procedure) também é higiene. Use o guia abaixo quando for criar ou auditar uma skill:

Pra cada skill, pergunte: QUEM deve apertar o gatilho?

ESCOLHA ABILITY (modelo invoca) se:
[ ] a regra vale quase sempre que o tema aparece (ex.: padroes de React)
[ ] errar o momento e barato
[ ] voce QUER automacao, nao controle fino

ESCOLHA PROCEDURE (voce invoca) se:
[ ] e raciocinio / planejamento / etapas encadeadas
[ ] previsibilidade > automacao ("quero estar no volante")
[ ] a description ocupando contexto te incomoda -> disable model invocation: true

Regra de bolso (estilo Pocock): na duvida, PROCEDURE.
"I know my skills, I don't want to delegate my thinking."