Skills do Claude: o que são, quando usar e como montar uma

Quem usa o Claude no dia a dia acaba repetindo as mesmas instruções: “use o modelo de relatório da empresa”, “formate as datas assim”, “gráfico sem pizza, por favor”. Uma skill é o jeito de escrever essas instruções uma vez, guardar numa pasta e deixar o Claude usá-las sozinho sempre que a tarefa pedir. Este artigo explica, do zero, o que é uma skill, como ela funciona por dentro, quando vale a pena criar uma e como montá-la passo a passo. Para não ficar só na teoria, no fim construo uma skill completa: uma que ensina o Claude a fazer gráficos seguindo os princípios do livro Storytelling com Dados, de Cole Nussbaumer Knaflic.

§1O que é uma skill

Uma skill (“habilidade”) é uma pasta com instruções e, opcionalmente, arquivos de apoio, que o Claude carrega quando a tarefa combina com ela. O coração da pasta é um arquivo chamado SKILL.md: um texto em Markdown com um pequeno cabeçalho que diz o nome da skill e quando usá-la. Ao lado dele podem existir documentos de referência, modelos, exemplos e scripts.

Uma analogia: o Claude é um profissional competente e generalista. Uma skill é o manual de procedimentos que você entrega a ele no primeiro dia — “aqui fazemos relatórios assim”, “nossos gráficos seguem estas regras”, “este script converte a planilha do jeito certo”. Ele não precisa decorar o manual: sabe que existe, sabe para que serve e abre a página certa quando precisa.

Três coisas definem uma skill:

• É conhecimento de procedimento, não de fatos. Ensina como fazer algo do seu jeito (o fluxo, o padrão, as armadilhas), não informações que mudam toda semana.
• É ativada pelo contexto. Você não precisa chamá-la: o Claude decide usá-la quando o pedido combina com a descrição. No Claude Code, também dá para chamá-la explicitamente com /nome-da-skill.
• É portátil. A mesma pasta funciona no Claude Code, no app do Claude (claude.ai) e pela API. Dá para versionar no Git e compartilhar com a equipe.

§2Como funciona por dentro: carregamento em camadas

O detalhe que torna as skills práticas é que elas não ocupam o contexto do modelo o tempo todo. O contexto (o “espaço de trabalho” do modelo, medido em tokens) é limitado; se cada skill instalada despejasse todo o seu conteúdo em cada conversa, não daria para ter muitas. Por isso o carregamento acontece em três níveis — o que a Anthropic chama de progressive disclosure (revelação progressiva):

Na prática: o Claude “sabe” que existe uma skill de gráficos porque leu a descrição de uma linha. Quando você pede um gráfico, ele abre o SKILL.md. Se o SKILL.md diz “para escolher o tipo de gráfico, consulte references/escolha-do-grafico.md”, ele abre esse arquivo — e só ele. Por isso dá para instalar dezenas de skills sem pesar, e por isso uma skill pode carregar material extenso: o que não for necessário fica no disco.

§3Skill, prompt, CLAUDE.md, MCP, subagente: qual usar

O ecossistema do Claude tem várias formas de “ensinar” ou “equipar” o modelo, e é fácil confundir. A diferença está em quando a coisa é carregada e o que ela fornece:

Uma forma simples de pensar: MCP dá ao Claude mãos (acesso a sistemas); skill dá ao Claude know-how (como fazer bem). Os dois se combinam: um conector MCP traz os dados de vendas; uma skill diz como transformá-los num gráfico que comunica.

§4Para que serve, e quando criar uma

Vale a pena criar uma skill quando:

• Você se pega repetindo as mesmas instruções em conversas diferentes. Se já colou o mesmo parágrafo de orientação três vezes, ele deveria ser uma skill.
• Há um padrão da casa: identidade visual, formato de relatório, estrutura de proposta, guia de estilo de escrita, convenções de código de uma biblioteca interna.
• A tarefa tem um fluxo com várias etapas que o modelo costuma pular ou fazer fora de ordem: revisão de contrato contra um checklist, análise de dados com validação, preparação de release.
• Existe conhecimento de domínio que o modelo não tem ou aplica de forma inconsistente: as regras de um livro de referência (como o desta demonstração), normas da empresa, particularidades de um formato de arquivo.
• Parte do trabalho é determinística e deveria ser código, não texto gerado: converter formatos, validar um arquivo, aplicar um estilo. A skill pode trazer o script pronto.

