Este guia mostra como criar, usar e gerenciar Habilidades do Agente no Claude Code. Habilidades são capacidades modulares que estendem a funcionalidade do Claude através de pastas organizadas contendo instruções, scripts e recursos.

​
Pré-requisitos

  • Claude Code versão 1.0 ou posterior
  • Familiaridade básica com Claude Code

​
O que são Habilidades do Agente?

Habilidades do Agente empacotam expertise em capacidades descobríveis. Cada Habilidade consiste em um arquivo SKILL.md com instruções que o Claude lê quando relevante, além de arquivos de suporte opcionais como scripts e templates. Como as Habilidades são invocadas: As Habilidades são invocadas pelo modelo—o Claude decide autonomamente quando usá-las com base na sua solicitação e na descrição da Habilidade. Isso é diferente dos comandos de barra, que são invocados pelo usuário (você digita explicitamente /comando para acioná-los). Benefícios:
  • Estender as capacidades do Claude para seus fluxos de trabalho específicos
  • Compartilhar expertise através da sua equipe via git
  • Reduzir prompts repetitivos
  • Compor múltiplas Habilidades para tarefas complexas
Saiba mais na visão geral das Habilidades do Agente.
Para um mergulho profundo na arquitetura e aplicações do mundo real das Habilidades do Agente, leia nosso blog de engenharia: Equipando agentes para o mundo real com Habilidades do Agente.

​
Criar uma Habilidade

Habilidades são armazenadas como diretórios contendo um arquivo SKILL.md.

​
Habilidades Pessoais

Habilidades Pessoais estão disponíveis em todos os seus projetos. Armazene-as em ~/.claude/skills/: 
mkdir -p ~/.claude/skills/meu-nome-da-habilidade
Use Habilidades pessoais para:
  • Seus fluxos de trabalho individuais e preferências
  • Habilidades experimentais que você está desenvolvendo
  • Ferramentas de produtividade pessoal

​
Habilidades de Projeto

Habilidades de Projeto são compartilhadas com sua equipe. Armazene-as em .claude/skills/ dentro do seu projeto: 
mkdir -p .claude/skills/meu-nome-da-habilidade
Use Habilidades de projeto para:
  • Fluxos de trabalho e convenções da equipe
  • Expertise específica do projeto
  • Utilitários e scripts compartilhados
Habilidades de Projeto são commitadas no git e automaticamente disponíveis para membros da equipe.

​
Habilidades de Plugin

Habilidades também podem vir de plugins do Claude Code. Plugins podem incluir Habilidades que ficam automaticamente disponíveis quando o plugin é instalado. Essas Habilidades funcionam da mesma forma que Habilidades pessoais e de projeto.

​
Escrever SKILL.md

Crie um arquivo SKILL.md com frontmatter YAML e conteúdo Markdown: 
---
name: Nome da Sua Habilidade
description: Breve descrição do que esta Habilidade faz e quando usá-la
---

# Nome da Sua Habilidade

## Instruções
Forneça orientação clara e passo a passo para o Claude.

## Exemplos
Mostre exemplos concretos de uso desta Habilidade.
O campo description é crítico para o Claude descobrir quando usar sua Habilidade. Deve incluir tanto o que a Habilidade faz quanto quando o Claude deve usá-la. Veja o guia de melhores práticas para orientação completa de criação.

​
Adicionar arquivos de suporte

Crie arquivos adicionais junto com SKILL.md: 
minha-habilidade/
├── SKILL.md (obrigatório)
├── reference.md (documentação opcional)
├── examples.md (exemplos opcionais)
├── scripts/
│   └── helper.py (utilitário opcional)
└── templates/
    └── template.txt (template opcional)
Referencie esses arquivos do SKILL.md: 
Para uso avançado, veja [reference.md](reference.md).

Execute o script auxiliar:
```bash
python scripts/helper.py input.txt
```
O Claude lê esses arquivos apenas quando necessário, usando divulgação progressiva para gerenciar o contexto de forma eficiente.

​
Restringir acesso a ferramentas com allowed-tools

