Vasculhei o código dos skills do Matt: ele escreve skills sob quatro leis (e flagrei ele apagando o caveman)

Resumo de 30 segundos

Um skill bom tem um único alvo: previsibilidade — na mesma situação, a IA percorre sempre o mesmo processo. As quatro leis servem a ele, cada uma com seu contra-exemplo:

Como dispara: o modelo decide sozinho quando usar (e paga ocupando contexto pra sempre), ou só dispara quando você chama pelo nome. Errar = contexto ocupado à toa.

Quanto entra: no SKILL.md fica só o que toda rota usa; o resto desce pra arquivo externo. Contra-exemplos: sprawl (inchaço), sediment (sedimentação).

Que palavra usar: pega um conceito que a IA já tem na cabeça como leading word (palavra-guia), uma palavra ancora um bloco de comportamento. Contra-exemplos: no-op (linha que não faz nada), duplication (repetição).

Como termina: cada passo ganha um completion criterion (critério de conclusão) verificável. Contra-exemplo: sair antes de terminar.

As quatro vêm do writing-great-skills do Matt Pocock; os quatro contra-exemplos são todos casos reais, garimpados das revisões dele mesmo.

Vasculhei o código dos skills do Matt do início ao fim

Mesmo / dado, tem skill que termina o serviço toda vez e tem skill que ora vai ora não. A diferença não é sorte. É como foi escrito.

Ninguém tem tempo de catar código de skill — eu cataei. Mirei no Matt Pocock, o cara que montou um conjunto inteiro de skills de colaboração com IA. Ele escreveu uma coisa esperta: um skill que ensina a escrever skill (writing-great-skills). Li esse, somei o código-fonte e o histórico de commits de dezenas de skills dele, e tirei quatro leis.

Quatro, só. Mas cada uma vem com um contra-exemplo — e nenhum inventado, todos garimpados dos commits do próprio Matt, erros que ele cometeu com a mão e corrigiu com a mão. Se até ele teve que voltar pra arrumar, o tropeço é real.

Aprenda as quatro: escreve skill com menos tropeço; e, se nunca escrever um, ainda rouba a manha dele de arrancar comportamento previsível de uma IA aleatória.

Skill bom tem um critério só: previsibilidade

O modelo é aleatório — a mesma frase, perguntada duas vezes, pode render respostas diferentes. O sentido inteiro de um skill é espremer determinismo dessa máquina aleatória: fazer ela percorrer o mesmo processo toda vez.

“A skill exists to wrangle determinism out of a stochastic system.” — Matt, writing-great-skills

Repare: processo, não saída. Um brainstorm tem que cuspir ideias diferentes a cada vez, mas a forma de conduzir o brainstorm precisa ser estável.

Pra julgar um skill, é esse o único critério: previsibilidade (predictability). As quatro leis abaixo servem todas a ele.

Lei 1 · Como dispara: você chama, ou o modelo decide sozinho?

A primeira decisão a bater o martelo ao escrever um skill: quem decide a hora de usar — o modelo sozinho, ou só você quando chama pelo nome? Tecnicamente é uma chave só: escrever ou não a description.

Disparo pelo modelo (model-invoked, com description): a IA enxerga o skill e decide sozinha quando usar. O custo é que essa description fica pendurada no contexto a cada turno — gasta token, gasta atenção. Isso é carga de contexto.
Disparo pelo usuário (user-invoked, com disable-model-invocation): a description some, o modelo não vê o skill, ele só dispara quando você digita o nome. Não custa um token de contexto à IA, mas o custo passa pra você: você tem que lembrar que ele existe. Isso é carga cognitiva.

A regra: só deixe disparar sozinho quando o modelo (ou outro skill) precisa de fato alcançá-lo; senão, manual, e leve a carga de contexto zerada de graça.

Contra-exemplo: um skill que na prática você só vai chamar à mão, mas que mantém a description ocupando seu contexto a cada turno por nada.

Caso real: esse trade-off o próprio Matt pesou de ida e volta. A chave disable-model-invocation do grill-with-docs ele primeiro apagou — soltou o skill pro disparo automático; na versão mais recente, voltou a colocá-la, de volta pro manual puro. A mesma chave, apagada e readicionada. Sinal de que “automático ou manual” é uma decisão que exige peso real, não um clique qualquer.

Como você usa: comece manual, poupe contexto primeiro; só dê uma description quando você de fato precisar que o modelo julgue sozinho “agora é hora de usar isto”. Autocheck de uma frase: “quem precisa alcançar este skill?” Se a resposta for “só eu”, manual.

Skill manual em excesso e você mesmo não dá conta de lembrar — aí estourou a carga cognitiva. A saída é escrever outro skill de roteamento: um skill manual que só lista os outros skills e diz quando usar qual. O ask-matt do Matt faz exatamente isso.

