Skills do Claude Code são pastas com um arquivo SKILL.md que ensinam ao Claude uma tarefa repetível, como revisar um PR ou preparar uma release, e o Claude só carrega uma delas quando seu pedido precisa. Isso faz das skills o lugar certo para instruções que importam em algumas tarefas, mas não em toda sessão. O porém é que uma skill são instruções que seu agente vai seguir, então uma skill da internet merece o mesmo cuidado que um script da internet.
Este post cobre o formato das skills, onde elas ficam, como o Claude as escolhe, como escrever uma boa skill e como encontrar e instalar skills compartilhadas sem entregar algo perigoso ao seu agente.
O que é uma skill do Claude Code
Uma skill é uma pasta. O único arquivo obrigatório é o SKILL.md:
---
name: release-notes
description: Use when the user asks for release notes or a changelog entry for a version.
---
1. Run `git log --oneline <last-tag>..HEAD`.
2. Group the commits into Features, Fixes and Other.
3. Write one plain sentence per change, for users, not developers.
4. Ask before writing to CHANGELOG.md.O frontmatter guarda o name e a description. O corpo é a instrução que o Claude segue depois que a skill é carregada. A pasta também pode guardar scripts e arquivos de referência para os quais as instruções apontam, então uma skill pode dizer “rode scripts/check.sh” ou “leia reference/api.md para a lista de endpoints”.
Onde ficam as skills do Claude Code
| Local | Quem recebe | Uso típico |
|---|---|---|
.claude/skills/<name>/SKILL.md | Todos que trabalham no repositório, pelo git | Fluxos do projeto: deploy, migrações, release |
~/.claude/skills/<name>/SKILL.md | Você, em todo projeto | Hábitos pessoais: seu checklist de revisão, estilo de commit |
O nome da pasta vira o comando, então .claude/skills/release-notes/SKILL.md também pode ser rodada como /release-notes. Digite /skills em uma sessão para listar as skills que o Claude vê. Para os demais comandos de barra, veja o guia rápido de comandos do Claude Code.
Como o Claude decide usar uma skill
No início de uma sessão, o Claude vê as descrições das skills, não o corpo completo. Quando seu pedido combina com uma descrição, ele carrega aquela skill. Daí saem duas consequências:
- A descrição faz o roteamento. “Skill de release notes” é uma descrição fraca. “Use quando o usuário pedir release notes ou uma entrada de changelog para uma versão” diz ao Claude quando recorrer a ela.
- Skills mantêm seu contexto base pequeno. Só as descrições carregam em toda sessão, então tirar instruções específicas de tarefas do
CLAUDE.mde colocá-las em skills deixa cada turno mais leve. Mais sobre isso em janela de contexto do Claude Code.
Skills, CLAUDE.md, subagentes e MCP
Esses quatro se sobrepõem, então ajuda saber qual se encaixa em cada caso.
| Ferramenta | Carregado | Melhor para |
|---|---|---|
CLAUDE.md | Toda sessão, o arquivo inteiro | Regras que sempre valem |
| Skill | Descrição sempre, corpo sob demanda | Um fluxo que você repete de vez em quando |
| Subagente | Quando delegado, no próprio contexto | Trabalho pesado cujos detalhes você não precisa receber de volta |
| Servidor MCP | Definições de ferramentas em toda sessão | Acesso a sistemas ou dados externos |
Se você cola o mesmo parágrafo em prompts duas vezes por semana, isso deveria ser uma skill. Se você precisa que o agente converse com um banco de dados ou uma API, isso é um servidor MCP (o que é um servidor MCP).
Como escrever uma boa skill
- Comece por uma tarefa que você já repete. Anote os passos que você digita hoje.
- Escreva a descrição como um gatilho. Comece com “Use when…” e cite as palavras que um usuário diria.
- Mantenha o corpo curto e ordenado. Passos numerados são melhores que parágrafos.
- Coloque material longo em arquivos. Uma tabela de referência ou um script fica ao lado do
SKILL.md, e o corpo diz quando ler ou rodar. - Diga o que não fazer. “Pergunte antes de escrever no CHANGELOG.md” evita a surpresa que você teria de corrigir à mão.
- Teste em uma sessão nova. Peça a tarefa com suas próprias palavras e confira se o Claude escolhe a skill sem que você mande.
O risco das skills compartilhadas
Compartilhar skills é onde elas ficam úteis, e arriscadas. Uma skill pode mandar seu agente rodar um comando de shell, ler um arquivo fora do projeto ou enviar algo para uma URL. Se seu agente roda com permissões amplas, uma skill maliciosa ou descuidada roda com elas também. O que procurar antes de instalar uma:
- Comandos destrutivos ou privilegiados (
rm -rf,sudo) - Leitura de segredos, como arquivos
.envou chaves SSH - Envio de dados para um host que você não conhece
- Padrões de baixar e executar, como passar
curldireto para um shell - Código ofuscado ou caracteres Unicode ocultos
- Prompt injection: texto que tenta sobrescrever suas instruções
O post sobre segurança de agentes de código com IA trata de permissões e sandbox com mais profundidade.
Gerenciando skills no AgentVera
A galeria de skills do AgentVera fica na página Details de um projeto, em Automation → Skills. Ela tem três visões: Local, Discover e My published.
Local lista as skills no seu computador para os dois agentes que usam pastas de skills:
| Agente | Pasta do projeto | Pasta pessoal |
|---|---|---|
| Claude Code | .claude/skills | ~/.claude/skills |
| Codex | .agents/skills | ~/.codex/skills |
Dali você pode:
- Criar uma com New skill: escolha o Agent (Claude Code ou Codex), o Scope (This project ou All projects), um Name (letras minúsculas, dígitos e hífens) e When should it be used?, que vira a descrição. Create and edit abre o novo
SKILL.md. - Desligar uma skill sem apagá-la. O botão move a pasta para um lugar que as CLIs não varrem.
- Visualizar ou editar o
SKILL.md, copiar uma skill para o outro agente ou escopo, ou apagá-la, o que move a pasta para a Lixeira.
Encontrando e instalando skills com segurança
Discover mostra as skills da sua organização e a galeria pública. Pesquise, escolha uma de 10 categorias (programação, testes, revisão de código, DevOps, dados, documentação, design, segurança, produtividade, outros), filtre por agente e ordene por Popular ou New. A mesma galeria está na web em app.agentvera.dev/skills.
A tela de detalhes de cada skill tem as abas Files, Security e Versions. A aba Security mostra o Server scan. A análise procura comandos destrutivos ou privilegiados, leitura de segredos, chaves embutidas, envio de dados, baixar e executar, código ofuscado, prompt injection, Unicode oculto, endereços IP diretos e hosts externos. Os resultados vão de limpo, passando por informativo, risco baixo, médio e alto, até crítico.
A instalação tem dois passos:
- Download and scan. O AgentVera baixa os arquivos, verifica o SHA-256 deles e os analisa de novo no seu computador.
- Install. Scripts são gravados como arquivos comuns e não ficam executáveis.
Os agentes veem a skill na próxima sessão. Quando uma nova versão é publicada, aparece um botão de atualização ao lado da skill instalada. Skills da galeria só são instaladas para os agentes que elas suportam, Claude Code e Codex.
Skills públicas passam por uma análise de segurança e por revisão de um moderador, mas mesmo assim dê uma olhada nos resultados e nos arquivos. A análise pega padrões; você sabe o que seu projeto deve e não deve fazer.
Compartilhando suas próprias skills
Com um plano Pro ou Team e uma conta no AgentVera, Share publica uma skill local. Você dá a ela um título, um resumo de 20 a 300 caracteres, até 6 tags, uma categoria e uma versão como 1.0.0, com um changelog para cada versão. Uma skill é limitada a 50 arquivos de texto, 256 KB por arquivo e 1 MB no total.
- Organization only: visível para sua organização na hora se a análise não encontrar nada alto ou crítico; caso contrário, é recusada.
- Public: aguarda a aprovação de um moderador, e resultados críticos não são aceitos. Acompanhe em My published.
Skills e uso de tokens
Cada skill adiciona sua descrição ao contexto base. Algumas não pesam; dezenas de skills pessoais se acumulam em cada turno. O perfil de contexto Lean do AgentVera não carrega skills do nível do usuário, que é um dos motivos de a primeira requisição dele ser menor (medido aqui). Mantenha as skills do projeto no repositório e apague as pessoais que você não usa mais.
Resumo
As skills do Claude Code transformam prompts repetidos em pastas que o Claude carrega sob demanda: um SKILL.md com uma descrição clara de “quando usar”, passos curtos e ordenados e os scripts necessários, em .claude/skills para o projeto ou em ~/.claude/skills para você. Skills compartilhadas só valem a pena se você conferir antes. O AgentVera lista as skills do Claude Code e do Codex em um só lugar, analisa as skills da galeria no servidor e de novo no seu computador antes da instalação, e permite que usuários Pro e Team publiquem as suas. Baixe o AgentVera para gerenciar suas skills.