A resposta curta
Se chamar uma Skill pelo nome funciona, ela está instalada. Se ela roda sozinha depende da descrição, que o agente lê primeiro e pode encurtar. Teste as duas coisas separadamente, porque elas falham por motivos diferentes.
Como cada agente escolhe uma Skill
Cada agente primeiro lê uma lista de nomes e descrições de Skills e só carrega as instruções completas de uma Skill depois de escolhê-la. Essa lista vem do frontmatter de cada SKILL.md (o arquivo que muita gente procura como skills.md), e ela tem um limite de tamanho:
| Agente | Lê primeiro | Quando falta espaço |
|---|---|---|
| Claude Code | Nome e descrição, além de when_to_use se estiver definido; até 1.536 caracteres cada | A lista recebe cerca de 1% da janela de contexto; as descrições menos usadas saem primeiro |
| Codex | Nome, descrição e caminho do arquivo | A lista recebe cerca de 2% da janela de contexto; as descrições são encurtadas primeiro |
| Cursor | Nome e descrição | Não documentado |
Com muitas Skills instaladas, uma descrição longa ou vaga pode ser cortada ou descartada antes mesmo de o agente considerá-la. Por isso a primeira frase é a que mais importa.
Escreva uma descrição de Skill que seja escolhida
Escreva a descrição do jeito que um colega pediria o trabalho e coloque o uso principal na primeira frase.
O agente compara o seu pedido com essas palavras, então use as que as pessoas realmente digitam, como “landing page”, “página de lançamento” ou “pitch deck”. Diga primeiro o resultado e depois quando usar.
O que cria e quando
- “Build a product launch page with a hero, feature grid, and pricing toggle. Use when asked for a landing or launch page.”
Genérica
- “Helps with websites.”
- Ela compete com todas as outras Skills de web e quase não diz nada depois de encurtada.
Como testar se ela é acionada
Teste nesta ordem. O primeiro passo descarta um problema de instalação, então qualquer falha depois dele aponta para a descrição.
- 1Chame pelo nome. Se falhar, é um problema de instalação; veja Solução de problemas.
- 2Comece uma sessão nova, para que a chamada anterior não esteja no contexto, e peça com palavras comuns, sem o nome.
- 3Pergunte ao agente qual Skill ele usou e confira uma instrução que só essa Skill seguiria.
Quando a Skill errada roda
Normalmente isso significa que duas descrições se sobrepõem ou que a mesma Skill está instalada duas vezes.
- Chame a que você quer pelo nome. Uma chamada pelo nome sempre vence.
- Restrinja as descrições que se sobrepõem por entrada, público ou resultado, para que cada Skill tenha um trabalho claro.
- Mesmo nome em dois lugares: o Claude Code prefere Enterprise, depois a pessoal e depois a do projeto. O Codex pode listar as duas. Mantenha uma cópia só.
Perguntas frequentes
Por que minha Claude Skill não é acionada?
Primeiro chame pelo nome. Se falhar, a Skill não está instalada onde o agente procura; se só os pedidos comuns falham, reescreva a descrição com as palavras que você realmente digita.
Como o Claude decide qual Skill usar?
Ele lê o nome e a descrição de cada Skill e carrega a que melhor combina com o seu pedido. Digitar /skill-name pula essa comparação e roda a Skill que você nomeou.
O que a descrição de uma Skill deve dizer?
O que a Skill cria e quando usá-la, com o uso principal na primeira frase. Use as palavras que as pessoas realmente digitam, como “landing page” ou “pitch deck”, porque a descrição pode ser encurtada.
O arquivo se chama SKILL.md ou skills.md?
É SKILL.md, um em cada pasta de Skill. O frontmatter dele contém o nome e a descrição que os agentes leem quando escolhem uma Skill.
Fontes
Este guia ajudou?