Lei 2 · Quanto entra: no SKILL.md fica só o que “toda rota usa”

Escada de informação: o que toda rota de uso aproveita vai no corpo do SKILL.md; o que só serve em certos casos desce pra um arquivo externo separado, deixando no corpo só uma linha “vá ver aquilo quando precisar”. O objetivo é manter o topo sempre limpo — empilhe coisa demais e a ação que a IA realmente deveria executar afoga no meio.

Dois contra-exemplos, ambos com nome:

Inchaço (sprawl): enfia tudo num arquivo só, que vai ficando mais e mais longo. Mesmo que cada linha esteja certa e nenhuma se repita, o “longo” por si já é a doença — a IA tem que atravessar um monte de texto antes de alcançar o serviço.
Sedimentação (sediment): conteúdo velho só entra, nunca sai, vai assentando em camadas, e quem vem depois precisa escavar feito arqueólogo pra achar a parte que ainda vale.

Caso real: o grill-with-docs começou como um monólito gordo — lógica de sabatina, formato de documento, modelo de ADR, tudo num arquivo só. O Matt partiu em três: a metade da sabatina virou grilling, a metade de escrever documento virou domain-modeling, e até os arquivos de formato do ADR e do glossário desceram pro domain-modeling; o grill-with-docs sobrou como uma casca fina de uma linha, costurando os dois. Isso é usar a escada de informação pra emagrecer um skill inchado.

Como você usa: termine de escrever e volte pra cortar. A cada linha, pergunte “isto toda rota usa?” Se não, ou desce pra externo, ou some na hora. Uma intuição grosseira mas que funciona — quanto mais curto o SKILL.md, mais perto só do tronco, normalmente mais confiável.

Lei 3 · Que palavra usar: pega um conceito que a IA já tem na cabeça

Esta é a mais contraintuitiva. Eu mesmo levei um tempo pra cair a ficha.

Palavra-guia (leading word): um conceito que a IA já aprendeu no treino, com uma carga inteira de associações embutida. Não se restringe a termo técnico — jogo, militar, medicina, ditado do dia a dia, tudo vale, desde que a IA pegue de cara. Escreva no skill e, sem você explicar nada, ela puxa o bloco de comportamento inteiro.

Exemplos (todos emprestados, nenhum inventado pelo Matt):

fog of war (névoa de guerra, de jogo/militar) → a IA entende na hora “à frente está turvo, aja com a informação parcial que tem na mão”.
tracer bullets (balas traçantes, de O Programador Pragmático) → “fure primeiro um caminho ponta a ponta bem fino, acerte a direção, depois acrescente o resto”.
triage (triagem, do pronto-socorro), caveman (homem das cavernas = falar pouco), grilling (sabatinar) — pega o conceito pronto e usa.

Onde achar: primeiro diga claro o comportamento que você quer, depois pergunte de trás pra frente “qual palavra ou referência pronta já significa exatamente isto?” Garimpe em ditados, clássicos, metodologias, jogo e militar, medicina e esporte. O que a IA leu é o seu dicionário.

Como verificar — o teste do no-op: escreva a palavra sozinha, sem explicação, e a IA já fez o que você queria? Conseguiu = palavra-guia de verdade, aproveitando o conhecimento prévio da IA de graça; ainda precisou de meia página de explicação pra ela entender = a palavra não está puxando peso, caiu nos contra-exemplos:

Linha que não faz nada (no-op): escrita, mas que a IA já faria de qualquer jeito. Tipo “be thorough” (seja minucioso) — a IA já é meio minuciosa por padrão, essa linha é quase nada. O conserto não é acrescentar explicação, é trocar por uma palavra mais dura: “be thorough” → “relentless” (implacável).
Repetição (duplication): o mesmo sentido escrito várias vezes. Custa manutenção (mudou um lugar, tem que mudar todos) e ainda infla o peso desse sentido aos olhos da IA.

Caso real: nesses dois o Matt botou a faca. Ele apertou o skill review, e a mensagem de commit diz preto no branco “single-sourced rules, no-op cuts” — juntou regras repetidas, cortou linhas que não faziam nada. Chegou a voltar e atacar o próprio writing-great-skills, num commit feito só pra “caçar no-op até o nível da frase”.

Como você usa: não descreva o comportamento com uma frase inteira, ache uma palavra pronta pra fisgá-lo; depois pegue cada adjetivo e advérbio e faça o teste do no-op — apagado isto, o comportamento da IA muda? O que não muda é água, corta.

Lei 4 · Como termina: cada passo precisa de um critério de conclusão verificável

Skill costuma ser uma sequência de passos. Se um passo de fato terminou ou não, quem decide é o critério de conclusão (completion criterion).

