A resposta curta
- 1Chame pelo nome:
/skill-nameou$skill-name. Se rodar, a instalação está certa. - 2Não encontrou? Verifique a pasta. O
SKILL.mdprecisa ficar diretamente em<skills folder>/<name>/. - 3Ainda travado? Encontre abaixo o que você está vendo.
Encontre o problema em 30 segundos
Encontre à esquerda o que você está vendo e vá direto para a solução à direita.
Chamar pelo nome não funciona
Ela não está onde o seu agente procura. Veja Skill não aparece.
Roda pelo nome, mas não a partir de um pedido normal
Verifique a descrição ou as configurações. Veja Skill não é acionada.
Outra Skill roda
Duas descrições se sobrepõem. Veja A Skill errada roda.
Começa e depois para
Falta algo de que ela depende. Veja Falha no meio.
Roda a versão antiga
Há uma segunda cópia, ou a sessão está desatualizada. Veja Versão antiga.
Skill não aparece no Claude Code, Codex ou Cursor
Se uma Skill não está em /skills nem em Customize → Skills, o agente não a carregou. Na maioria das vezes a pasta está no lugar errado ou um nível abaixo do esperado.
| Causa provável | Solução |
|---|---|
Você instalou para o Claude Code com a Skillry CLI, mas esqueceu o --agent claude-code | Reinstale com a flag. Sem ela, a CLI usa ~/.agents/skills/ |
| O ZIP criou um nível de pasta a mais | Suba a pasta interna um nível. O Claude Code exige exatamente skills/<name>/SKILL.md |
Um erro no frontmatter entre as linhas --- | Corrija. O Codex e o Cursor exigem name e description, e no Cursor o name precisa ser igual ao nome da pasta |
| O agente ainda não a detectou | Claude Code: /reload-skills. Codex: reinicie dentro do repositório. Cursor: novo chat ou recarregue a janela |
Codex no app desktop do ChatGPT: $ não encontra nada | Um bug relatado (openai/codex#28505). Verifique /skills, reinicie ou tente uma cópia em ~/.codex/skills/ (ainda não testamos isso) |
Para ver todas as pastas que cada agente lê, consulte Locais das Skills.
A Skill aparece, mas não é acionada sozinha
O agente decide se usa uma Skill lendo a descrição dela. Quando uma Skill só roda se você a chama pelo nome, ou a descrição não combina com o jeito como você pede, ou alguma configuração a está segurando.
- Teste o prompt de exemplo da página da Skill. Ele foi escrito para combinar com a descrição.
- Verifique
paths. Ele limita o uso automático aos arquivos correspondentes. - Muitas Skills instaladas? O agente encurta ou descarta descrições para caber todas, então coloque o uso principal primeiro. Veja Acionamento.
Outra Skill roda no lugar
Quando duas Skills instaladas descrevem o mesmo trabalho, elas competem, e o agente escolhe a que parece mais próxima do seu pedido. Normalmente isso significa duas Skills para tarefas parecidas ou a mesma Skill instalada duas vezes.
| O que está acontecendo | Solução |
|---|---|
| Uma Skill parecida sempre vence | Chame a que você quer pelo nome: /skill-name no Claude Code e no Cursor, $skill-name no Codex. Chamar pelo nome sempre roda aquela Skill. |
| Suas próprias Skills se sobrepõem | Restrinja cada descrição por entrada, público ou resultado, para que cada uma cubra um único trabalho. Veja Acionamento. |
| O mesmo nome está instalado duas vezes | O Claude Code usa primeiro Enterprise, depois a pessoal e depois a do projeto. O Codex pode listar as duas. Mantenha uma cópia só. |
| Uma Skill fica começando sem você pedir | Deixe a descrição dela mais específica sobre quando usá-la, para que pare de combinar com pedidos não relacionados. Depois chame pelo nome a Skill que você quer. Veja Acionamento. |
Começa e depois falha no meio
Quase sempre é uma dependência faltando: a versão errada do Node.js, ou falta de Python, FFmpeg ou chave da FAL. A página da Skill lista o que ela precisa, então confira isso primeiro:
Continua rodando a versão antiga
Você atualizou a Skill, mas o agente ainda se comporta do jeito antigo. O motivo é um destes:
- Só o
SKILL.mdfoi substituído. Reinstale com--forceou substitua a pasta inteira. - Outra cópia com o mesmo nome está instalada em outro lugar. Remova-a.
- No Claude Code, uma Skill que já rodou fica como estava pelo resto daquela conversa. Comece uma nova conversa para pegar suas edições.
Para backups e para voltar a uma versão anterior, veja Gerenciar e atualizar.
Funciona na sua máquina, mas não na nuvem
Sessões na nuvem rodam em outra máquina, então uma Skill que só existe no seu computador não vai junto, a menos que você configure:
| Agente | Solução |
|---|---|
| Claude Code | Sessões na nuvem: faça commit em .claude/skills/ ou ative-a em claude.ai. Cowork: ative-a em claude.ai. |
| Codex | Skills avulsas não chegam ao ChatGPT na web nem no celular. Distribua-a em um plugin. |
| Cursor | Mantenha-a em ~/.cursor/skills/ e ative Settings → Agents → Context and Tools → Sync Skills for Cloud Agents. |
Mensagens de erro da Skillry CLI
Encontre a mensagem que a Skillry CLI exibiu e faça o que a coluna da direita indica.
| Você vê | Faça isto |
|---|---|
| “Not logged in.” ou “Session expired.” | Rode npx --yes skillry-cli@latest login |
| “…already exists. Re-run with --force to replace it safely.” | Adicione --force. Sua cópia antiga ganha um backup |
| “This Skill requires a paid plan.” | Confira o preço da Skill ou o seu plano |
| “--agent and --target cannot be used together.” | Escolha uma das duas opções |
| “Secure session storage is currently supported on macOS and Windows only.” | No Linux, use o prompt de instalação ou Download ZIP |
Perguntas frequentes
Por que minha Skill do Claude Code não carrega?
Geralmente ela está em ~/.agents/skills/ em vez de ~/.claude/skills/, ou há um nível de pasta a mais. Corrija o caminho e, se a pasta for nova, rode /reload-skills.
Por que minha Skill pede uma API key?
Ela usa um serviço pago, listado em custos externos na página da Skill. Configure a chave do jeito que esse serviço orienta e nunca cole a chave no chat.
Como sei se a instalação funcionou?
Ela aparece em /skills (Customize → Skills no Cursor) e roda quando você a chama pelo nome.
Fontes
Este guia ajudou?