Skill

Ela lê por partes, e cada parte tem a sua hora

Na estante de manuais, você lê a lombada e só tira da prateleira o que vai usar. Aqui, na largada entram só as etiquetas. O passo a passo abre quando o pedido bate com uma delas. O anexo abre só se o passo a passo mandar consultar. Por isso uma skill pode ser longa sem pesar. Avance.

O mesmo procedimento, colado nas instruções ou guardado como skill

Imagine o procedimento de fechamento contábil impresso no verso de todo papel da empresa: até o bilhete da copa viria com doze passos. Abaixo, texto idêntico, palavra por palavra. A diferença é o lugar, e ela aparece num pedido que não tem nada a ver com ele. Colado nas instruções, o procedimento é lido sempre, e aplicado onde não devia.

Pedido: “Escreva um e-mail curto avisando a unidade que o prazo mudou.”

Guardar no lugar certo não melhora o texto. Melhora quando ele é usado.

A skill não é um texto: é uma pasta com gavetas

Pense no kit que o RH entrega na admissão: a folha de instruções, a norma, o formulário em branco, cada um no seu envelope. Na skill, só a primeira gaveta é obrigatória: o arquivo SKILL.md, um texto simples (é o que o .md no fim quer dizer). As outras levam junto o material que a sua área já tem: a norma, o modelo, uma conta que não pode variar. Gaveta vazia não é skill incompleta: é skill do tamanho do problema. Troque de skill e clique nas gavetas.

Das quatro skills de exemplo, nenhuma usa a gaveta de scripts. Nas tarefas de escritório ela é rara; em skill de quem programa, é comum. E o anexo pode ser grande: ele só é lido quando o passo a passo manda. Não resuma a norma antes de anexar; é no resumo que a exceção some.

A gaveta depende do verbo, não do documento

Um mesmo contrato antigo pode servir de consulta para o jurídico e de modelo para a secretária: o que decide onde ele fica é o que se faz com ele. Ela lê para decidir, copia para produzir, roda para calcular, ou aquilo é o próprio método? O mesmo arquivo pode cair em gavetas diferentes conforme o uso.

Etiqueta vaga é procedimento perfeito que nunca abre

Na recepção, o atendente encaminha pela plaquinha de cada sala: se a plaquinha diz só “Sala 3”, ninguém sabe que é ali que se resolve o reembolso. A descrição (o campo “description”, no topo do arquivo) é o que ela lê para decidir se a skill entra. Ela precisa dizer o que faz e quando usar, com as palavras que você usaria no pedido. Escreva a sua e teste com um pedido: a simulação procura as palavras em comum, que é uma versão tosca do que a IA faz.

Escreva a etiqueta antes do conteúdo. Quem escreve o passo a passo primeiro acaba com uma etiqueta que descreve o texto (“procedimento de cotação”) e não o momento (“quando o pedido for comparar propostas”).

Skill, instrução, prompt salvo e comando

No escritório há o regulamento que vale sempre, o modelo de e-mail que você copia quando lembra, e o formulário que só sai quando alguém pede no balcão: tudo é papel, muda quem decide usar. Aqui, o prompt salvo é um pedido pronto que você guarda para colar de novo. Os quatro guardam texto. O que muda é quem puxa o gatilho, e quando.

E o projeto? Ele guarda o quê; a skill guarda o como

O teste é a frase: ela descreve o trabalho de agora ou manda fazer alguma coisa? A que descreve vai para o projeto; a que manda fazer, para a skill.

Onde cada coisa mora, no mapa completo: onde a regra mora.

A citação do item é o que prova que ela abriu o anexo

Quem diz que conferiu o estoque mostra a contagem com o código de cada item; “está tudo certo” não prova que alguém foi ao depósito. Aqui, uma contratação de acabamento especial, estimada em R$ 3.200. Pela regra geral, abaixo de cinco mil, basta uma proposta e o comprador aprova. Pelo anexo de exceções, que ninguém abre há dois anos, é outra coisa. Nenhuma linha do passo a passo mudou entre os dois lados.

De onde saiu cada regra que você acabou de aplicar? Diga a seção ou o item do documento em cada uma. Se alguma coisa você respondeu sem estar no documento, diga isso com todas as letras.

Ela escreve bem com ou sem o anexo aberto. Um código de item só existe dentro do documento: é por isso que a citação prova e a resposta bonita não. Mais em resposta ancorada.

O pior jeito de fazer uma skill é sentar para escrever uma skill

A melhor receita da cozinha industrial não nasce numa reunião: nasce do cozinheiro que fez o prato, acertou o sal e só depois escreveu. A sua área já escreveu quase todos os procedimentos: norma, checklist, o passo a passo que você explicou para quem entrou. O caminho que funciona é fazer a tarefa uma vez, junto com a IA, e só depois empacotar o que deu certo.

Empacote tudo que fizemos nesta conversa numa skill.
Antes de escrever, me mostre em lista: quais foram as correções que eu fiz ao longo da conversa, e quais regras saem de cada uma. Quero conferir se você pegou todas.
Depois monte a skill assim:
1. Um nome curto, em minúsculas e com hífen, dizendo a tarefa.
2. Uma descrição que diga o que ela faz E quando usar, incluindo as palavras que eu usaria no dia a dia para pedir isso.
3. O passo a passo na ordem em que a tarefa acontece de verdade, com as exceções no lugar certo.
4. Uma seção final com os erros que essa tarefa costuma ter.
Não invente regra que eu não disse. Se faltar alguma decisão, pergunte antes de escrever.

Uma skill de confiança diz onde para, o que não muda e o que não é dela

Um bom procedimento operacional diz, além dos passos, onde parar para a assinatura do chefe, o que nunca se muda e o que é decisão de outro setor. Na skill, o passo a passo diz como fazer. Uma skill que roda toda semana precisa de mais quatro partes, e é nelas que moram as correções que você não quer fazer de novo. Clique em cada parte.

Quando a saída vem torta, pergunte por quê antes de mandar corrigir

O reflexo é mandar consertar. Pergunte antes o motivo, e só peça análise: a resposta mostra de qual parte da skill o erro saiu. Aí a correção vai para essa parte, com o que você esperava e o que veio, em vez de virar mais uma regra solta no fim.

1 · Só o diagnóstico
Por que você fez isto aqui: [cole o trecho da saída]? Não corrija nada ainda. Só analise: qual parte da skill levou a esse resultado?

2 · A correção
Eu esperava [o que você esperava]. Veio [o que veio]. Atualize a skill para isso não se repetir, e me mostre a linha que mudou.

Se você usa a IA numa pasta: a skill mora numa pasta do projeto e, quando a pasta já tem a receita num arquivo, aponta para ele em vez de copiar os passos. Como ela conversa com o manual e a memória da pasta está na família Claude Code.

Três ideias

Skill

Um procedimento guardado fora da conversa, com nome, etiqueta e passo a passo, aberto quando a tarefa bate com a etiqueta. Também aparece como habilidade.

Etiqueta

A descrição de quando usar. É a única parte que fica sempre à vista, e é por ela que a skill é chamada ou não.

Gaveta

Cada pasta dentro da skill: referências para decidir, modelos para produzir, scripts para calcular.

Comando

O mesmo conteúdo de uma skill, com outro gatilho: só roda quando você chama pelo nome.

Simplificação didática. O nome do recurso, o formato do arquivo e o lugar onde ele fica guardado mudam entre ferramentas e versões; nome, etiqueta, passo a passo e gavetas continuam. As skills, a política e os valores são exemplos inventados. Família assistente; irmãs: resposta ancorada, onde a regra mora, time de assistentes.