🧩 Skills: ensinando um processo

Uma "skill" é um arquivo de texto que ensina o agente a fazer uma tarefa que você repete — como um manual de procedimento que uma empresa entrega a um funcionário novo.

Sem skill, você reexplica o mesmo processo toda vez. Com ela, escreve uma vez e o agente segue sozinho depois.

POP (procedimento operacional padrão), reuso, instrução persistente.

Cada skill vive numa pasta com nome próprio, contendo pelo menos um arquivo SKILL.md e, opcionalmente, subpastas de referência e scripts.

Entender a estrutura de pastas é o primeiro passo pra você conseguir criar (módulo 3.6) e organizar as suas próprias.

Pasta de skill, arquivo raiz, subpastas opcionais.

Front matter é um bloco curto no topo do arquivo, entre duas linhas ---, com pares como name: e description: — é o "rótulo" que o agente lê primeiro, antes de abrir o resto.

É esse rótulo que decide se a skill é chamada ou ignorada — assunto central do módulo 3.4.

Front matter, metadado, cabeçalho estruturado.

Documentos extras (dentro de uma subpasta, por exemplo references/) com o detalhe fino — tabelas grandes, listas de erros, exemplos longos — que o agente só abre se a tarefa exigir.

Manter o SKILL.md enxuto e empurrar detalhe pra referência é o que barateia cada skill — tema do módulo 3.2.

Referência, detalhe sob demanda, arquivo profundo.

Uma skill pode empacotar scripts prontos (Python, Node, shell) que o agente executa em vez de escrever código do zero toda vez.

Script embutido = mais rápido e mais confiável que "reinventar" a lógica a cada chamada.

Script embutido, execução determinística, WAT — tools.

Uma leitura guiada de uma skill instalada de verdade — front matter, corpo, referência — pra ver a anatomia funcionando junto.

Ver o exemplo completo fecha a teoria antes de você construir a sua no módulo 3.6.

Estudo de caso, anatomia aplicada.

Contexto é tudo que o agente "tem na cabeça" numa conversa — sua mensagem, o histórico, os arquivos abertos. É limitado, e quanto mais cheio, mais caro e mais lento fica cada resposta.

O carregamento progressivo existe justamente pra não lotar esse espaço com skills que não estão sendo usadas.

Contexto, janela de memória, custo por token.

Um token é um pedacinho de texto (perto de uma palavra) — a unidade que a IA usa pra "ler" e cobrar. No Nível 1, só o nome e a descrição de cada skill ficam sempre disponíveis, custando perto de 100 tokens cada.

É esse nível barato que permite o agente "saber que a skill existe" sem carregar ela inteira.

Token, Nível 1, sempre residente.

Quando o gatilho (módulo 3.4) bate, o agente abre o SKILL.md inteiro — o passo a passo completo — e só nesse momento aquele custo maior entra na conversa.

Entender esse "só quando precisa" explica por que ter muitas skills instaladas não deixa tudo lento.

Nível 2, carregamento sob demanda.

O último nível: arquivos de referência ou scripts que o agente só abre se, dentro da própria tarefa, precisar daquele detalhe específico.

É o que permite uma skill ter documentação enorme sem custar caro na maioria das vezes que é usada.

Nível 3, leitura condicional.

20 skills × ~100 tokens de Nível 1 dá perto de 2 mil tokens fixos — pouco, perto de uma janela de contexto que aguenta centenas de milhares.

Esse número concreto derruba o medo de "ter skill demais instalada".

Custo agregado, escala sem dor.

Empurrar tabelas grandes, listas de erro e exemplos longos pra referências, mantendo o SKILL.md como um "resumo executivo" curto.

É a diretriz que você aplica na hora de escrever a sua própria skill no módulo 3.6.

Corpo enxuto, referência funda, separação de responsabilidade.

Um nome curto e único, mais a frase de "gatilho" que diz quando aquela skill deve entrar em ação.

É o primeiro pedaço lido (Nível 1) — se estiver fraco, a skill nunca é chamada.

Nome, gatilho, identificação.

Uma frase que diz exatamente o que a skill entrega quando termina — "gera um relatório em CSV", não "ajuda com dados".

Objetivo vago produz execução vaga — a clareza aqui evita retrabalho.

Objetivo, critério de sucesso.

A sequência numerada de ações que o agente deve seguir — o coração da skill, equivalente ao "workflow" do framework WAT (Trilha 1).

É essa lista que garante repetibilidade — a mesma tarefa sai igual toda vez que a skill é chamada.

Passo a passo, repetibilidade, workflow.

A lista de arquivos extras (Nível 3, módulo 3.2) que a skill pode consultar quando o passo a passo não é suficiente.

Sem essa referência declarada, o agente não sabe que o detalhe existe pra consultar.

Referência declarada, apontador de leitura.

Restrições explícitas — o que a skill nunca deve fazer sem confirmação, ecoando as regras de segurança da Trilha 0.6.

Regra escrita evita que o agente "improvise" fora do que você autorizou.

Regra explícita, limite de autonomia.

Um espaço reservado pra anotar o que deu errado e ajustar o passo a passo — a skill não nasce perfeita, ela é refinada.

Prepara você pro módulo 3.7, onde essa melhoria contínua vira prática regular.

Ciclo de melhoria, refinamento iterativo.

O agente compara o seu pedido com as descrições (Nível 1) de todas as skills disponíveis, e escolhe a que casa melhor — igual um índice de assunto de um livro.

Entender esse casamento explica por que às vezes a skill certa não dispara.

Casamento de intenção, índice de descrições.

Uma boa descrição diz "quando usar" (gatilho) e "o que faz" (resultado), com palavras que a pessoa realmente digitaria — não jargão interno.

É a diferença entre uma skill que dispara sozinha e uma que fica esquecida.

Gatilho + resultado, linguagem do usuário.

Descrições genéricas como "ajuda com documentos" fazem a skill nunca ser escolhida, porque não distingue de nada mais.

Reconhecer esse erro é o primeiro passo pra corrigir skills que "existem mas nunca disparam".

Descrição genérica, ambiguidade.

Duas skills com descrições parecidas podem confundir o agente sobre qual escolher — sinal de que uma delas precisa de um gatilho mais específico.

Evita retrabalho quando você já tem várias skills instaladas (módulo 3.5).

Sobreposição de gatilho, desambiguação.

Pedir a mesma tarefa com frases diferentes ("faz um resumo", "resuma isso", "TL;DR disso") e ver se a skill dispara em todas.

É o teste real de qualidade de uma descrição — não basta funcionar com a frase que você escreveu primeiro.

Teste de variação, robustez do gatilho.

Uma skill pode ser chamada por um comando explícito (tipo /nome-da-skill) ou simplesmente por você descrever o que quer, em linguagem natural.

Saber as duas portas ajuda a escolher qual usar em cada momento — comando quando quer certeza, natural quando quer fluidez.

Comando explícito, disparo por linguagem natural.

Uma pasta .claude/skills/ dentro do próprio projeto guarda skills que só existem ali — específicas daquele repositório.

Skills de projeto podem viajar junto com o código (versionadas), então o time inteiro herda o mesmo processo.

Escopo de projeto, versionamento junto ao código.

Uma pasta na sua pasta pessoal (~ = "home") guarda skills disponíveis em qualquer projeto que você abrir, em qualquer computador seu.

É onde ficam os processos pessoais que você usa sempre, não importa em qual projeto está trabalhando.

Escopo global, pasta pessoal (home).

Regra simples: se o processo só faz sentido dentro desse projeto (ex.: deploy dessa app específica), vai em projeto; se é algo que você faz em qualquer lugar (ex.: gerar um resumo), vai em global.

Colocar no lugar errado é um dos erros mais comuns de quem está aprendendo skills — dificulta achar depois.

Critério de escopo, especificidade vs. generalidade.

Quando existe uma skill de projeto e uma global com o mesmo nome/propósito, a do projeto normalmente prevalece naquele contexto — ela é mais específica.

