Claude Code Skills: como ensinar novas habilidades ao Claude

Este artigo tem vídeo:

O que são Skills

Skills são um recurso do Claude Code que permite ensinar novas habilidades ao Claude. Na prática, são arquivos Markdown (SKILL.md) que documentam conhecimento, procedimentos ou instruções que o Claude carrega automaticamente quando o contexto da conversa é relevante.

Pense em skills como um manual de treinamento para um funcionário novo. Você documenta como as coisas devem ser feitas, e o Claude consulta esse manual sempre que precisa.

Exemplos práticos

Agora vou mostrar alguns exemplos de skills que criei e uso no meu dia a dia. Cada exemplo ilustra um tipo diferente de valor que uma skill pode entregar.

Exemplo 1: converter Markdown para Word (md2docx)

O primeiro exemplo é de uma skill que criei com o intuito de ensinar o Claude a usar uma ferramenta CLI especializada na conversão de documentos Markdown para DOCX.

Não é uma conversão genérica. A ferramenta aplica formatação específica que eu defini: code blocks com fundo cinza, idioma pt-BR configurado, tabelas estilizadas, remoção automática de frontmatter YAML, entre outras regras.

O que a skill resolve

Sem a skill, três coisas aconteceriam:

O Claude não saberia que existe uma ferramenta chamada md2docx instalada no meu sistema. Ele tentaria resolver com código Python do zero ou soluções genéricas.
Mesmo que conseguisse alguma conversão, não teria garantia de que o resultado seguiria o padrão que eu preciso.
O resultado seria inconsistente entre conversões diferentes.

Com a skill, o Claude sabe que a ferramenta existe, conhece todos os parâmetros e flags disponíveis, e segue o mesmo procedimento toda vez.

Exemplo 2: iteração visual autônoma (agent-vision)

O segundo exemplo muda o tipo de valor que a skill entrega. Aqui o foco é autonomia.

Imagine o cenário: estou desenvolvendo um site e preciso ajustar a interface até que ela fique correta. O fluxo normal seria:

Eu tiro um screenshot da tela
Colo no chat do Claude
Claude sugere ajustes
Eu aplico os ajustes
Tiro outro screenshot
Colo no chat novamente
Repito até ficar pronto

Isso é lento e quebra o fluxo de trabalho. Criei uma skill chamada agent-vision que ensina o Claude a usar uma ferramenta de captura de screenshots, permitindo fazer tudo isso de forma autônoma:

# Capturar pagina web (default: 1280x800)
agent-vision url http://localhost:3000 --delay 2000

# Viewport mobile
agent-vision url http://localhost:3000 --width 375 --height 812

# Elemento especifico via CSS selector
agent-vision url http://localhost:3000 --selector ".my-component"

# Pagina inteira (com scroll)
agent-vision url http://localhost:3000 --full-page

Com essa skill, o Claude entra em um loop autônomo: captura screenshot, analisa visualmente, identifica problemas, ajusta o código, captura novamente, verifica, e repete até que o resultado esteja correto. Tudo sem intervenção manual.

O que muda sem a skill

Sem a skill, o Claude não saberia que a ferramenta existe, não conheceria os parâmetros disponíveis e ficaria dependente de screenshots manuais que eu enviasse.

A diferença em relação ao primeiro exemplo: ali o valor era padronização e consistência. Aqui, o valor é autonomia e feedback visual contínuo. É como dar olhos ao Claude.

Exemplo 3: ensinar conhecimento novo (Liquid Glass)

Os dois primeiros exemplos ensinavam o Claude a usar ferramentas CLI. O terceiro é diferente: aqui a skill ensina conhecimento sobre uma tecnologia.

O contexto

Estou desenvolvendo um aplicativo nativo para macOS usando SwiftUI e quero implementar o Liquid Glass, o design language da Apple lançado na WWDC 2025. O problema: essa tecnologia é tão recente que não consta na base de conhecimento dos modelos de IA. A documentação oficial é limitada e há pouco conteúdo disponível.

Armadilhas que a skill documenta

Conforme fui experimentando Liquid Glass na prática, descobri várias armadilhas que não são óbvias. E conforme eu descobria coisas importantes, ia documentando tudo dentro de uma skill:

Usar NSButton via NSViewRepresentable não funciona com liquid glass
Colocar botões em HStack dentro de ToolbarItemGroup gera forma oval em vez de circular
Combinar .controlSize(.small) com .buttonBorderShape causa interferência

Sem a skill, o Claude tentaria implementar com base em conhecimento genérico de SwiftUI, cairia nessas armadilhas, e eu teria que repetir as mesmas instruções em toda nova conversa.

Com a skill, o conhecimento fica centralizado, documentado e reutilizável. O Claude consulta automaticamente e aplica as boas práticas corretas.

Quando criar este tipo de skill

Skills informacionais (que ensinam conhecimento, não ferramentas) são úteis em vários cenários:

