Guia Claude Code Skills: Criar, Compartilhar e Ampliar

Ei, pessoal, Lena aqui. Algo mudou silenciosamente no final de 2025. Não percebi de uma vez — veio devagar, do jeito que a maioria das mudanças reais vem.

Eu estava observando como Claude Code lidava com tarefas repetidas em vários projetos. O padrão era familiar: as mesmas instruções, reescritas de forma ligeiramente diferente a cada vez. O mesmo contexto, reexplicado. Começou a parecer que algo estava faltando — não no modelo, mas na ​camada entre o modelo e o trabalho​.

Essa camada agora tem um nome. Chama-se ​Claude Code Skills​.

O Que São Claude Code Skills?

No nível mais simples, uma skill de Claude Code é uma pasta. Dentro dessa pasta existe um arquivo chamado SKILL.md. Quando Claude Code encontra essa pasta, ele lê o arquivo, carrega as instruções no contexto e ajusta seu comportamento de acordo.

Continuo voltando a essa descrição porque soa quase simples demais. E ainda assim, as implicações — uma vez que você as considera — são maiores do que parecem à primeira vista.

Skills não são prompts que você cola no início de toda conversa. São pacotes comportamentais reutilizáveis que Claude descobre e aplica automaticamente. Você instala uma vez. Claude pega o contexto sempre que for relevante — sem ser lembrado.

O Formato SKILL.md — Como Funciona

Cada skill começa com a mesma estrutura de duas partes. SKILL.md é um arquivo markdown que segue uma estrutura de duas partes — frontmatter e conteúdo. O frontmatter configura como a skill funciona (permissões, modelo, metadados), enquanto o conteúdo markdown diz ao Claude o que fazer.

Um exemplo mínimo se parece com isto:

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Instructions Claude will follow when this skill is active]

O campo name se torna o comando barra. O campo description é o que Claude lê ao decidir se deve carregar a skill ou não. A descrição é crítica para a seleção da skill — Claude a utiliza para escolher a skill certa dentre possivelmente mais de 100 skills disponíveis. Sua descrição deve fornecer detalhes suficientes para Claude saber quando selecionar esta skill, enquanto o restante do SKILL.md fornece os detalhes de implementação.

Essa última parte é fácil de subestimar. Eu errei nas minhas primeiras tentativas — escrevi descrições que eram tecnicamente precisas, mas comportamentalmente vagas. A skill carregava nos momentos errados, ou não carregava de forma alguma. A descrição não é metadado. É uma decisão de roteamento.

Você pode ler a documentação oficial de Claude Code Skills para uma explicação completa da especificação.

Que Tipos de Comportamentos Você Pode Codificar

É aqui que fica interessante. As habilidades não se limitam a instruções de texto. Cada habilidade é um diretório que pode incluir um arquivo principal SKILL.md, modelos para Claude preencher, exemplos de saída mostrando o formato esperado e scripts que Claude pode executar.

Na prática, isso significa que você pode codificar:

• Convenções de codificação — como sua equipe nomeia funções, estrutura testes, trata erros
• Padrões de fluxo de trabalho — processos em várias etapas que Claude deve seguir ao gerar relatórios ou processar arquivos
• Scripts executáveis — lógica de validação, transformações de arquivos, chamadas a APIs externas que rodam de forma determinística
• Documentos de referência — especificações detalhadas que Claude lê sob demanda, sem inchar cada sessão

A principal percepção de design: quando uma habilidade é acionada, Claude usa bash para ler SKILL.md do sistema de arquivos, trazendo suas instruções para a janela de contexto. Se essas instruções fizerem referência a outros arquivos, Claude também os lê. Quando as instruções mencionam scripts executáveis, Claude os executa e recebe apenas a saída — o código do script em si nunca entra no contexto.

Este é um ponto sutil, mas importante. A habilidade é ​lazy-loaded​. Você pode agrupar um documento de referência de 50 páginas em uma habilidade, e Claude só puxará o que ele realmente precisa.

Construindo Sua Primeira Habilidade para Claude Code

Serei honesto — minha primeira habilidade foi ruim. Não quebrada, apenas... imprecisa. Ela carregava de forma muito ampla, suas instruções competiam com a conversa, e eu gastava mais tempo explicando o que queria do que se tivesse apenas digitado.

Aqui está o que eu faria diferente.

Localização e Formato de Arquivos

