Pular para o conteúdo
Kitbay

O que é uma skill do Claude?

Pela equipe editorial do Kitbay ·

Uma skill do Claude é uma pasta de instruções organizada em torno de um arquivo chamado SKILL.md, que ensina o Claude a realizar um tipo específico de tarefa. O Claude mantém à vista apenas o nome e a descrição de cada skill e só abre as instruções completas, os scripts e os arquivos de referência quando um pedido precisa deles.

Para que serve uma skill

Pense em uma skill como um procedimento escrito que, sem ela, você repetiria em cada chat: o formato de relatório da sua equipe, um checklist de release, os passos para preencher um formulário em PDF ou as regras para consultar um banco de dados interno. A documentação da Anthropic compara uma skill a um guia de onboarding para um colega novo: ela guarda o know-how, e o Claude o aplica quando a tarefa aparece.

A documentação do Claude Code dá um critério prático. Se você vive colando as mesmas instruções em uma conversa, esse texto é candidato a virar skill. Ao contrário das notas de projeto, que ficam sempre carregadas, o corpo principal de uma skill só entra na conversa quando ela é usada.

As skills seguem o formato aberto Agent Skills, publicado em agentskills.io, que a Anthropic lançou como padrão aberto em dezembro de 2025. Por isso, a mesma pasta pode funcionar fora do Claude. O Codex lê skills de pastas .agents/skills, e o Gemini CLI as lê de .gemini/skills ou .agents/skills, segundo a documentação de cada ferramenta.

O que tem dentro de uma skill

Uma skill é um diretório. Só o SKILL.md é obrigatório; todo o resto é opcional.

pdf-forms/
├── SKILL.md        required: front matter + instructions
├── scripts/        code the agent can run
├── references/     extra documents read on demand
└── assets/         templates, images, data files

O SKILL.md e o front matter

O SKILL.md começa com um front matter em YAML entre duas linhas ---, seguido das instruções em Markdown. A especificação Agent Skills define estes campos:

Campo Obrigatório O que a especificação diz
name Sim Até 64 caracteres; letras minúsculas, dígitos e hífens; sem hífen no início ou no fim, sem hífens duplos; precisa ser igual ao nome da pasta
description Sim Até 1.024 caracteres; deve dizer o que a skill faz e quando usá-la
license Não O nome de uma licença ou uma referência a um arquivo de licença incluído
compatibility Não Até 500 caracteres sobre requisitos de ambiente, como pacotes necessários ou acesso à rede
metadata Não Chaves e valores de texto livres
allowed-tools Não Ferramentas pré-aprovadas; marcado como experimental, e o suporte varia de agente para agente

A API da Anthropic acrescenta dois limites próprios: o nome não pode conter as palavras reservadas "anthropic" ou "claude", e nenhum dos dois campos pode conter tags XML.

A descrição é o que mais importa. É com esse texto que o Claude compara o seu pedido para decidir se abre a skill, então ela precisa citar tanto a tarefa quanto as situações em que a skill deve ser acionada.

O Claude Code aceita campos extras no front matter, como disable-model-invocation (só você pode iniciar a skill) e context: fork (executa a skill em um subagente). A documentação avisa que, fora do Claude Code, por exemplo ao enviar a skill para o claude.ai, só os campos padrão são aceitos, e chaves desconhecidas geram erro.

As instruções

O corpo em Markdown não tem formato fixo. O conteúdo mais comum são instruções passo a passo, exemplos de entrada e saída e observações sobre casos-limite. Tanto a Anthropic quanto a especificação sugerem manter o arquivo principal com menos de 500 linhas e mover o material mais longo para arquivos separados.

Scripts

Os arquivos em scripts/ são programas que o agente executa, geralmente em Python, Bash ou JavaScript. Quando o Claude executa um deles, o código em si fica fora da conversa; só a saída é adicionada. A Anthropic apresenta isso como uma forma de tornar repetíveis operações fixas, como validar um formulário, em vez de fazer o modelo reescrever o código toda vez.

Arquivos de referência e assets

