Nesta aula você aprende o que é uma skill, onde ela fica no projeto e como ela se diferencia das outras formas de moldar o comportamento do Claude (o CLAUDE.md, os subagentes, o MCP da aula 05, os hooks). Na segunda metade, construímos uma skill de verdade para um problema de economista — o cálculo e a redação de variações de séries mensais — usando o método que funciona na prática: uma versão mínima, um teste real, a observação do que falhou e a regra que corrige a falha, repetidos até a saída ficar estável.
1 O que é uma skill
Uma skill é uma pasta com instruções que o Claude Code carrega quando uma tarefa específica aparece. O arquivo central se chama SKILL.md: um markdown comum, com um cabeçalho YAML de dois campos principais — name e description — seguido das instruções que você escreveria num prompt bem feito: regras, fórmulas, formato de saída, exemplos, o que evitar.
---
name: variacao
description: Use quando o usuário pedir análise de variação
de uma série mensal em CSV.
---
# Análise de variação
Calcule as variações da série e escreva um parágrafo padronizado.
...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 na janela de contexto. O corpo do SKILL.md — que pode ter centenas de linhas — só entra quando a skill é acionada. Esse mecanismo tem nome, progressive disclosure, e é o que permite acumular dezenas de procedimentos no projeto sem inchar todas as conversas: o índice é barato, o conteúdo é pago só quando usado.
Uma skill também pode carregar mais do que texto. A pasta aceita arquivos auxiliares — um script Python que a skill manda executar, uma tabela de referência, um template de relatório — que o Claude lê sob demanda, quando as instruções apontam para eles. Para os casos desta aula, o SKILL.md sozinho resolve.
1.1 Onde a skill mora
O lugar da pasta define quem enxerga a skill:
Para procedimentos do trabalho — como calcular o acumulado do IPCA, como 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 commit. No projeto, a estrutura fica assim:
meu-projeto/
├── CLAUDE.md
├── dados/
│ └── ipca.csv
└── .claude/
└── skills/
└── variacao/
└── SKILL.md1.2 Como a skill é acionada
Há dois caminhos. O explícito: você digita /variacao dados/ipca.csv na conversa, e o Claude carrega o corpo da skill e executa. O implícito: 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.
O caminho implícito depende inteiramente da description. Ela é o único texto que o Claude lê para decidir se a skill serve para o pedido, então 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. Você vai ver o segundo defeito acontecer na seção de tentativa e erro.
2 Skill, CLAUDE.md, subagente, MCP, hook: qual ferramenta 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 quando você separa três coisas: 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:
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 — se fosse para o CLAUDE.md, estaria ocupando contexto até numa conversa sobre gráficos.
As demais peças entram no quadro assim:
| 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, definido em .claude/agents/ |
Quando o principal delega uma tarefa | Trabalho longo que poluiria a conversa principal |
| MCP | Conexão com serviço externo (aula 05) | Quando o Claude chama a ferramenta | Dar acesso a dados e ações fora da máquina |
| Hook | Comando configurado no settings.json |
Sempre que o evento ocorre, sem decisão do modelo | Garantias que não podem depender do modelo "lembrar" |
Dois contrastes merecem uma frase a mais. O subagente não ensina nada: ele delega. É um segundo Claude com janela de contexto própria, útil quando uma subtarefa — varrer cinquenta arquivos, rodar uma bateria de testes — 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: 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 — “rodar o linter depois de toda edição de arquivo” — hook; quando é procedimento que pede julgamento, skill.
3 A skill desta aula: ideação antes do código
Construir uma skill começa antes do SKILL.md: começa escolhendo a tarefa certa. Nem toda tarefa rende uma boa skill, e o tempo gasto numa skill que ninguém aciona é desperdiçado. Para a rotina de um analista de macro ou de um contador, quatro candidatas aparecem rápido:
- Conferir números: checar se todo valor citado num texto bate com o CSV de origem.
- Resumir DRE: transformar a demonstração de resultados num resumo padronizado de cinco linhas.
- Variações de série: calcular variação mensal, comparação interanual e acumulado em 12 meses, e redigir o parágrafo padrão.
- Revisão de estilo: aplicar as regras de escrita da casa num texto pronto.
Para escolher entre elas, três critérios:
O projeto de bancada é mínimo: uma pasta meu-projeto/ com um CSV de variações mensais do IPCA (valores ilustrativos), no formato pt-BR que o curso usa desde a aula 01:
data;ipca_var_mensal
2025-10;0,09
2025-11;0,20
2025-12;0,454 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.
---
name: variacao
description: Analisa variações de séries econômicas.
---
# Análise de variação
Leia o CSV indicado pelo usuário e calcule as variações da série:
variação do mês, comparação com o ano anterior e acumulado em
12 meses. Escreva um parágrafo com os resultados.Salve em .claude/skills/variacao/SKILL.md e teste com o caso real:
/variacao dados/ipca.csvO Claude leu o CSV, calculou e escreveu o parágrafo. À primeira vista funcionou, mas a leitura atenta revela 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 — multiplicar os fatores (1 + v/100) e subtrair 1 — dá 4,41%. Oito centésimos de diferença não chamam atenção de ninguém, e é justamente por isso que esse erro chega a relatório publicado. O terceiro erro é de outra natureza: o modelo completou o parágrafo com uma leitura econômica que ninguém pediu, porque a skill não disse que o parágrafo termina nos números.
Nenhum desses erros é surpresa 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.
5 Versão 2 — as regras que o teste pediu
Cada falha da versão 1 vira uma regra explícita. A fórmula do acumulado entra por extenso, o formato dos números ganha exemplos, e a interpretação é proibida com nome e sobrenome:
---
name: variacao
description: Analisa variações de séries econômicas.
---
# Análise de variação de série mensal
Leia o CSV indicado pelo usuário (separador `;`, decimal `,`)
e calcule, executando os cálculos com código:
1. Variação do mês: o último valor da série.
2. Mês anterior: o penúltimo valor.
3. Mesmo mês do ano anterior: o valor 12 posições antes.
4. Acumulado em 12 meses por COMPOSIÇÃO, nunca soma:
acum = (prod(1 + v_i/100) - 1) * 100
Formato: decimal com vírgula e duas casas (0,45%, não 0.45%).
Escreva um parágrafo apenas descritivo. Não inclua interpretação
("pressão inflacionária", "cenário benigno", "sinaliza").Repare na instrução “executando os cálculos com código”. Sem ela, o modelo pode fazer a aritmética “de cabeça” — e aritmética de cabeça é exatamente o tipo de coisa que um modelo de linguagem erra com confiança, como a aula 06 mostrou. Com ela, o Claude escreve três linhas de Python, roda e usa o resultado.
No reteste, os três defeitos da versão 1 sumiram: acumulado composto, vírgula decimal, parágrafo sem adjetivos. Mas dois defeitos novos apareceram, e nenhum deles era visível antes de testar:
O primeiro: numa conversa seguinte, o pedido foi “abre o ipca.csv e me diz qual foi o último valor” — uma leitura simples, sem análise — e a skill disparou mesmo assim, devolvendo o parágrafo completo de variações quando a resposta era um número. A description (“Analisa variações de séries econômicas”) é genérica o bastante para o Claude achar que qualquer pergunta sobre uma série econômica é caso dela.
O segundo: rodando a skill três vezes seguidas, saíram três parágrafos com os mesmos números e estruturas diferentes — ora começando pelo acumulado, ora pelo mês, ora com as comparações em ordem trocada. Para um relatório que o time produz toda semana, essa variação é ruído: o leitor habituado procura cada informação no lugar dela.
6 Versão 3 — gatilho preciso e exemplo de saída
Os dois defeitos da versão 2 têm correções conhecidas. Para o disparo indevido, a description vira um gatilho com fronteira: diz quando usar e quando não usar. Para a instabilidade do parágrafo, entra a técnica de few-shot da aula 06 — um exemplo concreto da saída esperada vale mais que três parágrafos descrevendo a saída esperada. E, como rede final, um checklist que o Claude percorre antes de entregar:
---
name: variacao
description: Use quando o usuário pedir análise de variação de uma
série temporal mensal em CSV — variação do mês, comparação com o
mês anterior e com o mesmo mês do ano anterior, e acumulado em 12
meses — com parágrafo padronizado em pt-BR. Não use para leituras
simples do CSV (último valor, contagem de linhas) nem para séries
que não sejam variações percentuais mensais.
---
# Análise de variação de série mensal
Calcule as variações da série e escreva um parágrafo padronizado.
## Leitura do CSV
- Separador `;` e decimal `,`. Com pandas: `sep=";"`, `decimal=","`.
- Ordene por data antes de calcular. Se houver mês faltando no
meio da série, pare e avise — não interpole.
## Cálculos
Sempre execute os cálculos com código (Python), nunca de cabeça.
1. Variação do mês: o último valor da série.
2. Mês anterior: o penúltimo valor.
3. Mesmo mês do ano anterior: o valor 12 posições antes do último.
4. Acumulado em 12 meses: composição, nunca soma simples:
acum = (prod(1 + v_i/100) - 1) * 100
## Formato dos números
- Decimal com vírgula, duas casas: 0,45%, não 0.45%.
- Meses por extenso em minúsculas com ano: dezembro de 2025.
## Parágrafo de saída
Siga a estrutura do exemplo, trocando apenas os valores e datas:
> 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%.
## Regras
- Todo número do parágrafo sai dos cálculos sobre o CSV.
- Não escreva interpretação. O parágrafo descreve; quem
interpreta é o analista.
## Antes de entregar
- [ ] Acumulado calculado por composição (difere da soma simples).
- [ ] Todos os números com vírgula decimal e duas casas.
- [ ] Nenhuma palavra de interpretação no parágrafo.
- [ ] Datas do parágrafo conferem com as últimas linhas do CSV.No reteste, /variacao dados/ipca.csv devolveu o parágrafo na estrutura do exemplo, com os números certos, três execuções seguidas. E o pedido “me diz o último valor do CSV” passou a receber a resposta curta, sem acionar a skill, porque a description agora exclui esse caso por escrito.
6.1 O ciclo que você acabou de rodar
O método das três versões não tem nada de específico desta skill. É um ciclo, e ele se parece de propósito com o agentic loop que você conhece das aulas anteriores — só que quem itera é você:
description só fica calibrada quando você verifica os dois lados dela.7 O benefício: o que muda com a skill pronta
O ganho visível é digitar menos — um comando no lugar de um prompt de vinte linhas. Mas o ganho que justifica o investimento é outro: 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 — uma casa decimal a mais, um indicador novo no parágrafo — 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 — não porque o modelo ficou melhor, mas porque os procedimentos pararam de ser redigitados e passaram a ser executados.
O que levar desta aula
- Skill é uma pasta com
SKILL.mdem.claude/skills/(projeto) ou~/.claude/skills/(pessoal): instruções que o Claude carrega só quando a tarefa aparece. - A
descriptioné o gatilho do acionamento automático — escreva quando usar e quando não usar. CLAUDE.mdpara convenções permanentes; skill para procedimento de tarefa; subagente para delegar trabalho longo; MCP para serviços externos; hook para regras que não podem depender do modelo.- Construa por tentativa e erro: versão mínima, teste real, falha observada, regra que corrige. Três versões costumam bastar.
- O benefício final é institucional: o procedimento sai da cabeça de quem sabe e entra no repositório, versionado, revisável e igual para todo o time.