Evita surpresa quando você espera o comportamento global mas o projeto sobrepõe.

Precedência de escopo, sobreposição.

Como a pasta .claude/skills/ mora dentro do repositório, commitá-la faz todo colega que clona o projeto herdar as mesmas skills automaticamente.

Transforma "o jeito que eu faço" em "o jeito que o time faz" sem reunião nenhuma.

Skill versionada, padronização de time.

Com o tempo sua pasta global acumula skills — vale revisar de vez em quando, apagar as que não usa mais e afinar descrições confusas.

Prepara o terreno pro módulo 3.7, sobre manter as skills afiadas ao longo do tempo.

Manutenção, limpeza periódica.

Antes de escrever qualquer skill, escolha uma tarefa que você já repete manualmente hoje — é o melhor candidato pra virar skill.

Skill que resolve um problema real fica mais fácil de testar e de sentir o ganho.

Candidato a skill, tarefa repetitiva.

Um bloco pronto de comandos que cria a pasta e o arquivo inicial da skill, com o front matter já preenchido.

É literalmente o primeiro passo prático — colar e rodar tira o "medo da folha em branco".

Estrutura inicial, template base.

Preencher o corpo do SKILL.md seguindo o framework de 6 passos do módulo 3.3, com a tarefa escolhida no tópico 1.

É onde a teoria vira arquivo de verdade, testável.

Aplicação prática do framework.

Abrir uma conversa nova e pedir a tarefa em linguagem natural, verificando se a skill nova realmente é chamada.

É o "como verificar" do exercício — sem esse teste você não sabe se a skill funciona.

Verificação de disparo, teste manual.

Um roteiro de checagem: descrição vaga demais? pasta no lugar errado? nome duplicado com outra skill?

Frustração some quando você tem uma lista de suspeitos pra checar, em vez de adivinhar.

Diagnóstico, lista de checagem.

Com a skill funcionando, o próximo passo natural é usá-la de verdade algumas vezes e observar onde ela falha — abertura do módulo 3.7.

Fecha o ciclo prático desta trilha antes de partir pra manutenção contínua.

Uso real, observação, transição.

Toda skill começa imperfeita: você chama, observa onde travou, corrige o texto, chama de novo. Verdade sem marketing: costuma ficar boa só lá pela décima execução.

Sem essa expectativa, você desiste cedo demais achando que a primeira versão devia funcionar perfeita.

Ciclo iterativo, expectativa realista.

Manter nomes de arquivo, seções e identificadores estáveis dentro da skill, mesmo quando o conteúdo muda — evita quebrar referências cruzadas.

Skill que muda de estrutura toda hora fica difícil de manter e de debugar.

ID estável, referência cruzada.

Quando você já sabe que uma referência (Nível 3) vai ser necessária quase sempre, pode instruir a skill a carregá-la de cara, sem esperar o agente "descobrir" que precisa.

Economiza uma volta de ida-e-vinda quando o Nível 3 é praticamente garantido.

Pré-carregamento, antecipação de necessidade.

Um sub-agente é uma cópia do agente aberta pra cuidar de uma parte isolada da tarefa, devolvendo só o resumo — assim a skill pode delegar pedaços pesados sem lotar o contexto principal.

Skills complexas (ex.: pesquisa em muitos arquivos) ficam mais leves e rápidas usando esse truque.

Sub-agente, isolamento de contexto.

Olhando pelo framework WAT da Trilha 1: o SKILL.md é o "workflow" (o passo a passo), e os scripts/referências são as "tools" (as ferramentas que o workflow usa).

Amarra tudo que você aprendeu nas duas trilhas — skills não são um conceito isolado, são o WAT aplicado a um processo específico.

Mapeamento workflow/tools, integração de trilhas.

Com processos ensinados via skill, o próximo desafio é fazer essas automações rodarem fora do seu laptop — tema da Trilha 4, Deploy.

Fecha a Trilha 3 com clareza do próximo passo do curso.

Transição de trilha.