A pasta references/ guarda documentação que o agente só lê quando uma etapa precisa dela, como uma referência de API ou o schema de um banco de dados. A pasta assets/ guarda modelos, imagens e arquivos de dados. A especificação recomenda criar links diretos para esses arquivos a partir do SKILL.md e evitar cadeias de arquivos que apontam para outros arquivos.

Como o Claude carrega uma skill

As skills são carregadas em etapas, um design que a Anthropic chama de progressive disclosure (revelação progressiva):

Etapa Quando Custo aproximado
Nome e descrição No início de cada sessão Cerca de 100 tokens por skill
Corpo do SKILL.md Quando um pedido corresponde à descrição Recomendado: menos de 5.000 tokens
Scripts, referências, assets Só quando as instruções apontam para eles Nada até serem lidos; scripts só adicionam a saída

Veja uma sequência típica. Você pede ao Claude para extrair o texto de um PDF. O Claude percebe que a descrição de uma skill de PDF se encaixa, lê o SKILL.md dela, segue as instruções e pula a referência sobre preenchimento de formulários, porque a tarefa não precisa dela.

No Claude Code, você também pode iniciar uma skill digitando / seguido do nome dela, por exemplo /summarize-changes. Depois de carregadas, as instruções ficam na conversa para as próximas interações.

Onde as skills do Claude funcionam

  • Claude Code: as skills pessoais ficam em ~/.claude/skills/<name>/SKILL.md, as skills de projeto ficam em .claude/skills/ dentro de um repositório, e plugins podem trazer outras.
  • claude.ai: você envia a skill como um arquivo zip. A Anthropic informa que skills personalizadas estão disponíveis nos planos Pro, Max, Ultra, Team e Enterprise com a execução de código ativada.
  • Claude API: as skills rodam dentro do contêiner de execução de código. A Anthropic oferece skills prontas para arquivos PowerPoint, Excel, Word e PDF, e você pode enviar as suas. Skills na API não têm acesso à rede.

Skills personalizadas não são sincronizadas entre esses lugares. Uma skill adicionada no claude.ai não fica disponível pela API, e as skills do Claude Code são separadas das duas.

Skills e servidores MCP

Uma skill ensina um procedimento; um servidor MCP dá ao agente uma conexão ativa com outro sistema. Os dois costumam ser usados juntos: um servidor lê o seu gerenciador de projetos, e uma skill descreve como a sua equipe escreve tickets. Nosso guia sobre servidores MCP vs. skills de agente explica a diferença em detalhes, e o que é um servidor MCP explica a outra metade.

Uma observação rápida sobre segurança

Uma skill pode mandar o agente executar código e usar as ferramentas dele nos seus arquivos e contas. A Anthropic recomenda usar apenas skills de fontes confiáveis e ler antes todos os arquivos incluídos, procurando chamadas de rede ou acessos a arquivos que não combinem com o propósito declarado da skill. No Claude Code, as skills têm o mesmo acesso à rede que qualquer outro programa no seu computador. Nossas perguntas de segurança sobre servidores e skills trazem um checklist mais completo.

Encontre e crie skills

Veja as skills de agente listadas no Kitbay ou comece por uma tarefa, como skills para trabalhar com documentos ou escrita e revisão. Cada listagem mostra se a skill inclui scripts e tem um link para o código-fonte. Para criar a sua, veja como criar uma skill.

Perguntas

O que é uma skill no Claude?
Uma skill é uma pasta com um arquivo SKILL.md que traz um nome, uma descrição e instruções. O Claude vê o nome e a descrição o tempo todo e só lê as instruções completas quando o seu pedido corresponde a elas.
As skills só funcionam com o Claude?
Não. As skills seguem o formato aberto Agent Skills, e outros agentes, como o Codex e o Gemini CLI, documentam suporte a pastas com SKILL.md. Campos específicos de um produto podem ser ignorados ou rejeitados em outros.
Uma skill pode executar código?
Sim. Uma skill pode incluir scripts que o agente executa, e só a saída do script entra na conversa. Por isso, leia os arquivos de uma skill antes de instalá-la.
Minhas skills são sincronizadas entre o Claude Code, o claude.ai e a API?
Não. A documentação da Anthropic diz que skills personalizadas não são sincronizadas entre as plataformas, então você precisa adicioná-las separadamente em cada lugar onde as usa.

Fontes

Mais guias