Tecnologias novas - frameworks ou APIs lançados recentemente que ainda não estão na base de conhecimento dos modelos
Padrões internos da empresa - convenções de código, arquitetura, estrutura de pastas específicas do time
Domínio de negócio - terminologia, regras de negócio, processos únicos do seu contexto
Armadilhas documentadas - problemas que você já enfrentou e resolveu, para evitar repetição

Skills prontas e marketplaces

Além de criar suas próprias skills, é possível usar skills prontas disponíveis nos marketplaces.

A Anthropic disponibiliza skills oficiais que podem ser instaladas diretamente pela interface do Claude Code. Eu considero essas skills seguras porque vêm da própria Anthropic.

Cuidado com skills de terceiros

Ponto de atenção importante: adicionar skills de terceiros pode trazer riscos para o seu sistema. Uma skill sozinha não executa nada - ela é apenas um arquivo Markdown. Mas ela pode conter instruções maliciosas que levem o Claude a executar comandos prejudiciais no seu terminal, acessar arquivos sensíveis ou modificar configurações.

Na prática, o que eu faço:

Uso skills oficiais da Anthropic
Uso minhas próprias skills (sei exatamente o que tem dentro)
Não uso skills de terceiros desconhecidos
Se for usar skill de terceiro, sempre reviso o SKILL.md e o campo allowed-tools

Como criar suas próprias skills

O site da Anthropic tem um guia completo ensinando a criar skills customizadas. Dá para seguir o passo a passo manualmente, mas eu uso um atalho, conforme veremos a seguir.

O truque: uma skill para criar skills

Eu criei uma skill que ensina o Claude a criar outras skills. Isso é bootstrapping: usar o Claude para criar uma ferramenta que ensina o Claude a criar mais ferramentas.

O processo que segui foi simples:

Acessei o guia oficial da Anthropic sobre criação de skills
Colei a URL no Claude Code
Pedi: "Crie uma skill ensinando como criar skills, baseado nessa documentação"

A partir daí, sempre que quero criar uma nova skill, basta pedir: "Crie uma skill para X". O Claude já sabe a estrutura correta, o formato, e onde salvar.

Boa prática: indexar no CLAUDE.md

Depois de criar uma skill, considero uma boa prática mencionar brevemente no CLAUDE.md global que essa skill existe. Não é obrigatório - as skills funcionam sem isso. Mas funciona como um índice rápido que ajuda o Claude a localizar skills com mais facilidade, especialmente quando você tem muitas.

Skills vs MCP Servers vs Plugins

Uma dúvida comum: qual a diferença entre Skills, MCP Servers e Plugins? São camadas complementares, não concorrentes. Vou explicar brevemente cada uma.

Skills: conhecimento interno

Como vimos anteriormente, skills são arquivos Markdown que o Claude carrega automaticamente. Zero infraestrutura (só um arquivo de texto), zero overhead quando não estão em uso. O conteúdo completo só carrega quando a skill é relevante para a conversa.

MCP Servers: conexões externas

São servidores que conectam o Claude com sistemas externos via Model Context Protocol (JSON-RPC). Cada MCP é um processo em background (Python, Node.js, etc.) que consome recursos durante toda a sessão. Quando abro o Claude Code, todos os MCPs configurados iniciam automaticamente. Quando fecho, são encerrados.

Plugins: empacotamento

São containers que agrupam Skills, MCP Servers, Hooks e Agents em um pacote distribuível. Úteis para compartilhar configurações completas com o time.

Quando usar cada um

A regra prática que eu sigo:

**Se quero simplesmente dar conhecimento adicional ao Claude sobre determinado tema, ou ensiná-lo a usar uma CLI tool, uso Skill. Zero processos em background, zero overhead, máxima simplicidade.
Se o que o Claude tiver que fazer demandar uma ferramenta que precisa de conexão persistente com sistema externo (GitHub, Slack, banco de dados) uso MCP. Mantém sessão autenticada, queries estruturadas, validação de schemas.

Overhead comparado

Skills (md2docx):
  Arquivo .md carregado na memoria (~2KB)
  Zero processos em background
  Execucao: Claude invoca bash -> md2docx inicia -> executa -> termina
  Overhead: ~0MB quando nao usado

MCP (GitHub integration):
  Processo Node.js rodando o tempo todo (~80MB RAM)
  Consome recursos mesmo sem uso
  Execucao: Claude -> JSON-RPC -> servidor ja ativo
  Overhead: ~80MB constante

Uso combinado

Os três trabalham juntos. Um exemplo: imagine um workflow de deployment automatizado.

Skill - ensina boas práticas de deployment (checklist, validações)
MCP Server - conecta com AWS/Vercel para fazer o deploy real
Plugin - empacota tudo (skill + MCP + hooks de pre-deploy) para distribuir ao time

A pergunta que resume tudo

A forma mais simples de pensar em skills:

"O que eu gostaria que o Claude soubesse antes de começar a trabalhar comigo?"

Pode ser como usar uma ferramenta, como trabalhar com uma tecnologia, como seguir padrões da empresa, ou como evitar armadilhas conhecidas.

Essa resposta é a sua skill.