Um bom critério de conclusão tem dois cuidados: um, ser verificável — a IA consegue julgar objetivamente “terminei” ou “não terminei”, sem decidir no sentimento; dois, ser exaustivo quando cabe — tipo “cada modelo alterado tem que ser explicado”, em vez de um vago “faça uma lista de mudanças”.

Contra-exemplo · sair antes de terminar (premature completion): o critério de conclusão fica turvo (“chegar a um acordo”, “entender direito”), a IA não alcança uma fronteira nítida, e a atenção dela escorrega de “terminar o serviço” pra “fechar logo isto” — pula pro passo seguinte sem ter terminado de verdade.

Tem um mecanismo aliado: se a IA enxerga quais passos ainda estão na fila à frente, aquela força de “termina logo e segue” puxa mais forte. Um dos remédios é esconder os passos seguintes em outro skill, pra que o passo atual não fique de olho na pressa.

Caso real: o movimento de assinatura do grilling (a metade da sabatina, partida do grill-with-docs) é perguntar uma de cada vez, e só perguntar a próxima quando você responde a atual — a palavra-guia dele é justamente “relentless” (implacável). Partir sabatina e escrita de documento em dois skills foi pela mesma razão: não deixar a IA, enquanto te sabatina, ficar pensando “termino as perguntas e corro pra escrever o documento”, porque aí ela encerra na correria. Separado, o passo da sabatina sobra só sabatina.

Como você usa: escreva a condição de fechamento de cada passo como verificável e, de preferência, exaustiva (“cada X…”, em vez de “tá quase”); se notar a IA largando na frente sempre no mesmo passo, mude os passos seguintes pra outro skill.

Com as quatro leis, olhe uma coisa estranha: por que ele apagou o caveman?

Pega as quatro e leva pra uma cena de crime de verdade.

O caveman do nosso primeiro texto (faça a IA calar a boca e ir direto ao ponto) não está mais no repositório original do Matt — foi apagado. O registro da remoção é seco:

No fim de maio, ele apagou o SKILL.md inteiro do caveman, com a mensagem de commit numa linha só: “streamline” (enxugar os skills de produtividade).
Quinze dias depois, limpou as referências que sobraram no README e na lista de plugins.
Nenhum skill novo veio assumir o posto. Apagou e pronto.

Por quê? Mede com as quatro e fica claro: o caveman é um skill manual, ocupa a sua carga cognitiva — você tem que lembrar que ele existe. Só que o tantinho que ele faz (poupar palavra, cortar formalidade) se consegue com uma única instrução, ou com um estilo de saída global, e não vale ocupar sozinho uma “casa que você tem que lembrar”. Apagá-lo é podar no nível do conjunto inteiro de skills, cortar uma carga que não compensa.

Uma ressalva honesta: a mensagem de commit do Matt só escreveu “streamline”, não desenvolveu — esta leitura é minha, feita com este framework. Mas o framework consegue dar uma explicação que se sustenta sozinha — e é exatamente pra isso que ele serve.

As quatro leis não são só uma lista pra escrever skill. Elas também explicam, no mundo real, por que um skill vive e por que um skill morre.

Cartão de consulta rápida

Lei	O que fazer	Contra-exemplo	Autocheck de uma frase
Como dispara	Só leve `description` se precisa ser alcançado pelo modelo; senão, manual	Contexto ocupado à toa	”Este skill, quem precisa alcançar?”
Quanto entra	No SKILL.md só o que toda rota usa, o resto desce pra externo	Inchaço / sedimentação	”Esta linha toda rota usa?”
Que palavra usar	Pega um conceito pronto da IA como palavra-guia, uma palavra ancora um bloco de comportamento	Linha que não faz nada / repetição	”Apagada esta linha, o comportamento da IA muda?”
Como termina	Cada passo ganha um critério de conclusão verificável e exaustivo	Sair antes de terminar	”Este passo terminou? A IA julga objetivamente?”

Critério único: previsibilidade — na mesma situação, a IA percorre sempre o mesmo processo. As quatro leis servem todas a ele.

Pra fechar

Quatro leis, pra usar direto ao escrever skill. E mesmo que você nunca vá escrever um skill na vida, a linha de raciocínio por trás — “como arrancar determinismo de uma IA aleatória” — já te faz tocar IA com mais firmeza no dia a dia. No fundo, é esse o verdadeiro proveito de roubar de quem é bom: você não leva umas regras, leva o jeito de julgar que está na cabeça dele.

Fonte: este texto destrincha o writing-great-skills do Matt Pocock (e seu GLOSSARY.md), repositório mattpocock/skills, licença MIT, versão 6eeb81b. Os “casos reais” do texto são todos rastreáveis no histórico de commits do repositório (links de commit anexados).

Mesma série: primeiro · caveman · segundo · grill-with-docs