Uma skill do Claude Code é uma pasta com instruções que o agente carrega apenas quando a tarefa correspondente aparece na conversa. O arquivo central, chamado SKILL.md, guarda o procedimento completo de uma tarefa repetitiva: as regras, as fórmulas, o formato de saída e os exemplos que você redigitaria num prompt a cada vez.
Este guia mostra onde a skill fica no projeto, como o Claude decide acioná-la, em que ela difere do CLAUDE.md, dos subagentes, do MCP e dos hooks, e o ciclo de construção que funciona na prática: uma versão mínima, um teste com o caso real e a regra que corrige cada falha observada. O exemplo que acompanha o texto é uma skill que calcula e redige a variação de uma série mensal do IPCA.
Esse fluxo resume o mecanismo inteiro: a skill fica dormindo no projeto e só entra no contexto quando o pedido bate com a descrição dela. As seções a seguir explicam cada etapa e mostram como uma skill sai do rascunho e chega à versão que o time usa toda semana.
Quer montar skills como essa no seu trabalho?
Na Imersão Claude Code para economistas, administradores e contadores você constrói, com acompanhamento, as skills, os agentes e as rotinas do seu dia a dia, da instalação ao procedimento rodando no seu projeto.
O que vai dentro do SKILL.md
O SKILL.md é um markdown comum que abre com um frontmatter, o cabeçalho YAML delimitado por três traços no topo do arquivo, com dois campos principais: name, o nome pelo qual a skill é chamada, e description, o texto que diz ao Claude quando usá-la. Depois do cabeçalho vem o corpo com as instruções, escritas como você escreveria um prompt caprichado.
--- name: variacao description: Use quando o usuário pedir análise de variação de uma série mensal em CSV. ---
A diferença para um prompt colado na conversa está no carregamento. De cada skill instalada, o Claude conhece de antemão apenas o name e a description, que custam poucas dezenas de tokens; o corpo, que pode ter centenas de linhas, só entra no contexto quando a skill é acionada. Esse mecanismo se chama progressive disclosure e é o que permite acumular dezenas de procedimentos no projeto sem inchar todas as conversas.
A pasta da skill também aceita arquivos auxiliares, como um script que a skill manda executar, uma tabela de referência ou um template de relatório, que o Claude lê sob demanda quando as instruções apontam para eles. Para o exemplo deste guia, o SKILL.md sozinho resolve.
Onde a skill mora: os três escopos
O lugar da pasta define o escopo da skill, isto é, quem consegue enxergá-la e usá-la. São três níveis: a skill de projeto vive em .claude/skills/ na raiz do repositório e vale para todo o time; a pessoal vive em ~/.claude/skills/ na sua máquina e acompanha você em qualquer projeto; a de plugin chega instalada junto com um plugin do Claude Code.
Para procedimentos do trabalho, como calcular o acumulado do IPCA ou formatar o relatório da casa, o nível de projeto é o certo, porque a skill entra no repositório e chega a todo o time num git pull. A pasta pessoal serve para hábitos seus que valem em qualquer projeto, como um formato preferido de mensagem de commit.
Como o Claude decide acionar a skill
Há dois caminhos. O explícito usa um slash command, o comando iniciado por barra que você digita na conversa: /variacao dados/ipca.csv carrega o corpo da skill e executa. O implícito dispensa o comando: você pede em linguagem natural ("calcula as variações do IPCA desse CSV") e o Claude decide sozinho acionar a skill, comparando o pedido com a description de cada uma instalada.
O caminho implícito depende inteiramente da description, porque ela é o único texto que o Claude lê para decidir se a skill serve para o pedido. Escreva a description como um gatilho: comece com "Use quando…", diga em quais pedidos ela se aplica e, quando houver risco de confusão, diga também quando não usar. Uma description vaga produz dois defeitos simétricos, a skill que nunca dispara e a skill que dispara em pedido errado, e o segundo aparece na prática mais adiante neste guia.
Skill, CLAUDE.md, subagente, MCP e hook: qual peça para qual problema
Todas essas peças respondem à mesma pergunta, "como faço o Claude se comportar do meu jeito?", e por isso se confundem. A distinção fica clara ao separar quando a instrução entra no contexto, quem executa o trabalho e o que a peça adiciona.
A comparação mais frequente é com o CLAUDE.md, o arquivo de contexto fixo do projeto. A regra prática: o que vale para toda conversa vai no CLAUDE.md; o que vale para uma tarefa vai numa skill. "CSVs usam ; e ," é convenção permanente; "como calcular e redigir a variação de uma série" é procedimento de tarefa, que no CLAUDE.md ocuparia contexto até numa conversa sobre gráficos.
| Peça | O que é | Quando age | Use para |
|---|---|---|---|
| CLAUDE.md | Contexto fixo do projeto | Sempre, em toda conversa | Convenções permanentes e curtas |
| Skill | Procedimento carregado sob demanda | Quando a tarefa correspondente aparece | Tarefas repetitivas com regras estáveis |
| Subagente | Outro Claude, com contexto próprio | Quando o principal delega uma tarefa | Trabalho longo que poluiria a conversa principal |
| MCP | Conexão com serviço externo | Quando o Claude chama a ferramenta | Dar acesso a dados e ações fora da máquina |
| Hook | Comando configurado nas settings | Sempre que o evento ocorre, sem decisão do modelo | Garantias que não podem depender do modelo "lembrar" |
As cinco peças que moldam o comportamento do Claude Code, lado a lado. Elaborado por analisemacro.com.br.
Dois contrastes merecem uma frase a mais. O subagente não ensina nada: ele delega, porque é um segundo Claude com janela de contexto própria, útil quando uma subtarefa geraria tanto resultado intermediário que afogaria a conversa principal. A skill responde "como fazer"; o subagente responde "quem faz", e os dois se combinam, já que um subagente pode acionar uma skill.
O hook é o oposto da skill no quesito confiança. A skill depende de o modelo decidir usá-la; o hook executa sempre que o evento configurado acontece, sem consultar o modelo. Quando a regra é inegociável, como rodar o linter depois de toda edição de arquivo, use hook; quando é procedimento que pede julgamento, use skill.
Escolher a tarefa certa antes de escrever
Construir uma skill começa antes do SKILL.md: começa escolhendo a tarefa, porque nem toda tarefa rende uma boa skill e o tempo gasto numa skill que ninguém aciona é desperdiçado. Três critérios filtram as candidatas: a tarefa é repetitiva (volta toda semana ou todo mês com o mesmo roteiro), tem regras estáveis (fórmula, formato e proibições cabem num texto curto) e é verificável (dá para olhar a saída e dizer se está certa).
Na rotina de um analista, quatro candidatas aparecem rápido: conferir se os números de um texto batem com o CSV de origem, resumir uma DRE em cinco linhas padronizadas, calcular as variações de uma série mensal e aplicar a revisão de estilo da casa. Todas passam no primeiro critério, mas a análise de variações vence nos outros dois: as regras cabem numa página e a verificação é binária, porque número está certo ou errado, enquanto a qualidade de uma revisão de estilo admite discussão.
Há ainda um motivo prático para essa escolha: é uma tarefa em que se erra sem perceber. O acumulado em 12 meses calculado por soma simples, em vez de composição, passa ileso por uma revisão apressada e sai errado no relatório publicado.
Versão 1: o mínimo que poderia funcionar
A primeira versão deve ser pequena de propósito. Escrever a skill "completa" de primeira é apostar que você sabe de antemão onde o modelo vai errar, e você não sabe; melhor deixar o teste revelar. A versão 1 tinha uma description de uma linha e um corpo de três frases: leia o CSV, calcule as variações do mês, do ano e do acumulado em 12 meses, escreva um parágrafo.
No teste com o caso real, um CSV de variações mensais do IPCA, o Claude leu o arquivo, calculou e escreveu um parágrafo fluente. A leitura atenta, porém, revelou três problemas.
O primeiro erro é o mais sério, porque é o mais difícil de notar. Somar as doze variações mensais dá 4,33%; compor, multiplicando os fatores de cada mês e subtraindo um, dá 4,41%. Oito centésimos de diferença não chamam a atenção de ninguém, e é justamente por isso que esse erro chega a relatório publicado. O segundo erro foi de formato, números com ponto decimal no meio de um texto em português. O terceiro foi de fronteira: o modelo fechou o parágrafo com uma leitura econômica ("pressão inflacionária persistente") que a skill nunca pediu, porque nada dizia que o texto termina nos números.
Nenhum desses erros surpreende em retrospecto: a skill não deu a fórmula, não deu o formato e não delimitou a saída. Skill vaga é só um prompt vago que se repete sozinho.
Versão 2: cada falha vira regra
A correção segue um princípio simples: cada falha observada no teste vira uma regra explícita no SKILL.md. A fórmula do acumulado por composição entrou por extenso, o formato dos números ganhou exemplos (0,45%, não 0.45%) e a interpretação foi proibida com as palavras exatas a evitar.
Entrou também a instrução de executar os cálculos com código, nunca de cabeça. Aritmética mental é exatamente o tipo de operação que um modelo de linguagem erra com confiança, porque ele estima o resultado em vez de computá-lo; com a instrução, o Claude escreve três linhas de Python, roda e usa o resultado que saiu da máquina.
No reteste, os três defeitos da versão 1 sumiram, e dois defeitos novos apareceram, nenhum deles visível antes de testar. Numa conversa seguinte, o pedido "abre o CSV e me diz o último valor", uma leitura simples, disparou a skill mesmo assim, devolvendo o parágrafo completo quando a resposta era um número, porque a description genérica abraçava qualquer pergunta sobre série econômica. E rodando a skill três vezes seguidas saíram três parágrafos com os mesmos números e estruturas diferentes, um ruído incômodo para o leitor habituado que procura cada informação no lugar dela.
Versão 3: gatilho com fronteira e exemplo de saída
Os dois defeitos da versão 2 têm correções conhecidas. Para o disparo indevido, a description virou um gatilho com fronteira: além de dizer quando usar, passou a dizer por escrito quando não usar (leituras simples do CSV, séries que não sejam variações percentuais mensais). Para a instabilidade do parágrafo, entrou a técnica de few-shot: um exemplo concreto da saída esperada, que o modelo imita trocando apenas valores e datas, vale mais que três parágrafos descrevendo a saída esperada.
O exemplo embutido na skill é este, e toda execução passou a segui-lo:
O IPCA variou 0,45% em dezembro de 2025, acima dos 0,20% registrados em novembro e abaixo dos 0,52% de dezembro de 2024. No acumulado em 12 meses, o índice atingiu 4,41%.
Como rede final, a versão 3 fecha com um checklist que o Claude percorre antes de entregar: acumulado por composição, vírgula decimal em todos os números, nenhuma palavra de interpretação, datas conferidas com as últimas linhas do CSV. No reteste, o comando devolveu o parágrafo na estrutura do exemplo, com os números certos, em três execuções seguidas; e o pedido do último valor passou a receber a resposta curta, sem acionar a skill. Vale testar também o pedido que a skill não deve atender, porque a fronteira da description só fica calibrada quando você verifica os dois lados dela.
O ciclo que constrói qualquer skill
O método das três versões nada tem de específico deste exemplo. É um ciclo de quatro estações, escrever a versão mínima, testar com o caso real, observar o que saiu errado e transformar a falha em regra, repetido até a saída estabilizar.
O ciclo converge rápido: três versões bastaram aqui, e é o número típico, porque as falhas grandes aparecem logo no primeiro teste. E as regras da versão final não saíram da imaginação de quem escreveu, já que cada uma corrige uma falha observada. Esse é o motivo de começar pequeno: a skill termina contendo exatamente as regras de que precisa, nem mais, nem menos.
O que muda com a skill pronta
O antes e depois resume o ganho operacional. Sem a skill, o prompt longo é recolado da última conversa quando alguém lembra onde está, o resultado muda de formato a cada execução e a cada pessoa, e a fórmula do acumulado mora na cabeça de quem sabe. Com a skill, um comando de uma linha resolve, a estrutura do parágrafo é a mesma para todo o time, e a fórmula está escrita, revisada e versionada no git.
O ganho visível é digitar menos, mas o que justifica o investimento é institucional: a skill transforma conhecimento tácito em procedimento versionado. A regra de que acumulado se calcula por composição existia antes na cabeça do analista sênior; agora existe num arquivo que o git rastreia, que passa por revisão como qualquer código e que se aplica por inteiro em toda execução. Quando a regra mudar, a mudança acontece num lugar só e vale para todos no mesmo commit.
Há também um efeito composto ao longo do tempo. A segunda skill do projeto custa menos que a primeira, porque o método já está aprendido, e cada skill nova aumenta a fração do trabalho semanal que vira comando de uma linha. O time que mantém dez skills bem testadas opera num ritmo que o prompt avulso não alcança, porque os procedimentos pararam de ser redigitados e passaram a ser executados.
Considerações finais
Skills resolvem o problema que aparece depois que você aprende a usar o Claude Code: os pedidos que funcionam viram prompts longos, os prompts se perdem entre conversas e cada pessoa do time executa a mesma tarefa de um jeito. Empacotar o procedimento num SKILL.md versionado encerra essa dispersão, e o ciclo de construção por tentativa e erro garante que as regras do arquivo correspondem a falhas que aconteceram, e não a palpites.
O mesmo caminho, escolher a tarefa repetitiva, escrever a versão mínima e iterar até a saída estabilizar, se aplica a rotinas bem diferentes conforme a profissão:
- Economistas e analistas de dados: padronizam o cálculo e a redação de variações de indicadores (IPCA, câmbio, atividade), com a fórmula do acumulado escrita e conferida em toda execução.
- Administradores: transformam relatórios gerenciais recorrentes, como o resumo semanal de vendas ou o acompanhamento de metas, num comando que devolve sempre a mesma estrutura.
- Contadores: empacotam procedimentos como o resumo padronizado de uma DRE ou a conferência de valores entre demonstrativos, tarefas verificáveis em que o número está certo ou errado.
Em qualquer dessas frentes, o benefício final é o mesmo: o procedimento sai da cabeça de quem sabe e entra no repositório, revisável e igual para todo o time.
Você viu o método; construa as suas skills com a gente
Na Imersão Claude Code para economistas, administradores e contadores você monta o passo a passo completo na prática: o projeto, o CLAUDE.md, as skills da sua rotina e os agentes que as executam, com dados reais da sua área. Quem quer acesso a todos os cursos e formações da casa tem o AM Black, a assinatura anual.
Leia também:
