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
- Agent Skills (Claude Platform docs)conferido em 14 de nov. de 2026
- Extend Claude with skills (Claude Code docs)conferido em 14 de nov. de 2026
- Agent Skills specificationconferido em 14 de nov. de 2026
- anthropics/skills repositoryconferido em 14 de nov. de 2026
- Equipping agents for the real world with Agent Skills (Anthropic Engineering)conferido em 14 de nov. de 2026
- Build skills (Codex docs)conferido em 14 de nov. de 2026
- Agent Skills (Gemini CLI docs)conferido em 14 de nov. de 2026
Mais guias
- Como conectar servidores MCP ao Claude, ao ChatGPT e ao Cursor
- Como criar um servidor MCP
- Como criar skills personalizadas para o Claude Code
- Segurança no MCP: perguntas para fazer antes de instalar um servidor ou uma skill
- MCP vs. API: qual é a diferença?
- MCP vs. skills: a diferença entre servidores MCP e skills de agente
- O que é um servidor MCP?