Como criar Skills personalizadas para o Claude: tutorial passo a passo

Depois de entender o conceito de Skills e como usá-las, chegou a hora de criar as suas. Este tutorial cobre desde um arquivo Markdown de 5 linhas até skills avançadas com scripts executáveis.

A estrutura mínima: skill.md

Toda skill é um diretório contendo no mínimo um arquivo skill.md — o coração da skill. Ele começa com um bloco YAML (frontmatter) com os metadados obrigatórios e depois o corpo em Markdown com as instruções.

Metadados obrigatórios

• name: nome legível da skill (máximo 64 caracteres)
• description: descrição clara do que a skill faz e quando usá-la — é isso que o Claude lê para decidir se ativa ou não sua skill

Metadados opcionais

• dependencies: pacotes de software que a skill precisa (ex: pandas, matplotlib)

Exemplo real: skill de guia de marca

---
name: brand-guidelines
description: Apply company brand guidelines to any document or design. Use when creating external-facing content, presentations, or marketing materials.
---

# Brand Guidelines

## Colors
- Primary: #0066CC (Company Blue)
- Secondary: #FF6600 (Accent Orange)
- Background: #FFFFFF

## Typography
- Headings: Inter, 700 weight
- Body: Inter, 400 weight
- Code: JetBrains Mono

## Voice
- Professional but approachable
- Active voice
- No jargon without explanation

O YAML superior é a primeira camada do sistema de progressive disclosure: informação suficiente para o Claude decidir se deve usar a skill, sem carregar o conteúdo inteiro. Se a skill for relevante, ele carrega o corpo Markdown com as instruções detalhadas.

Adicionando recursos e referências

Se as instruções forem extensas ou tiverem seções que só se aplicam a cenários específicos, distribua o conteúdo em arquivos separados dentro do diretório da skill. Por exemplo, crie um REFERENCE.md com informações complementares e referencie-o no skill.md. O Claude decide se precisa acessar o arquivo adicional durante a execução.

Adicionando scripts executáveis

Para skills avançadas, você pode anexar arquivos de código executável. As skills de documentos da Anthropic, por exemplo, usam Python com bibliotecas como python-pptx, openpyxl e python-docx para manipular arquivos Office. O Claude executa esses scripts no ambiente de container, aplicando a lógica programada aos dados da sua conversa.

Empacotando a skill

A estrutura correta do ZIP:

minha-skill.zip
└── minha-skill/
    ├── skill.md
    └── resources/
        └── REFERENCE.md

Erro comum: zipar os arquivos diretamente na raiz do ZIP, sem a pasta da skill. O Claude não reconhece skills sem o diretório pai.

Testando sua skill

Antes do upload

1. Revise a clareza do skill.md
2. Verifique se a descrição reflete com precisão quando a skill deve ser acionada
3. Confirme que todos os arquivos referenciados existem nos locais corretos
4. Teste mentalmente com prompts de exemplo

Depois do upload no Claude

1. Experimente vários prompts diferentes que deveriam acionar a skill
2. Revise o pensamento do Claude para confirmar que ele está carregando a skill
3. Se o Claude não estiver usando quando esperado, itere na descrição — é quase sempre ali que está o problema

Dica de ouro: durante a iteração, edite os arquivos da skill diretamente na interface do Claude. Selecione o texto que quer mudar, clique em “Edit with Claude” e descreva a alteração. Para skills com múltiplos arquivos, deixe os pedidos de edição em cada um e envie todos juntos — o Claude aplica em uma única passada.

Boas práticas

• Mantenha o foco: skills separadas para fluxos diferentes compõem melhor do que uma skill gigante que tenta fazer tudo
• Descrições específicas: é com base nelas que o Claude decide invocar a skill. “Ajuda com documentos” é vago; “Aplica o template de relatório financeiro Q3 com gráficos de barras” é preciso
• Comece simples: instruções em Markdown primeiro, scripts depois. Você sempre pode expandir
• Use exemplos: inclua entradas e saídas de exemplo no skill.md para o Claude entender o que é sucesso
• Teste incrementalmente: teste após cada mudança significativa, não depois de construir uma skill complexa inteira
• Skills se compõem: embora skills não possam referenciar outras explicitamente, o Claude pode usar múltiplas skills juntas automaticamente — essa composabilidade é um dos recursos mais poderosos
• Siga o padrão aberto: consulte as diretrizes em agentskills.io para que suas skills funcionem em qualquer plataforma que adote o padrão

Segurança

Skills podem incluir ou instruir o Claude a instalar pacotes de terceiros. Revise dependências de código antes de habilitar uma skill — especialmente as recebidas de colegas ou fontes externas. Fique atento a instruções que direcionem o Claude a conectar-se a redes externas não confiáveis.