Não vale a pena quando:

• É algo de uma vez só — escreva no prompt.
• É uma regra que vale para tudo num projeto — vai no CLAUDE.md.
• O que falta é acesso a um sistema, não instrução — isso é um conector MCP.
• A informação muda toda semana (preços, estoque, notícias) — a skill envelhece; busque o dado na hora.

§5Anatomia de uma skill

A estrutura mínima é uma pasta com um arquivo. A estrutura típica, a da skill que vou construir, é esta:

storytelling-charts/
├── SKILL.md                     # obrigatório: cabeçalho + instruções principais
├── references/                  # lidos sob demanda
│   ├── principios.md            #   os princípios completos, com o porquê
│   ├── escolha-do-grafico.md    #   tabela pergunta → tipo de gráfico
│   └── checklist.md             #   revisão antes de entregar
└── scripts/
    └── sc_style.py              # ajudantes de matplotlib (estilo, rótulos diretos)

O SKILL.md começa com um cabeçalho em YAML, entre linhas de ---:

---
name: storytelling-charts
description: Monta gráficos explicativos que comunicam uma mensagem, seguindo
  os princípios de "Storytelling com Dados". Use sempre que o usuário pedir um
  gráfico, visualização, slide com dados ou dashboard para apresentar a alguém,
  e quando pedir para revisar ou "deixar mais claro" um gráfico existente.
---

# Gráficos com storytelling

Esta skill transforma "fazer um gráfico" em "comunicar uma conclusão com dados".
...

• name: identificador da skill — letras minúsculas, números e hífens, até 64 caracteres. É o que aparece em /storytelling-charts.
• description: o campo mais importante da skill inteira (até 1.024 caracteres). É a única coisa que o Claude vê antes de decidir se usa ou não. Precisa dizer o que a skill faz e quando usá-la.
• Corpo: as instruções, em Markdown comum. Escreva como escreveria para um colega competente que nunca viu o seu processo: imperativo, direto, com exemplos. A recomendação é manter o SKILL.md abaixo de umas 500 linhas e mover o detalhe para arquivos em references/.
• Arquivos de apoio: o corpo precisa apontar para eles (“leia references/principios.md na primeira vez”). Um arquivo que nenhuma instrução menciona provavelmente nunca será aberto.

No Claude Code, o cabeçalho aceita campos opcionais além desses dois — por exemplo, restringir quais ferramentas a skill pode usar. Para começar, name e description bastam.

§6Montando passo a passo

1. Faça a tarefa uma vez, na conversa, sem skill. Peça o gráfico, corrija o que sair errado, anote cada correção que você precisou dar. Essas correções são o conteúdo da skill. Uma skill escrita antes de você ter feito a tarefa à mão costuma ensinar o óbvio e esquecer o que importa.

2. Escreva a descrição. Ela deve conter as palavras que você usaria ao pedir (“gráfico”, “visualização”, “slide”, “dashboard”) e os limites (“não use para gráficos exploratórios rápidos”). Descrições vagas — “ajuda com dados” — fazem a skill disparar na hora errada ou nunca.

3. Escreva o corpo como um processo. Etapas numeradas, na ordem em que devem acontecer, com o porquê de cada regra. Explicar o motivo (“pizza dificulta comparar porque o olho mede mal ângulos”) funciona melhor do que só proibir: o modelo generaliza para casos que você não previu.

4. Mova o detalhe para references/. Tabelas longas, catálogos, exemplos extensos, regras de nicho. O SKILL.md fica enxuto e diz quando abrir cada arquivo.