Use o campo frontmatter allowed-tools para limitar quais ferramentas o Claude pode usar quando uma Habilidade está ativa: 
---
name: Leitor de Arquivo Seguro
description: Ler arquivos sem fazer alterações. Use quando precisar de acesso somente leitura a arquivos.
allowed-tools: Read, Grep, Glob
---

# Leitor de Arquivo Seguro

Esta Habilidade fornece acesso somente leitura a arquivos.

## Instruções
1. Use Read para visualizar conteúdo de arquivos
2. Use Grep para buscar dentro de arquivos
3. Use Glob para encontrar arquivos por padrão
Quando esta Habilidade está ativa, o Claude pode usar apenas as ferramentas especificadas (Read, Grep, Glob) sem precisar pedir permissão. Isso é útil para:
  • Habilidades somente leitura que não devem modificar arquivos
  • Habilidades com escopo limitado (ex: apenas análise de dados, sem escrita de arquivos)
  • Fluxos de trabalho sensíveis à segurança onde você quer restringir capacidades
Se allowed-tools não for especificado, o Claude pedirá permissão para usar ferramentas normalmente, seguindo o modelo de permissão padrão.
allowed-tools é suportado apenas para Habilidades no Claude Code.

​
Visualizar Habilidades disponíveis

Habilidades são automaticamente descobertas pelo Claude de três fontes:
  • Habilidades Pessoais: ~/.claude/skills/
  • Habilidades de Projeto: .claude/skills/
  • Habilidades de Plugin: incluídas com plugins instalados
Para visualizar todas as Habilidades disponíveis, pergunte diretamente ao Claude: 
Quais Habilidades estão disponíveis?
ou 
Liste todas as Habilidades disponíveis
Isso mostrará todas as Habilidades de todas as fontes, incluindo Habilidades de plugin. Para inspecionar uma Habilidade específica, você também pode verificar o sistema de arquivos: 
# Listar Habilidades pessoais
ls ~/.claude/skills/

# Listar Habilidades de projeto (se em um diretório de projeto)
ls .claude/skills/

# Visualizar conteúdo de uma Habilidade específica
cat ~/.claude/skills/minha-habilidade/SKILL.md

​
Testar uma Habilidade

Após criar uma Habilidade, teste-a fazendo perguntas que correspondam à sua descrição. Exemplo: Se sua descrição menciona “arquivos PDF”: 
Você pode me ajudar a extrair texto deste PDF?
O Claude decide autonomamente usar sua Habilidade se ela corresponder à solicitação—você não precisa invocá-la explicitamente. A Habilidade ativa automaticamente com base no contexto da sua pergunta.

​
Debugar uma Habilidade

Se o Claude não usar sua Habilidade, verifique esses problemas comuns:

​
Tornar descrição específica

Muito vaga: 
description: Ajuda com documentos
Específica: 
description: Extrair texto e tabelas de arquivos PDF, preencher formulários, mesclar documentos. Use quando trabalhar com arquivos PDF ou quando o usuário mencionar PDFs, formulários ou extração de documentos.
Inclua tanto o que a Habilidade faz quanto quando usá-la na descrição.

​
Verificar caminho do arquivo

Habilidades Pessoais: ~/.claude/skills/nome-da-habilidade/SKILL.md Habilidades de Projeto: .claude/skills/nome-da-habilidade/SKILL.md Verifique se o arquivo existe: 
# Pessoal
ls ~/.claude/skills/minha-habilidade/SKILL.md

# Projeto
ls .claude/skills/minha-habilidade/SKILL.md

​
Verificar sintaxe YAML

YAML inválido impede que a Habilidade carregue. Verifique o frontmatter: 
cat SKILL.md | head -n 10
Certifique-se:
  • --- de abertura na linha 1
  • --- de fechamento antes do conteúdo Markdown
  • Sintaxe YAML válida (sem tabs, indentação correta)

​
Visualizar erros

Execute o Claude Code com modo debug para ver erros de carregamento de Habilidades: 
claude --debug

​
Compartilhar Habilidades com sua equipe