Para Claude Code, as habilidades vivem em .claude/skills/ dentro do diretório do seu projeto, ou ~/.claude/skills/ para habilidades pessoais que se aplicam globalmente. Claude Code suporta apenas Habilidades Personalizadas — crie habilidades como diretórios com arquivos SKILL.md.

O nome da pasta se torna a identidade da habilidade. Mantenha em minúsculas, use hífens. Dentro:

my-skill/
├── SKILL.md          ← required
├── examples/         ← optional but helpful
│   └── sample.md
└── scripts/          ← optional
    └── validate.sh

O frontmatter do SKILL.md requer dois campos: name e description. O campo name deve usar apenas letras minúsculas, números e hífens. Sempre escreva a descrição na terceira pessoa — a descrição é injetada no prompt do sistema, e inconsistências no ponto de vista podem causar problemas de descoberta.

Testando Se Sua Habilidade Está Sendo Aplicada

Isso me confundiu no começo. Não há uma notificação explícita de "habilidade carregada" na interface. O que eu descobri que funciona: pergunte diretamente ao Claude. "Quais habilidades você tem acesso?" geralmente exibe a lista. Você também pode verificar se o comportamento do Claude muda em prompts específicos de tarefas que deveriam acionar a habilidade.

O teste mais confiável é comportamental — execute a mesma tarefa com e sem a habilidade ativa. Se o padrão de saída mudar na direção que você codificou, a habilidade está funcionando. Entender o mecanismo de acionamento ajuda a projetar habilidades melhores. As habilidades aparecem na lista de habilidades disponíveis do Claude com seu nome e descrição, e Claude decide se consulta uma habilidade com base nessa descrição. O Claude só consulta habilidades para tarefas que não consegue realizar facilmente sozinho — consultas simples, de um único passo, podem não acionar uma habilidade mesmo que a descrição corresponda.

Erros Comuns no Design de Habilidades

O guia de melhores práticas para autoria de habilidades da Anthropic cobre isso bem, mas os erros que vi com mais frequência são:

• Descrições vagas — Claude não consegue direcionar para uma habilidade que não entende exatamente
• SKILL.md sobrecarregado — tentar codificar tudo em um único arquivo; use referências para detalhes
• Sem exemplos — habilidades sem exemplos concretos produzem saídas inconsistentes
• Instruções desatualizadas — não inclua informações que ficarão desatualizadas; instruções específicas de versão devem estar em seções recolhíveis ou claramente datadas

Compartilhando Habilidades Entre Projetos e Equipes

É aqui que as coisas ficam realmente úteis — e também onde as limitações atuais se tornam visíveis.

Limitações Atuais do Compartilhamento de SKILL.md

As habilidades são baseadas em arquivos. Isso significa que compartilhá-las requer distribuição de arquivos: pastas zip, repositórios Git, cópia manual. O modelo de distribuição atual exige que usuários individuais baixem a pasta da habilidade e a coloquem no diretório de habilidades Claude Code. Habilidades a nível de organização podem ser implantadas em todo o workspace por administradores — isso foi lançado em dezembro de 2025 — com atualizações automáticas e gerenciamento centralizado.

Isso é uma melhoria significativa. Mas ainda significa que a habilidade existe como um artefato estático. Quando o fluxo de trabalho subjacente que ela codifica muda, a habilidade não se atualiza automaticamente. Alguém precisa mantê-la.

Em dezembro de 2025, a Anthropic lançou a especificação Agent Skills como um padrão aberto, e a OpenAI adotou o mesmo formato para o Codex CLI. As skills são invocadas pelo modelo — a IA decide automaticamente quando usá-las com base no contexto. Essa interoperabilidade é real e valiosa. Uma skill que você cria para o Claude Code pode, em princípio, rodar no Cursor ou em outros ambientes compatíveis. Você pode navegar pelo repositório de skills da Anthropic no GitHub para ver exemplos contribuídos pela comunidade.

Como é uma Camada de Compartilhamento entre Agentes

Essa é a parte que ainda estou tentando entender.

No momento, uma skill é criada por um humano, revisada por um humano e distribuída manualmente. O agente a executa, mas não a melhora. Ele não aprende com os resultados, não propaga variantes bem-sucedidas, não sinaliza quando as instruções se desviaram do que realmente funciona.

Uma verdadeira camada de compartilhamento entre agentes precisaria de algo mais: validação de execução, avaliação de qualidade, rastreamento de versões. O SKILL.md estático captura bem a intenção. Ele não captura o resultado.

Não tenho certeza de ter visto esse problema resolvido de forma limpa em qualquer lugar até agora.

O Teto: Onde as Skills do Claude Code Param de Funcionar