5. Transforme o que é mecânico em script. Se toda vez o modelo reescreve as mesmas 30 linhas de configuração do matplotlib, ponha essas linhas num .py e mande a skill usá-lo. Código é determinístico, testável e não gasta contexto para ser “lembrado”.

6. Instale. Onde a pasta fica dependerá de onde está o Claude:

Para esta skill, no Claude Code:

# pessoal (vale em qualquer projeto)
cp -r skills/storytelling-charts ~/.claude/skills/

# ou só neste repositório
mkdir -p .claude/skills && cp -r skills/storytelling-charts .claude/skills/

7. Teste e ajuste (detalhes na §10).

§7A descrição: o detalhe que decide tudo

Como só o nome e a descrição ficam sempre visíveis, uma skill excelente com descrição ruim é uma skill que não roda. Três regras práticas:

• Diga o gatilho, não só o tema. “Princípios de visualização” descreve um assunto; “Use sempre que o usuário pedir um gráfico, slide com dados ou dashboard” descreve uma situação. O Claude decide por situação.
• Inclua os sinônimos que as pessoas usam. Gráfico, chart, plot, visualização, figura. Também casos indiretos: “revisar um gráfico existente”, “deixar mais claro”.
• Diga quando não usar, se houver uma fronteira natural. Isso evita que a skill entre em tarefas vizinhas.

Os modelos tendem a subusar skills — na dúvida, não carregam. Por isso a descrição pode (e deve) ser um pouco insistente: “use sempre que…” funciona melhor que “pode ser usada para…”.

§8A demonstração: o livro em seis etapas

Storytelling com Dados é um dos livros mais usados para ensinar comunicação com gráficos no mundo corporativo. A tese central é que um gráfico explicativo é um argumento: existe para levar uma audiência específica a entender algo e agir, e os padrões dos softwares (feitos para servir a qualquer dado) quase nunca servem a esse objetivo. O livro organiza o trabalho em seis lições, que viraram as seis etapas do SKILL.md:

1. Entender o contexto. Antes de abrir o software: quem é a audiência (específica, não “a diretoria”), o que ela deve saber ou fazer e como vai ver (apresentação ao vivo ou documento lido sozinho). Separar a análise exploratória (procurar o que é interessante) da explicativa (mostrar o que você achou). Resumir tudo numa ideia central — uma frase com ponto de vista e o que está em jogo — e conseguir contar a história em três minutos. Rascunhar a sequência em papel (storyboard) antes de produzir.
2. Escolher o visual adequado. Um repertório pequeno resolve quase tudo: texto simples para um ou dois números, tabela, mapa de calor, dispersão, linhas, inclinação, barras (verticais, horizontais, empilhadas), cascata. Evitar pizza e rosca, 3D e eixo duplo. Barras sempre com base zero.
3. Eliminar a poluição. Cada elemento sem função aumenta a carga cognitiva. Os princípios da Gestalt (proximidade, similaridade, fechamento, continuidade, conexão, cerco) explicam por que bordas, grades e legendas costumam ser dispensáveis. Alinhar, usar espaço em branco, rotular diretamente.
4. Focar a atenção. Os atributos pré-atentivos — cor, intensidade, tamanho, posição, negrito — são percebidos antes da leitura consciente. A receita: tudo em cinza, cor só onde está a mensagem. Se tudo se destaca, nada se destaca.
5. Pensar como designer. Deixar claro como “usar” o gráfico (o que olhar primeiro), torná-lo acessível (título que afirma, eixos rotulados, anotações, linguagem simples), cuidar da estética e planejar a aceitação de formatos novos pela audiência.
6. Contar uma história. Começo (contexto e conflito), meio (os dados que desenvolvem o problema e as opções), fim (a chamada à ação). Verificar pelos títulos dos slides lidos em sequência (lógica horizontal) e pelo conteúdo de cada slide (lógica vertical). Repetir a mensagem no começo e no fim.

