Aula 07 — Skills: ensinando o Claude Code a trabalhar do seu jeito
Curso Claude Code para Economistas
Autor
Análise Macro
De onde viemos
Na aula 06 você viu o que o modelo lê quando responde: a janela de contexto, com system prompt, ferramentas, histórico e o que mais couber ali. Também viu o custo disso — tudo que entra na janela ocupa espaço e compete pela atenção do modelo. A skill é a resposta do Claude Code para um dilema que nasce daí: você quer que o Claude conheça os seus procedimentos, mas não quer pagar o preço de carregar todos eles em toda conversa.
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: variacaodescription: Use quando o usuário pedir análise de variação de uma série mensal em CSV.---# Análise de variaçãoCalcule 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:
projeto
Pasta .claude/skills/ na raiz do projeto, versionada com o git
todo o time
pessoal
Pasta ~/.claude/skills/ na sua máquina
qualquer projeto seu
plugin
Instalada junto com um plugin do Claude Code
quem instalar o plugin
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:
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.
Você
Digita /variacao dados/ipca.csv — ou pede em linguagem natural
Claude
Compara o pedido com as description das skills instaladas
Claude
Carrega o corpo do SKILL.md para a janela de contexto
OK
Executa a tarefa seguindo as regras da skill
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, que você usa desde a aula 01:
📌 CLAUDE.md
Carregado sempre, em toda conversa do projeto
Convenções permanentes: idioma, separador do CSV, paleta de cores
Curto por obrigação — cada linha custa em todas as conversas
vs
🎯 Skill
Carregada sob demanda, quando a tarefa aparece
Procedimento completo de uma tarefa: passos, fórmulas, exemplos
Pode ser longa — só ocupa contexto quando acionada
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 — 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:
🔁 Repetitiva
A tarefa volta toda semana ou todo mês, sempre com o mesmo roteiro
📐 Regras estáveis
Você consegue escrever as regras — fórmula, formato, proibições — num texto curto
✅ Verificável
Dá para olhar a saída e dizer com certeza se está certa ou errada
As quatro candidatas passam no primeiro critério, mas a análise de variações vence nos outros dois. As regras cabem numa página: a fórmula do acumulado, o formato pt-BR dos números, a estrutura do parágrafo. E a verificação é binária, porque número está certo ou está errado, diferente da revisão de estilo, em que a qualidade da saída admite discussão. Há ainda um motivo prático: é uma tarefa em que se erra sem perceber, já que o acumulado em 12 meses calculado por soma simples, em vez de composição, passa despercebido em revisão apressada e sai errado no relatório.
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:
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: variacaodescription: Analisa variações de séries econômicas.---# Análise de variaçãoLeia 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 em12 meses. Escreva um parágrafo com os resultados.
Salve em .claude/skills/variacao/SKILL.md e teste com o caso real:
/variacao dados/ipca.csv
O Claude leu o CSV, calculou e escreveu o parágrafo. À primeira vista funcionou, mas a leitura atenta revela três problemas:
✅ O que saiu certo
Leu o CSV com ; e , sem tropeçar (graças ao CLAUDE.md)
Identificou as colunas e ordenou as datas
Escreveu um parágrafo fluente
mas
❌ O que saiu errado
Acumulado em 12 meses somado: 4,33% em vez de 4,41%
Números com ponto decimal: "0.45%" no meio de um texto em português
Fechou com interpretação inventada: "sinalizando pressão inflacionária persistente"
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: variacaodescription: Analisa variações de séries econômicas.---# Análise de variação de série mensalLeia 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) * 100Formato: 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: variacaodescription: 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 mensalCalcule 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álculosSempre 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ídaSiga 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ê:
SUA SKILLitere até a saída estabilizar
Escrevaa versão mínima
Testecom o caso real
Observeo que saiu errado
Corrijaa falha vira regra
Duas observações sobre o ciclo. Primeiro, ele converge rápido: três versões bastaram aqui, e é o número típico, porque as falhas grandes aparecem logo no primeiro teste. Segundo, as regras da versão final não saíram da sua imaginação — 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.
Teste a skill também com o pedido que ela não deve atender. A fronteira da description só fica calibrada quando você verifica os dois lados dela.
7 O benefício: o que muda com a skill pronta
📋 Antes da skill
Prompt longo recolado da última conversa (quando alguém lembra onde está)
Resultado muda de formato a cada execução e a cada pessoa
A fórmula do acumulado mora na cabeça de quem sabe
Analista novo aprende errando ou perguntando
⚡ Depois da skill
/variacao dados/ipca.csv e pronto
Mesma estrutura de parágrafo em toda execução, para todo o time
A fórmula está escrita, revisada e versionada no git
Analista novo herda o procedimento no primeiro git pull
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.md em .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.md para 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.
Código fonte
---title: "Aula 07 — Skills: ensinando o Claude Code a trabalhar do seu jeito"subtitle: "Curso Claude Code para Economistas"author: "Análise Macro"lang: pt-BRformat: html: theme: cosmo toc: true toc-depth: 3 toc-location: left toc-title: '<a href="https://analisemacro.com.br/" target="_blank"><img src="https://analisemacro.com.br/wp-content/uploads/dlm_uploads/2021/10/logo_am.png" alt="Logotipo Análise Macro" width="150"></a>' number-sections: true code-fold: false code-tools: true code-copy: true highlight-style: github smooth-scroll: true page-layout: article self-contained: trueexecute: echo: true eval: false warning: false message: false---```{=html}<style>:root { --primary: #d97706; --secondary: #1a1a2e; --accent: #f59e0b; --bg-dark: #0f0f23; --bg-light: #fffbeb; --success: #059669; --info: #2563eb; --warning: #dc2626; --text-light: #f8fafc;}.tip-box { background: #ecfdf5; border-left: 5px solid var(--success); padding: 1.25rem; border-radius: 0 8px 8px 0; margin: 1.25rem 0;}.tip-box::before { content: "💡 Dica"; font-weight: 700; color: var(--success); display: block; margin-bottom: 0.5rem; }.info-box { background: #eff6ff; border-left: 5px solid var(--info); padding: 1.25rem; border-radius: 0 8px 8px 0; margin: 1.25rem 0;}.info-box::before { content: "ℹ️ Informação"; font-weight: 700; color: var(--info); display: block; margin-bottom: 0.5rem; }.warning-box { background: #fef2f2; border-left: 5px solid var(--warning); padding: 1.25rem; border-radius: 0 8px 8px 0; margin: 1.25rem 0;}.warning-box::before { content: "⚠️ Atenção"; font-weight: 700; color: var(--warning); display: block; margin-bottom: 0.5rem; }.comparison-table { width: 100%; border-collapse: collapse; margin: 1.5rem 0; font-size: 0.95rem;}.comparison-table th { background: var(--secondary); color: white; padding: 0.75rem 1rem; text-align: left;}.comparison-table td { padding: 0.75rem 1rem; border-bottom: 1px solid #e5e7eb;}.comparison-table tr:nth-child(even) { background: #f9fafb; }/* ============================================================ BIBLIOTECA DE DIAGRAMAS — Análise Macro (guia, fontes maiores) paleta: azul #282f6b · laranja #d97706 · verde #059669 · vermelho #dc2626 · âmbar #fbbf24 ============================================================ *//* --- container base --- */.slide-diagram { background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e2e8f0; border-radius: 12px; padding: 1.5rem 1.6rem; margin: 1.75rem 0; font-family: 'Segoe UI', sans-serif; box-shadow: 0 1px 3px rgba(40, 47, 107, 0.06);}.slide-diagram .dtitle { text-align: center; font-size: 0.8rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.08em; color: #64748b; margin-bottom: 1rem; padding-bottom: 0.5rem; border-bottom: 1px dashed #cbd5e1;}.slide-diagram .caption { text-align: center; font-size: 0.8rem; color: #d97706; font-weight: 600; margin-top: 0.8rem; font-style: italic;}/* --- fluxo horizontal clássico --- */.slide-diagram .flow { display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: 0.4rem;}.slide-diagram .node { background: white; border: 2px solid #282f6b; border-radius: 10px; padding: 0.7rem 0.95rem; font-size: 0.9rem; font-weight: 700; color: #282f6b; text-align: center; min-width: 100px; line-height: 1.3; box-shadow: 0 1px 2px rgba(40, 47, 107, 0.08);}.slide-diagram .node.accent { border-color: #d97706; color: #d97706; }.slide-diagram .node.dark { background: #282f6b; color: white; border-color: #282f6b; }.slide-diagram .node.success { border-color: #059669; color: #059669; }.slide-diagram .node small { display: block; font-weight: 400; font-size: 0.75rem; color: #64748b; margin-top: 0.2rem;}.slide-diagram .node.dark small { color: #cbd5e1; }.slide-diagram .arrow { color: #d97706; font-size: 1.6rem; font-weight: 700; line-height: 1; padding: 0 0.2rem;}.slide-diagram .arrow small { display: block; font-size: 0.68rem; color: #94a3b8; font-weight: 600; text-align: center; margin-top: 0.1rem;}/* ============================================================ COMPONENTE: hub-radial (centro + 8 raios via bg-gradient) ============================================================ */.hub-radial { display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; gap: 1.2rem 1.6rem; max-width: 800px; margin: 0.5rem auto; padding: 0.5rem; position: relative; background-image: linear-gradient(45deg, transparent 49%, rgba(217, 119, 6, 0.55) 49.5%, rgba(217, 119, 6, 0.55) 50.5%, transparent 51%), linear-gradient(-45deg, transparent 49%, rgba(217, 119, 6, 0.55) 49.5%, rgba(217, 119, 6, 0.55) 50.5%, transparent 51%), linear-gradient(90deg, transparent 49%, rgba(217, 119, 6, 0.55) 49.5%, rgba(217, 119, 6, 0.55) 50.5%, transparent 51%), linear-gradient(0deg, transparent 49%, rgba(217, 119, 6, 0.55) 49.5%, rgba(217, 119, 6, 0.55) 50.5%, transparent 51%); background-size: 100% 100%; background-repeat: no-repeat; background-position: center;}.hub-radial .center { grid-column: 2; grid-row: 2; background: linear-gradient(135deg, #1a1f5e, #282f6b); color: white; border-radius: 50%; width: 150px; height: 150px; display: flex; flex-direction: column; justify-content: center; align-items: center; margin: auto; font-weight: 800; font-size: 0.98rem; text-align: center; box-shadow: 0 6px 18px rgba(40, 47, 107, 0.4), 0 0 0 8px white; border: 3px solid #fbbf24; z-index: 3; position: relative;}.hub-radial .center small { display: block; font-weight: 400; font-size: 0.72rem; color: #fbbf24; margin-top: 0.25rem; letter-spacing: 0.02em;}.hub-radial .spoke { background: white; border: 2px solid #282f6b; border-radius: 10px; padding: 0.55rem 0.75rem; font-size: 0.85rem; font-weight: 700; color: #282f6b; text-align: center; margin: auto; width: 135px; position: relative; z-index: 2; box-shadow: 0 2px 4px rgba(40, 47, 107, 0.12), 0 0 0 6px white;}.hub-radial .spoke small { display: block; font-weight: 400; font-size: 0.68rem; color: #64748b; margin-top: 0.15rem;}.hub-radial .spoke.tl { grid-column: 1; grid-row: 1; }.hub-radial .spoke.tc { grid-column: 2; grid-row: 1; }.hub-radial .spoke.tr { grid-column: 3; grid-row: 1; }.hub-radial .spoke.ml { grid-column: 1; grid-row: 2; }.hub-radial .spoke.mr { grid-column: 3; grid-row: 2; }.hub-radial .spoke.bl { grid-column: 1; grid-row: 3; }.hub-radial .spoke.bc { grid-column: 2; grid-row: 3; }.hub-radial .spoke.br { grid-column: 3; grid-row: 3; }/* ============================================================ COMPONENTE: timeline-h (linha do tempo horizontal) ============================================================ */.timeline-h { position: relative; display: grid; grid-template-columns: repeat(4, 1fr); gap: 0.5rem; padding: 1.8rem 1rem 0.5rem; margin: 0.5rem 0;}.timeline-h::before { content: ""; position: absolute; top: 40px; left: 8%; right: 8%; height: 3px; background: linear-gradient(90deg, #94a3b8 0%, #d97706 100%); border-radius: 2px; z-index: 1;}.timeline-h::after { content: "▶"; position: absolute; top: 32px; right: calc(8% - 8px); color: #d97706; font-size: 1.1rem; font-weight: 700; z-index: 2;}.timeline-h .tl-item { position: relative; text-align: center; padding-top: 32px;}.timeline-h .tl-dot { position: absolute; top: 0; left: 50%; transform: translateX(-50%); width: 20px; height: 20px; border-radius: 50%; background: white; border: 3px solid #282f6b; z-index: 3; box-shadow: 0 0 0 4px white;}.timeline-h .tl-item.accent .tl-dot { border-color: #d97706; background: #fff7ed; }.timeline-h .tl-item.success .tl-dot { border-color: #059669; background: #ecfdf5; }.timeline-h .tl-item.dark .tl-dot { border-color: #282f6b; background: #282f6b; }.timeline-h .tl-year { display: block; font-size: 0.75rem; font-weight: 700; color: #64748b; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.3rem;}.timeline-h .tl-card { background: white; border: 2px solid #282f6b; border-radius: 10px; padding: 0.65rem 0.75rem; font-size: 0.88rem; font-weight: 700; color: #282f6b; box-shadow: 0 1px 3px rgba(40, 47, 107, 0.1);}.timeline-h .tl-item.accent .tl-card { border-color: #d97706; color: #d97706; }.timeline-h .tl-item.success .tl-card { border-color: #059669; color: #059669; }.timeline-h .tl-item.dark .tl-card { background: #282f6b; color: white; }.timeline-h .tl-card small { display: block; font-weight: 400; font-size: 0.72rem; color: #64748b; margin-top: 0.2rem;}.timeline-h .tl-item.dark .tl-card small { color: #cbd5e1; }/* ============================================================ COMPONENTE: cycle-diagram (loop circular, 4 estações) ============================================================ */.cycle-diagram { position: relative; width: 100%; max-width: 700px; height: 400px; margin: 0.5rem auto;}.cycle-diagram .cy-arc { position: absolute; top: 50%; left: 50%; width: 280px; height: 280px; transform: translate(-50%, -50%); border: 3px dashed #d97706; border-radius: 50%; opacity: 0.45; z-index: 1;}.cycle-diagram .cy-arc::before,.cycle-diagram .cy-arc::after { content: "▶"; position: absolute; color: #d97706; font-size: 1.4rem; font-weight: 700; opacity: 0.9;}.cycle-diagram .cy-arc::before { top: -16px; right: 28%; transform: rotate(40deg); }.cycle-diagram .cy-arc::after { bottom: -16px; left: 28%; transform: rotate(220deg); }.cycle-diagram .cy-center { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); background: linear-gradient(135deg, #1a1f5e, #282f6b); color: white; border-radius: 50%; width: 130px; height: 130px; display: flex; flex-direction: column; align-items: center; justify-content: center; text-align: center; font-size: 0.85rem; font-weight: 800; padding: 0.5rem; box-shadow: 0 6px 18px rgba(40, 47, 107, 0.35); border: 3px solid #fbbf24; z-index: 3; line-height: 1.15;}.cycle-diagram .cy-center small { display: block; font-weight: 500; font-size: 0.68rem; color: #fbbf24; margin-top: 0.3rem; line-height: 1.2;}.cycle-diagram .cy-node { position: absolute; background: white; border: 2px solid #282f6b; border-radius: 10px; padding: 0.55rem 0.85rem; font-size: 0.85rem; font-weight: 700; color: #282f6b; text-align: center; width: 175px; box-shadow: 0 2px 5px rgba(40, 47, 107, 0.15); z-index: 2; line-height: 1.25;}.cycle-diagram .cy-node small { display: block; font-weight: 400; font-size: 0.68rem; color: #64748b; margin-top: 0.2rem; line-height: 1.3;}.cycle-diagram .cy-node.n1 { top: 10px; left: 50%; transform: translateX(-50%); border-color: #d97706; color: #d97706; }.cycle-diagram .cy-node.n2 { top: 50%; right: 0; transform: translateY(-50%); }.cycle-diagram .cy-node.n3 { bottom: 10px; left: 50%; transform: translateX(-50%); border-color: #059669; color: #059669; }.cycle-diagram .cy-node.n4 { top: 50%; left: 0; transform: translateY(-50%); }/* ============================================================ COMPONENTE: pyramid (pirâmide de camadas, badge interno) ============================================================ */.pyramid { max-width: 680px; margin: 0.5rem auto; padding: 0 50px 0 0; display: flex; flex-direction: column; align-items: center; gap: 0.35rem;}.pyramid .layer { position: relative; display: flex; flex-direction: column; align-items: center; justify-content: center; text-align: center; font-weight: 700; font-size: 0.92rem; padding: 0.75rem 1.2rem 0.75rem 3rem; border-radius: 8px; color: white; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.15);}.pyramid .layer.l1 { width: 50%; background: linear-gradient(135deg, #fbbf24, #f59e0b); }.pyramid .layer.l2 { width: 70%; background: linear-gradient(135deg, #fb923c, #d97706); }.pyramid .layer.l3 { width: 90%; background: linear-gradient(135deg, #3a4490, #282f6b); }.pyramid .layer.l4 { width: 98%; background: linear-gradient(135deg, #1a1f5e, #0f1438); }.pyramid .layer small { display: block; font-weight: 400; font-size: 0.78rem; margin-top: 0.2rem; opacity: 0.92; line-height: 1.3;}.pyramid .layer .num-badge { position: absolute; left: 0.8rem; top: 50%; transform: translateY(-50%); width: 32px; height: 32px; background: white; border: 2px solid rgba(255, 255, 255, 0.6); color: #282f6b; border-radius: 50%; font-weight: 800; font-size: 0.95rem; display: flex; align-items: center; justify-content: center; box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);}/* ============================================================ COMPONENTE: cards-vs (comparação dois lados) ============================================================ */.cards-vs { display: grid; grid-template-columns: 1fr auto 1fr; gap: 0.9rem; align-items: stretch; margin: 1.5rem 0;}.cards-vs .card { background: white; border: 2px solid #282f6b; border-radius: 12px; overflow: hidden; display: flex; flex-direction: column; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.1);}.cards-vs .card .card-head { background: #282f6b; color: white; padding: 0.6rem 0.9rem; font-weight: 800; font-size: 0.92rem; text-align: center; letter-spacing: 0.02em;}.cards-vs .card.warm .card-head { background: linear-gradient(135deg, #fb923c, #d97706); }.cards-vs .card.cool .card-head { background: linear-gradient(135deg, #1a1f5e, #282f6b); }.cards-vs .card.good .card-head { background: linear-gradient(135deg, #059669, #047857); }.cards-vs .card.bad .card-head { background: linear-gradient(135deg, #dc2626, #991b1b); }.cards-vs .card .card-body { padding: 0.85rem 1rem; font-size: 0.9rem; color: #1e293b; line-height: 1.5; flex-grow: 1;}.cards-vs .card .card-body ul { margin: 0; padding-left: 1.1rem; }.cards-vs .card .card-body li { margin-bottom: 0.3rem; }.cards-vs .vs-pill { align-self: center; background: white; border: 2px solid #d97706; color: #d97706; font-weight: 800; font-size: 0.9rem; border-radius: 50%; width: 46px; height: 46px; display: flex; align-items: center; justify-content: center; box-shadow: 0 2px 6px rgba(217, 119, 6, 0.25);}/* ============================================================ COMPONENTE: split-feature (antes/depois, esquerda/direita) ============================================================ */.split-feature { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.5rem 0;}.split-feature .sf-block { background: white; border-radius: 12px; overflow: hidden; border: 2px solid #e2e8f0; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.08);}.split-feature .sf-block .sf-header { padding: 0.65rem 1rem; color: white; font-weight: 800; font-size: 0.95rem; display: flex; align-items: center; gap: 0.5rem;}.split-feature .sf-block .sf-icon { display: inline-flex; width: 28px; height: 28px; border-radius: 50%; background: rgba(255, 255, 255, 0.2); align-items: center; justify-content: center; font-size: 0.95rem;}.split-feature .sf-block.before .sf-header { background: linear-gradient(135deg, #64748b, #475569); }.split-feature .sf-block.after .sf-header { background: linear-gradient(135deg, #059669, #047857); }.split-feature .sf-block.left .sf-header { background: linear-gradient(135deg, #fb923c, #d97706); }.split-feature .sf-block.right .sf-header { background: linear-gradient(135deg, #1a1f5e, #282f6b); }.split-feature .sf-block .sf-body { padding: 0.85rem 1rem; font-size: 0.9rem; color: #1e293b;}.split-feature .sf-block .sf-body ul { margin: 0; padding-left: 1.1rem; }.split-feature .sf-block .sf-body li { margin-bottom: 0.3rem; }/* ============================================================ COMPONENTE: actor-flow (raias com atores) ============================================================ */.actor-flow { display: grid; grid-template-columns: 130px 1fr; gap: 0; background: #fbfbfa; border-radius: 12px; overflow: hidden; margin: 1.5rem 0; border: 1px solid #e2e8f0; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.08);}.actor-flow .lane { display: contents; }.actor-flow .actor { background: #282f6b; color: white; font-weight: 800; font-size: 0.85rem; padding: 0.8rem 0.6rem; display: flex; align-items: center; justify-content: center; text-align: center; border-bottom: 1px solid rgba(255, 255, 255, 0.15); letter-spacing: 0.02em;}.actor-flow .actor.you { background: linear-gradient(135deg, #fb923c, #d97706); }.actor-flow .actor.svc { background: linear-gradient(135deg, #1a1f5e, #282f6b); }.actor-flow .actor.cl { background: linear-gradient(135deg, #3a4490, #282f6b); }.actor-flow .actor.ok { background: linear-gradient(135deg, #059669, #047857); }.actor-flow .step { background: white; padding: 0.8rem 1rem; font-size: 0.9rem; color: #1e293b; border-bottom: 1px solid #e2e8f0; display: flex; align-items: center; position: relative; line-height: 1.4;}.actor-flow .step::before { content: "▶"; color: #d97706; margin-right: 0.6rem; font-weight: 700; font-size: 0.85rem; flex-shrink: 0;}.actor-flow > .lane:last-of-type > .actor,.actor-flow > .lane:last-of-type > .step,.actor-flow > .actor:nth-last-of-type(1),.actor-flow > .step:nth-last-of-type(1) { border-bottom: none;}/* ============================================================ COMPONENTE: tier-stack (pilha de escopos com etiquetas) ============================================================ */.tier-stack { max-width: 760px; margin: 1.5rem auto; display: flex; flex-direction: column; gap: 0.4rem;}.tier-stack .tier { display: grid; grid-template-columns: 130px 1fr 110px; gap: 0; background: white; border-radius: 10px; overflow: hidden; border: 2px solid #282f6b; box-shadow: 0 1px 3px rgba(40, 47, 107, 0.1);}.tier-stack .tier .tier-tag { background: #282f6b; color: white; font-weight: 800; font-size: 0.88rem; display: flex; align-items: center; justify-content: center; text-transform: uppercase; letter-spacing: 0.05em;}.tier-stack .tier.t1 { border-color: #94a3b8; }.tier-stack .tier.t1 .tier-tag { background: #64748b; }.tier-stack .tier.t2 { border-color: #d97706; }.tier-stack .tier.t2 .tier-tag { background: linear-gradient(135deg, #fb923c, #d97706); }.tier-stack .tier.t3 { border-color: #1a1f5e; }.tier-stack .tier.t3 .tier-tag { background: linear-gradient(135deg, #1a1f5e, #282f6b); }.tier-stack .tier .tier-desc { padding: 0.65rem 1rem; font-size: 0.9rem; color: #1e293b; display: flex; align-items: center;}.tier-stack .tier .tier-scope { background: #f1f5f9; display: flex; align-items: center; justify-content: center; font-size: 0.78rem; font-weight: 700; color: #475569; text-align: center; padding: 0.3rem 0.5rem; line-height: 1.3; border-left: 1px solid #e2e8f0;}/* ============================================================ COMPONENTE: steps-numbered (passos com círculo de número) ============================================================ */.steps-numbered { display: grid; grid-template-columns: repeat(5, 1fr); gap: 0.5rem; margin: 0.5rem 0 1rem; padding: 0 0.5rem; position: relative;}.steps-numbered::before { content: ""; position: absolute; top: 26px; left: 10%; right: 10%; height: 4px; background: linear-gradient(90deg, #282f6b 0%, #d97706 50%, #059669 100%); border-radius: 2px; z-index: 1;}.steps-numbered::after { content: "▶"; position: absolute; top: 14px; right: calc(10% - 12px); color: #059669; font-size: 1.3rem; font-weight: 700; z-index: 3;}.steps-numbered .stp { position: relative; text-align: center; z-index: 2;}.steps-numbered .stp .num { width: 52px; height: 52px; border-radius: 50%; background: white; border: 3px solid #282f6b; color: #282f6b; font-weight: 800; font-size: 1.1rem; display: flex; align-items: center; justify-content: center; margin: 0 auto 0.5rem; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.2), 0 0 0 4px white;}.steps-numbered .stp.accent .num { background: #fff7ed; border-color: #d97706; color: #d97706; }.steps-numbered .stp.success .num { background: #ecfdf5; border-color: #059669; color: #059669; }.steps-numbered .stp .stp-title { font-size: 0.88rem; font-weight: 700; color: #282f6b; margin-bottom: 0.2rem;}.steps-numbered .stp .stp-desc { font-size: 0.75rem; color: #64748b; line-height: 1.3;}/* ============================================================ COMPONENTE: fontes-triple (3 cards lado a lado) ============================================================ */.fontes-triple { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 0.7rem; align-items: stretch; margin: 1.5rem 0;}.fontes-triple .ft-block { background: white; border-radius: 12px; overflow: hidden; display: flex; flex-direction: column; border: 2px solid #e2e8f0; box-shadow: 0 2px 6px rgba(40, 47, 107, 0.08);}.fontes-triple .ft-block .ft-head { padding: 0.6rem 0.8rem; color: white; font-weight: 800; font-size: 0.92rem; text-align: center;}.fontes-triple .ft-block.b1 .ft-head { background: linear-gradient(135deg, #3a4490, #282f6b); }.fontes-triple .ft-block.b2 .ft-head { background: linear-gradient(135deg, #fb923c, #d97706); }.fontes-triple .ft-block.b3 .ft-head { background: linear-gradient(135deg, #059669, #047857); }.fontes-triple .ft-block .ft-body { padding: 0.8rem 0.95rem; font-size: 0.88rem; color: #1e293b; flex-grow: 1;}.fontes-triple .ft-block .ft-body code { background: #f1f5f9; padding: 0.05rem 0.3rem; border-radius: 3px; font-size: 0.8rem; color: #282f6b;}/* ============================================================ COMPONENTE: mesh-grid (matriz NxN) ============================================================ */.mesh-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 0.45rem; max-width: 520px; margin: 0.4rem auto;}.mesh-cell { background: white; border: 2px solid #282f6b; border-radius: 6px; padding: 0.5rem 0.35rem; font-size: 0.8rem; font-weight: 700; text-align: center; color: #282f6b; box-shadow: 0 1px 2px rgba(40, 47, 107, 0.08);}.mesh-cell.mesh-bad { background: linear-gradient(135deg, #fef2f2, #fee2e2); color: #dc2626; border-color: #dc2626; animation: pulse-bad 2s infinite;}@keyframes pulse-bad { 0%, 100% { box-shadow: 0 0 0 0 rgba(220, 38, 38, 0.4); } 50% { box-shadow: 0 0 0 6px rgba(220, 38, 38, 0); }}/* ---- bloco JSON inline para exemplos curtos ---- */.json-inline { background: #1e1e2e; color: #cdd6f4; border-radius: 8px; padding: 1rem 1.2rem; font-family: 'Consolas', 'Monaco', monospace; font-size: 0.85rem; line-height: 1.5; margin: 1.25rem 0; overflow-x: auto;}.json-inline .key { color: #f9e2af; }.json-inline .str { color: #a6e3a1; }.json-inline .comment { color: #6c7086; font-style: italic; }</style>```## De onde viemos {.unnumbered}Na aula 06 você viu o que o modelo lê quando responde: a janela de contexto, com system prompt, ferramentas, histórico e o que mais couber ali. Também viu o custo disso — tudo que entra na janela ocupa espaço e compete pela atenção do modelo. A skill é a resposta do Claude Code para um dilema que nasce daí: você quer que o Claude conheça os seus procedimentos, mas não quer pagar o preço de carregar todos eles em toda conversa.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.# O que é uma skillUma 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.```markdown---name: variacaodescription: Use quando o usuário pedir análise de variação de uma série mensal em CSV.---# Análise de variaçãoCalcule 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.## Onde a skill moraO lugar da pasta define quem enxerga a skill:```{=html}<div class="tier-stack"> <div class="tier t1"> <div class="tier-tag">projeto</div> <div class="tier-desc">Pasta <code>.claude/skills/</code> na raiz do projeto, versionada com o git</div> <div class="tier-scope">todo o time</div> </div> <div class="tier t2"> <div class="tier-tag">pessoal</div> <div class="tier-desc">Pasta <code>~/.claude/skills/</code> na sua máquina</div> <div class="tier-scope">qualquer projeto seu</div> </div> <div class="tier t3"> <div class="tier-tag">plugin</div> <div class="tier-desc">Instalada junto com um plugin do Claude Code</div> <div class="tier-scope">quem instalar o plugin</div> </div></div>```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.md```## Como a skill é acionadaHá 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.```{=html}<div class="actor-flow"> <div class="lane"> <div class="actor you">Você</div> <div class="step">Digita <code>/variacao dados/ipca.csv</code> — ou pede em linguagem natural</div> </div> <div class="lane"> <div class="actor cl">Claude</div> <div class="step">Compara o pedido com as <code>description</code> das skills instaladas</div> </div> <div class="lane"> <div class="actor cl">Claude</div> <div class="step">Carrega o corpo do <code>SKILL.md</code> para a janela de contexto</div> </div> <div class="lane"> <div class="actor ok">OK</div> <div class="step">Executa a tarefa seguindo as regras da skill</div> </div></div>```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.# Skill, CLAUDE.md, subagente, MCP, hook: qual ferramenta para qual problemaTodas 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`, que você usa desde a aula 01:```{=html}<div class="cards-vs"> <div class="card cool"> <div class="card-head">📌 CLAUDE.md</div> <div class="card-body"> <ul> <li>Carregado <strong>sempre</strong>, em toda conversa do projeto</li> <li>Convenções permanentes: idioma, separador do CSV, paleta de cores</li> <li>Curto por obrigação — cada linha custa em todas as conversas</li> </ul> </div> </div> <div class="vs-pill">vs</div> <div class="card warm"> <div class="card-head">🎯 Skill</div> <div class="card-body"> <ul> <li>Carregada <strong>sob demanda</strong>, quando a tarefa aparece</li> <li>Procedimento completo de uma tarefa: passos, fórmulas, exemplos</li> <li>Pode ser longa — só ocupa contexto quando acionada</li> </ul> </div> </div></div>```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 — se fosse para o `CLAUDE.md`, estaria ocupando contexto até numa conversa sobre gráficos.As demais peças entram no quadro assim:```{=html}<table class="comparison-table"> <thead> <tr> <th>Peça</th> <th>O que é</th> <th>Quando age</th> <th>Use para</th> </tr> </thead> <tbody> <tr> <td><strong>CLAUDE.md</strong></td> <td>Contexto fixo do projeto</td> <td>Sempre, em toda conversa</td> <td>Convenções permanentes e curtas</td> </tr> <tr> <td><strong>Skill</strong></td> <td>Procedimento carregado sob demanda</td> <td>Quando a tarefa correspondente aparece</td> <td>Tarefas repetitivas com regras estáveis</td> </tr> <tr> <td><strong>Subagente</strong></td> <td>Outro Claude, com contexto próprio, definido em <code>.claude/agents/</code></td> <td>Quando o principal delega uma tarefa</td> <td>Trabalho longo que poluiria a conversa principal</td> </tr> <tr> <td><strong>MCP</strong></td> <td>Conexão com serviço externo (aula 05)</td> <td>Quando o Claude chama a ferramenta</td> <td>Dar acesso a dados e ações fora da máquina</td> </tr> <tr> <td><strong>Hook</strong></td> <td>Comando configurado no <code>settings.json</code></td> <td>Sempre que o evento ocorre, sem decisão do modelo</td> <td>Garantias que não podem depender do modelo "lembrar"</td> </tr> </tbody></table>```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.# A skill desta aula: ideação antes do códigoConstruir 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:```{=html}<div class="fontes-triple"> <div class="ft-block b1"> <div class="ft-head">🔁 Repetitiva</div> <div class="ft-body">A tarefa volta toda semana ou todo mês, sempre com o mesmo roteiro</div> </div> <div class="ft-block b2"> <div class="ft-head">📐 Regras estáveis</div> <div class="ft-body">Você consegue escrever as regras — fórmula, formato, proibições — num texto curto</div> </div> <div class="ft-block b3"> <div class="ft-head">✅ Verificável</div> <div class="ft-body">Dá para olhar a saída e dizer com certeza se está certa ou errada</div> </div></div>```As quatro candidatas passam no primeiro critério, mas a **análise de variações** vence nos outros dois. As regras cabem numa página: a fórmula do acumulado, o formato pt-BR dos números, a estrutura do parágrafo. E a verificação é binária, porque número está certo ou está errado, diferente da revisão de estilo, em que a qualidade da saída admite discussão. Há ainda um motivo prático: é uma tarefa em que se erra sem perceber, já que o acumulado em 12 meses calculado por soma simples, em vez de composição, passa despercebido em revisão apressada e sai errado no relatório.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_mensal2025-10;0,092025-11;0,202025-12;0,45```# Versão 1 — o mínimo que poderia funcionarA 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.```markdown---name: variacaodescription: Analisa variações de séries econômicas.---# Análise de variaçãoLeia 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 em12 meses. Escreva um parágrafo com os resultados.```Salve em `.claude/skills/variacao/SKILL.md` e teste com o caso real:```/variacao dados/ipca.csv```O Claude leu o CSV, calculou e escreveu o parágrafo. À primeira vista funcionou, mas a leitura atenta revela três problemas:```{=html}<div class="cards-vs"> <div class="card good"> <div class="card-head">✅ O que saiu certo</div> <div class="card-body"> <ul> <li>Leu o CSV com <code>;</code> e <code>,</code> sem tropeçar (graças ao CLAUDE.md)</li> <li>Identificou as colunas e ordenou as datas</li> <li>Escreveu um parágrafo fluente</li> </ul> </div> </div> <div class="vs-pill">mas</div> <div class="card bad"> <div class="card-head">❌ O que saiu errado</div> <div class="card-body"> <ul> <li>Acumulado em 12 meses <strong>somado</strong>: 4,33% em vez de 4,41%</li> <li>Números com ponto decimal: "0.45%" no meio de um texto em português</li> <li>Fechou com interpretação inventada: "sinalizando pressão inflacionária persistente"</li> </ul> </div> </div></div>```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.# Versão 2 — as regras que o teste pediuCada 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:```markdown---name: variacaodescription: Analisa variações de séries econômicas.---# Análise de variação de série mensalLeia 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) * 100Formato: 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.# Versão 3 — gatilho preciso e exemplo de saídaOs 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:```markdown---name: variacaodescription: 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 mensalCalcule 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álculosSempre 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ídaSiga 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.## O ciclo que você acabou de rodarO 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ê:```{=html}<div class="cycle-diagram"> <div class="cy-arc"></div> <div class="cy-center">SUA SKILL<small>itere até a<br>saída estabilizar</small></div> <div class="cy-node n1">Escreva<small>a versão mínima</small></div> <div class="cy-node n2">Teste<small>com o caso real</small></div> <div class="cy-node n3">Observe<small>o que saiu errado</small></div> <div class="cy-node n4">Corrija<small>a falha vira regra</small></div></div>```Duas observações sobre o ciclo. Primeiro, ele converge rápido: três versões bastaram aqui, e é o número típico, porque as falhas grandes aparecem logo no primeiro teste. Segundo, as regras da versão final não saíram da sua imaginação — 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.```{=html}<div class="tip-box">Teste a skill também com o pedido que ela <strong>não</strong> deve atender. A fronteira da <code>description</code> só fica calibrada quando você verifica os dois lados dela.</div>```# O benefício: o que muda com a skill pronta```{=html}<div class="split-feature"> <div class="sf-block before"> <div class="sf-header"><span class="sf-icon">📋</span> Antes da skill</div> <div class="sf-body"> <ul> <li>Prompt longo recolado da última conversa (quando alguém lembra onde está)</li> <li>Resultado muda de formato a cada execução e a cada pessoa</li> <li>A fórmula do acumulado mora na cabeça de quem sabe</li> <li>Analista novo aprende errando ou perguntando</li> </ul> </div> </div> <div class="sf-block after"> <div class="sf-header"><span class="sf-icon">⚡</span> Depois da skill</div> <div class="sf-body"> <ul> <li><code>/variacao dados/ipca.csv</code> e pronto</li> <li>Mesma estrutura de parágrafo em toda execução, para todo o time</li> <li>A fórmula está escrita, revisada e versionada no git</li> <li>Analista novo herda o procedimento no primeiro <code>git pull</code></li> </ul> </div> </div></div>```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 {.unnumbered}- Skill é uma pasta com `SKILL.md` em `.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.md` para 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.