Abordagem recomendada: Distribua Habilidades através de plugins. Para compartilhar Habilidades via plugin:
  1. Crie um plugin com Habilidades no diretório skills/
  2. Adicione o plugin a um marketplace
  3. Membros da equipe instalam o plugin
Para instruções completas, veja Adicionar Habilidades ao seu plugin. Você também pode compartilhar Habilidades diretamente através de repositórios de projeto:

​
Passo 1: Adicionar Habilidade ao seu projeto

Crie uma Habilidade de projeto: 
mkdir -p .claude/skills/habilidade-da-equipe
# Criar SKILL.md

​
Passo 2: Commitar no git

git add .claude/skills/
git commit -m "Adicionar Habilidade da equipe para processamento de PDF"
git push

​
Passo 3: Membros da equipe obtêm Habilidades automaticamente

Quando membros da equipe fazem pull das últimas alterações, as Habilidades ficam imediatamente disponíveis: 
git pull
claude  # Habilidades agora estão disponíveis

​
Atualizar uma Habilidade

Edite SKILL.md diretamente: 
# Habilidade Pessoal
code ~/.claude/skills/minha-habilidade/SKILL.md

# Habilidade de Projeto
code .claude/skills/minha-habilidade/SKILL.md
Alterações fazem efeito na próxima vez que você iniciar o Claude Code. Se o Claude Code já estiver rodando, reinicie-o para carregar as atualizações.

​
Remover uma Habilidade

Delete o diretório da Habilidade: 
# Pessoal
rm -rf ~/.claude/skills/minha-habilidade

# Projeto
rm -rf .claude/skills/minha-habilidade
git commit -m "Remover Habilidade não utilizada"

​
Melhores práticas

​
Manter Habilidades focadas

Uma Habilidade deve abordar uma capacidade: Focada:
  • “Preenchimento de formulários PDF”
  • “Análise de dados Excel”
  • “Mensagens de commit Git”
Muito ampla:
  • “Processamento de documentos” (dividir em Habilidades separadas)
  • “Ferramentas de dados” (dividir por tipo de dados ou operação)

​
Escrever descrições claras

Ajude o Claude a descobrir quando usar Habilidades incluindo gatilhos específicos na sua descrição: Clara: 
description: Analisar planilhas Excel, criar tabelas dinâmicas e gerar gráficos. Use quando trabalhar com arquivos Excel, planilhas ou analisar dados tabulares em formato .xlsx.
Vaga: 
description: Para arquivos

​
Testar com sua equipe

Faça com que colegas de equipe usem Habilidades e forneçam feedback:
  • A Habilidade ativa quando esperado?
  • As instruções estão claras?
  • Há exemplos ou casos extremos faltando?

​
Documentar versões de Habilidades

Você pode documentar versões de Habilidades no seu conteúdo SKILL.md para rastrear mudanças ao longo do tempo. Adicione uma seção de histórico de versões: 
# Minha Habilidade

## Histórico de Versões
- v2.0.0 (2025-10-01): Mudanças que quebram compatibilidade na API
- v1.1.0 (2025-09-15): Adicionadas novas funcionalidades
- v1.0.0 (2025-09-01): Lançamento inicial
Isso ajuda membros da equipe a entender o que mudou entre versões.

​
Solução de problemas

​
Claude não usa minha Habilidade

Sintoma: Você faz uma pergunta relevante mas o Claude não usa sua Habilidade. Verificar: A descrição é específica o suficiente? Descrições vagas tornam a descoberta difícil. Inclua tanto o que a Habilidade faz quanto quando usá-la, com termos-chave que usuários mencionariam. Muito genérica: 
description: Ajuda com dados
Específica: 
description: Analisar planilhas Excel, gerar tabelas dinâmicas, criar gráficos. Use quando trabalhar com arquivos Excel, planilhas ou arquivos .xlsx.
Verificar: O YAML é válido? Execute validação para verificar erros de sintaxe: 
# Visualizar frontmatter
cat .claude/skills/minha-habilidade/SKILL.md | head -n 15