Arquivos Estáticos vs. Aprendizado Adaptativo

Skills são instruções. Elas não observam seu próprio desempenho. Se uma skill codifica um padrão de depuração que era eficaz há seis meses, mas que desde então se tornou menos confiável devido a atualizações do modelo ou mudanças de API, a skill não perceberá. Você perceberá — eventualmente.

Skills são documentos vivos. Planeje iterar com base em como elas performam ao longo do tempo. Esse é um bom conselho, mas coloca o ônus da iteração inteiramente sobre o autor. O agente não pode participar da melhoria da instrução que está seguindo.

Sem Validação de Execução, Sem Ciclo de Reparação

Quando uma skill é executada e o resultado está errado, nada no mecanismo da skill detecta isso. O Claude executa o que o SKILL.md diz. Se o resultado não corresponder à intenção, o ciclo não se fecha automaticamente.

Isso é menos problemático para skills que codificam convenções estáveis (estilo de código, estrutura de documentos) e mais problemático para skills que codificam fluxos de trabalho dinâmicos onde a corretude depende da tarefa.

Sem Rede de Reuso

As skills hoje são ou locais (suas) ou públicas (compartilhadas no GitHub). Não existe uma camada ambiente onde uma solução bem-sucedida para uma classe de problema — testada, validada, rastreada por versão — se torne descobrível e herdável por outros agentes trabalhando em problemas semelhantes.

O marketplace da comunidade SkillsMP é um gesto inicial nessa direção. É útil para descobrir o que outros construíram. Mas as habilidades que ele indexa ainda são arquivos estáticos. Eles não carregam registros de auditoria. Eles não sabem quantas vezes foram aplicados, ou com quais resultados.

O que vem depois das habilidades

De instruções estáticas para capacidades validadas, herdáveis e negociáveis

Tenho pensado nessa pergunta há um tempo.

As habilidades do Claude Code resolvem um problema real: elas tornam o comportamento dos agentes repetível e transferível. Isso não é pouco. Antes das habilidades, o contexto precisava ser restabelecido a cada sessão. Agora não é mais assim.

Mas uma habilidade ainda é um artefato humano. Ela captura o que alguém achava que funcionou. Não carrega evidências do que realmente funcionou, em quais condições, com quais modos de falha.

A próxima camada — seja lá qual for — provavelmente parece menos um formato de arquivo e mais uma capacidade com procedência. Algo que diga: essa abordagem foi tentada nessas condições, teve sucesso nesse ritmo, falhou nesses casos extremos, foi revisada por esses autores e já foi aplicada por esses agentes em situações comparáveis.

Essa é uma infraestrutura diferente de um arquivo markdown.

Ainda não sei o que pensar desse intervalo. Mas não parece aleatório. Parece a próxima coisa a assistir.

! [imagem] (https://cdn.z-image.ai/1774441614198-55.png)

FAQ

1. O que é um arquivo SKILL.md no Claude Code?

SKILL.md contém as instruções principais e é obrigatória para toda habilidade do Código Claude. Ela segue uma estrutura em duas partes: frontmatter YAML, que informa Claude quando usar a habilidade, e conteúdo markdown com instruções que Claude segue quando a habilidade é invocada. Pense nisso como um documento de onboarding — exceto que o agente nunca o esquece.

2. Como eu escrevo uma habilidade Claude Code?

Comece com o frontmatter: name (minúsculas, apenas hífens) e description (terceira pessoa, específico sobre quando invocar). Depois, escreva instruções claras e imperativas no corpo do markdown. Adicione arquivos de suporte — exemplos, scripts, referências — somente quando realmente melhorem o comportamento. Teste comparando a saída da tarefa com e sem a habilidade ativa. Veja as melhores práticas de autoria de habilidades do Anthropic para orientações detalhadas.

3. As habilidades do Claude Code podem ser compartilhadas entre os membros da equipe?

Os administradores da organização podem implantar habilidades em todo o espaço de trabalho, com atualizações automáticas e gerenciamento centralizado — isso foi lançado em dezembro de 2025. Para compartilhamento de código aberto, o GitHub é o canal de distribuição atual. O padrão aberto Agent Skills significa que habilidades criadas para Claude Code também podem funcionar em outras ferramentas compatíveis. A interoperabilidade é real; uma rede centralizada de reutilização com histórico de execução ainda é um problema em aberto.

Continuarei observando como isso evolui. Algo está acontecendo aqui — eu só não vejo completamente onde isso termina ainda.