O arquivo references/principios.md desenvolve cada etapa com o porquê, os padrões recorrentes de bons gráficos e as táticas de narrativa; escolha-do-grafico.md traz a tabela “pergunta do leitor → gráfico”; checklist.md é a revisão final. A pasta completa está no repositório deste site.

§9Antes e depois

Os mesmos dados (inventados) em duas versões. Primeiro, o que sai de um software com as configurações padrão, ou de um pedido genérico “faça um gráfico das devoluções por linha”:

Agora o mesmo gráfico depois de passar pelas seis etapas da skill. A ideia central foi definida primeiro: as devoluções da linha infantil dobraram depois da troca de fornecedor em março. Todo o resto serve a essa frase:

Repare no que saiu: borda, grade, marcadores, legenda, decimais, datas inclinadas, duas cores. E no que entrou: uma frase de conclusão, uma anotação, dois números. Num slide, o próximo passo seria a chamada à ação — por exemplo, “propomos voltar ao fornecedor anterior para a coleção de Natal” — e, ao apresentar, revelar primeiro as linhas cinza (o normal), depois a azul (o problema).

O script scripts/sc_style.py da skill gera essa versão em matplotlib com poucas chamadas: setup() aplica os padrões, declutter() remove bordas e marcas, label_line_end() coloca o rótulo na ponta da linha e title_block() monta o título de conclusão alinhado à esquerda. Rodar o arquivo direto produz o gráfico de demonstração:

python skills/storytelling-charts/scripts/sc_style.py demo.png

§10Testar e melhorar a skill

Uma skill é um texto que muda o comportamento de um modelo — e só dá para saber se funciona testando. Um roteiro enxuto:

• Teste o gatilho. Faça pedidos que deveriam ativar a skill (“monta um gráfico das vendas por região para a reunião”) e pedidos vizinhos que não deveriam (“qual a média dessa coluna?”). Se ela não dispara ou dispara demais, o problema está na description.
• Compare com e sem. Mesmo pedido, numa sessão com a skill e noutra sem. Se o resultado é igual, a skill não está ensinando nada que o modelo já não fizesse.
• Leia o que o modelo fez, não só o resultado. Ele abriu os arquivos de referência? Pulou etapas? Se ignora uma instrução, talvez ela esteja enterrada no meio do texto, ou sem o porquê.
• Corrija a causa, não o caso. Se o gráfico saiu com legenda, não acrescente “não use legenda neste gráfico de vendas”; reforce o princípio geral e o motivo (“rótulo direto poupa o olho de ir e voltar”).
• Mantenha enxuto. Instruções que não mudam nada no resultado só gastam contexto. Corte.

No Claude Code e no claude.ai existe uma skill oficial para isso, a skill-creator: ela entrevista você sobre o que a skill deve fazer, escreve o rascunho, roda casos de teste com e sem a skill e ajuda a ajustar a descrição. É um bom ponto de partida para a primeira skill.

§11Conclusões

• Uma skill é uma pasta com um SKILL.md (nome, descrição e instruções) e, se preciso, arquivos de referência e scripts.
• Ela é carregada em camadas: só a descrição fica sempre visível; o resto entra quando a tarefa pede. Por isso pode ser extensa sem pesar.
• Use skill para procedimentos que se repetem e conhecimento de domínio; CLAUDE.md para regras sempre válidas; MCP para acesso a sistemas; o prompt para o que é pontual.
• A descrição decide se a skill roda: escreva o gatilho, os sinônimos e os limites.
• Monte a skill a partir de uma tarefa real, explique o porquê das regras, mova detalhes para references/, transforme o mecânico em script e teste com e sem.
• A skill storytelling-charts mostra o padrão completo aplicado a um livro: contexto → visual → limpeza → atenção → design → história.

Referências: documentação de Agent Skills e skills no Claude Code (Anthropic); repositório público de skills da Anthropic; Cole Nussbaumer Knaflic, Storytelling com Dados: um guia sobre visualização de dados para profissionais de negócios (Alta Books, 2018; original Storytelling with Data, Wiley, 2015). A skill completa: skills/storytelling-charts. Os dados dos gráficos são inventados.