# Verificar problemas comuns
# - --- de abertura ou fechamento faltando
# - Tabs em vez de espaços
# - Strings sem aspas com caracteres especiais
Verificar: A Habilidade está no local correto? 
# Habilidades Pessoais
ls ~/.claude/skills/*/SKILL.md

# Habilidades de Projeto
ls .claude/skills/*/SKILL.md

​
Habilidade tem erros

Sintoma: A Habilidade carrega mas não funciona corretamente. Verificar: As dependências estão disponíveis? O Claude instalará automaticamente dependências necessárias (ou pedirá permissão para instalá-las) quando precisar delas. Verificar: Scripts têm permissões de execução? 
chmod +x .claude/skills/minha-habilidade/scripts/*.py
Verificar: Os caminhos de arquivo estão corretos? Use barras normais (estilo Unix) em todos os caminhos: Correto: scripts/helper.py Errado: scripts\helper.py (estilo Windows)

​
Múltiplas Habilidades conflitam

Sintoma: O Claude usa a Habilidade errada ou parece confuso entre Habilidades similares. Seja específico nas descrições: Ajude o Claude a escolher a Habilidade certa usando termos de gatilho distintos nas suas descrições. Em vez de: 
# Habilidade 1
description: Para análise de dados

# Habilidade 2
description: Para analisar dados
Use: 
# Habilidade 1
description: Analisar dados de vendas em arquivos Excel e exportações de CRM. Use para relatórios de vendas, análise de pipeline e rastreamento de receita.

# Habilidade 2
description: Analisar arquivos de log e dados de métricas do sistema. Use para monitoramento de performance, debugging e diagnósticos do sistema.

​
Exemplos

​
Habilidade Simples (arquivo único)

commit-helper/
└── SKILL.md

---
name: Gerando Mensagens de Commit
description: Gera mensagens de commit claras a partir de diffs do git. Use quando escrever mensagens de commit ou revisar mudanças em stage.
---

# Gerando Mensagens de Commit

## Instruções

1. Execute `git diff --staged` para ver mudanças
2. Vou sugerir uma mensagem de commit com:
   - Resumo com menos de 50 caracteres
   - Descrição detalhada
   - Componentes afetados

## Melhores práticas

- Use tempo presente
- Explique o que e por que, não como

​
Habilidade com permissões de ferramenta

code-reviewer/
└── SKILL.md

---
name: Revisor de Código
description: Revisar código para melhores práticas e problemas potenciais. Use quando revisar código, verificar PRs ou analisar qualidade do código.
allowed-tools: Read, Grep, Glob
---

# Revisor de Código

## Lista de verificação de revisão

1. Organização e estrutura do código
2. Tratamento de erros
3. Considerações de performance
4. Preocupações de segurança
5. Cobertura de testes

## Instruções

1. Leia os arquivos alvo usando a ferramenta Read
2. Busque por padrões usando Grep
3. Encontre arquivos relacionados usando Glob
4. Forneça feedback detalhado sobre qualidade do código

​
Habilidade Multi-arquivo

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
SKILL.md: 
---
name: Processamento de PDF
description: Extrair texto, preencher formulários, mesclar PDFs. Use quando trabalhar com arquivos PDF, formulários ou extração de documentos. Requer pacotes pypdf e pdfplumber.
---

# Processamento de PDF

## Início rápido

Extrair texto:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Para preenchimento de formulários, veja [FORMS.md](FORMS.md).
Para referência detalhada da API, veja [REFERENCE.md](REFERENCE.md).

## Requisitos

Pacotes devem ser instalados no seu ambiente:
```bash
pip install pypdf pdfplumber
```
Liste pacotes necessários na descrição. Pacotes devem ser instalados no seu ambiente antes que o Claude possa usá-los.
O Claude carrega arquivos adicionais apenas quando necessário.

​
Próximos passos

Melhores práticas de criação

Escreva Habilidades que o Claude pode usar efetivamente

Visão geral das Habilidades do Agente

Aprenda como Habilidades funcionam através dos produtos Claude

Começar com Habilidades do Agente

Crie sua primeira Habilidade