Skill do Claude Code não funciona no seu projeto? O que checar antes de copiar a do outro

Tem skill que voa no repositório do outro e vira estátua no teu projeto

E aí bate aquela sensação de que a ferramenta é hype, quando na real o que falta é contexto

Skill no Claude Code é uma pasta com um arquivo SKILL.md obrigatório, mais arquivos de apoio opcionais (templates, exemplos, scripts, documentação de referência) que entram sob demanda

Só que o autor não escreveu aquilo no vácuo: ele escreveu em cima da stack dele, das convenções dele, da estrutura de pastas dele e do nível onde ele instalou a coisa

Copiar a pasta copia o texto, não copia o contexto

Bora destrinchar sintoma por sintoma? 😀

A skill simplesmente nunca dispara:

Sintoma: você pede a tarefa, o Claude responde numa boa, e a skill fica lá parada como se não existisse

Causa: o acionamento é decidido pela comparação do teu pedido com a description. name e description são os metadados críticos do frontmatter, e a description do autor foi escrita no vocabulário do projeto DELE

Se ele chama de "deck" o que tu chama de "apresentação", o casamento não acontece

Agrava: o Claude Code carrega no contexto uma listagem com os nomes e as descriptions das skills

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A listagem sempre traz todos os nomes, mas as descriptions podem ser encurtadas pra caber no orçamento de caracteres, e o corte começa pelas skills menos invocadas (as mais usadas mantêm o texto completo)

Ou seja: skill nova e pouco usada é justamente a primeira a perder texto, e junto pode ir embora a palavra-chave que faria ela casar com o teu pedido

Solução: reescrever a description dizendo o que a skill faz E quando usar, com os termos do teu domínio, mantendo a informação decisiva logo no começo

---
name: revisar-migration
description: Revisa migrations de banco antes do deploy. Use quando o pedido envolver migration, alteração de schema, índice ou coluna nova.
---

Como prevenir: sempre reler a description antes de usar skill herdada, nunca aceitar a do autor como está

Você editou a skill, mas o Claude continua rodando a versão antiga:

Sintoma: tu ajusta o arquivo, roda de novo, e o comportamento é exatamente o mesmo de antes

Causa A: existe outra skill com o MESMO nome em outro nível, e a precedência não é a que a maioria imagina

Então aquela cópia velha que tu jogou em ~/.claude/skills/ meses atrás vence a versão do projeto que tu acabou de ajustar

Skill vinda de plugin escapa dessa briga, porque usa namespace nome-do-plugin:nome-da-skill: um meu-plugin/skills/deploy/SKILL.md vira /meu-plugin:deploy e convive tranquilo com um deploy em .claude/skills/

Causa B: tu tinha um comando com o mesmo nome e presumiu que ele rodaria

Com .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md no mesmo projeto, o /deploy roda a SKILL, porque skill tem precedência sobre comando

Solução: mapear em quais níveis aquele nome existe, e renomear ou remover a duplicata

Como prevenir: ao trazer skill de fora, checa antes se o nome já é usado em ~/.claude/skills/ e em .claude/skills/

Editei o SKILL.md e nada mudou (ou mudei outra coisa e nada mudou):

Sintoma: a dúvida clássica, "preciso reiniciar o Claude Code pra valer?"

Causa: depende do que tu mexeu

Alterações no TEXTO do SKILL.md são detectadas dentro da sessão atual, sem reiniciar nada

Isso vale pra ~/.claude/skills/, pro .claude/skills/ do projeto e pro .claude/skills/ dentro de um diretório passado em --add-dir

Mas se liga nisso: a detecção ao vivo cobre SÓ o texto do SKILL.md

Quando a pasta da skill é também um plugin, mudanças em hooks/, .mcp.json, agents/ e output-styles/ só passam a valer com /reload-plugins

Como prevenir: separa mentalmente o que é texto da skill e o que é componente de plugin, porque a regra de recarga é diferente pra cada um

Os arquivos de apoio da skill não são encontrados no seu projeto:

Sintoma: os templates, exemplos ou scripts que vieram junto quebram assim que saem do repositório original

Causa: o autor referenciou caminhos que só existiam na estrutura de pastas dele

E tem mais: o diretório de trabalho e o lugar onde a skill está instalada mudam quando ela troca de casa

Solução: trocar caminho fixo pelo placeholder ${CLAUDE_SKILL_DIR}, que aponta pro diretório onde está o SKILL.md e resolve certo independentemente do diretório de trabalho e de onde a skill foi instalada, seja no pessoal, no projeto ou dentro de um plugin

cat ${CLAUDE_SKILL_DIR}/templates/checklist.md

Tome cuidado com um detalhe: em skill de plugin, ele aponta pra subpasta da skill dentro do plugin, e não pra raiz do plugin

Como prevenir: varre o SKILL.md atrás de qualquer caminho fixo ANTES do primeiro uso, não depois do primeiro erro

O allowed-tools veio junto e continua pedindo aprovação:

Sintoma: a skill prometia rodar comandos sem aprovação a cada uso, e o Claude continua batendo na tua porta toda vez

Causas possíveis: são três, e vale checar na ordem

Primeira: o allowed-tools só é suportado usando o Claude Code CLI diretamente, ele não vale pra skills usadas via SDK

Segunda: os padrões listados pelo autor citam os comandos do fluxo dele, que podem simplesmente não ser os teus

allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)

Terceira: existe issue aberta no repositório do Claude Code (issue #55382, anthropics/claude-code) relatando que ${CLAUDE_SKILL_DIR} NÃO é substituído dentro dos padrões de allowed-tools no frontmatter

A string literal fica lá no padrão de permissão e nunca casa com nada, enquanto ${CLAUDE_PLUGIN_ROOT} no mesmo campo funciona

Solução: revisar os padrões um a um, com o teu fluxo na cabeça

Como prevenir: trata allowed-tools herdado como rascunho, nunca como configuração pronta

Veio empacotada como plugin e a instalação não entrega a skill:

Sintoma: tu registrou o repositório e a skill não aparece em lugar nenhum

Causa: plugin é o formato de DISTRIBUIÇÃO e skill é o CONTEÚDO

Marketplaces são catálogos, e registrar o catálogo não instala nada por si só

O fluxo é em duas partes:

/plugin marketplace add <owner>/<repo>
/plugin

O primeiro registra o catálogo, o segundo abre o navegador de plugins pra tu instalar de fato

Segunda causa: estrutura do plugin fora do padrão

Os componentes (skills, agents, hooks) ficam na RAIZ do plugin, e não dentro de .claude-plugin/

Só o plugin.json mora em .claude-plugin/

Solução: rodar a validação local antes de sair culpando a skill

claude plugin validate ./seu-plugin

Ele imprime Validation passed (ou Validation passed with warnings) e aceita --strict pra tratar warning como erro

Campo não reconhecido entra como warning, e o warning sugere o nome provável quando o campo está um ou dois caracteres errado, o que salva bastante tempo de olho grudado no arquivo 🙂

Como prevenir: validar primeiro, reclamar depois

É a mesma pegada de quando tu vai atualizar o n8n sem quebrar os fluxos: checagem antes custa cinco minutos, conserto depois custa a tarde

A skill funciona no papel do autor, mas não no ambiente onde você vai rodar:

Sintoma: a mesma skill se comporta de um jeito num lugar e de outro jeito em outro

Causa: premissas de ambiente que ninguém escreveu no README

As skills pré-construídas de documentos (PowerPoint, Excel, Word, PDF) não estão disponíveis no Claude Code

E no ambiente de execução das Skills pela API da Anthropic não há acesso à rede nem instalação de pacotes em tempo de execução, embora exista acesso a sistema de arquivos, comandos bash e execução de código

Solução: se a skill herdada depende de baixar algo ou instalar dependência em runtime, esse passo precisa sair do fluxo ou ser resolvido antes

Como prevenir: lê o SKILL.md procurando o que ele ASSUME que já existe na máquina, esse é o tipo de premissa mais invisível de todas

A skill dispara, mas o resultado sai genérico ou fora das suas convenções:

Sintoma: acionou certinho e entregou errado, aquele resultado morno que tu vai reescrever inteiro

Causa: o grau de liberdade das instruções foi calibrado pro projeto do autor

A recomendação de autoria da Anthropic é justamente calibrar isso: quando existe só um caminho seguro, instruções exatas e guardrails (limites) específicos; quando muitos caminhos levam ao mesmo resultado, direção geral basta

O problema é que o que era guardrail lá vira camisa de força aqui, e o que era direção geral vira vazio

Solução: reescrever as partes que codificam convenção alheia, mantendo o esqueleto que presta

Como prevenir: refinar observando o comportamento REAL do agente em uso, e não por suposição tua no editor, no ciclo observar, refinar, testar

O que aprendi adaptando uma skill de terceiro no meu projeto:

No vídeo eu instalei o Impeccable num projeto que já existia e já estava rodando, em vez de começar do zero, justamente pra testar se dava pra aplicar com a obra em andamento

Antes disso eu criei uma landing page de um SaaS fictício de gestão de tarefas SEM o pacote, pra ter um antes e depois comparável

E olha que engraçado: eu achei aquele design excelente, tinha dito que seguiria com ele assim mesmo

Aí foi a etapa de crítica que apontou vários problemas nesse mesmo projeto que eu já tinha aprovado no olho 😛

Na instalação eu escolhi o escopo de projeto pro Claude Code em vez de um escopo mais amplo, e preferi a opção que copia os arquivos em vez da opção por link, porque já tive problema com a de link em outras vezes

Antes de qualquer melhoria eu tive que passar contexto: a skill abriu uma entrevista com perguntas sobre o escopo do repositório, o público que chega na página e o estilo de copy

A entrevista começou em inglês e passou a responder em português depois que eu respondi em português

Respondi que a copy existente já estava correta, pra ferramenta não mexer nessa parte

O resultado da entrevista virou um arquivo de produto que passa a ser a referência do projeto pras etapas seguintes, e isso é exatamente a prova do que esse post todo defende: a skill precisava do MEU contexto pra render

Outra coisa que fiz de propósito: perguntei ao assistente qual seria a ordem correta de comandos em vez de assumir a sequência, e segui exatamente a ordem que ele devolveu, com o fluxo completo em 4 passos

E reparei que cada skill do pacote ataca um eixo separado (tipografia, cores e contraste, espaçamento, responsividade, interação e motion), então dá pra usar só um pedaço em vez do conjunto inteiro

Essa lógica de escolher a peça em vez de engolir o pacote vale pra outros conjuntos também, tipo os modos de execução do Superpowers

Também não é uma troca de layout por layout, é análise por pontos do projeto existente, e na etapa de crítica o review usou a lista do que não pode acontecer como base pra apontar os problemas

Usei o Claude Code por ser a ferramenta que mais uso no dia a dia

A conclusão que ficou: dá pra adotar com o projeto já rodando, sem recomeçar, e mesmo um design que eu considerava excelente recebeu vários apontamentos

No vídeo acima tu vê o antes e depois, a entrevista de contexto e a etapa de crítica rodando em cima do projeto que já estava de pé

Conclusão: adaptar, não descartar

Quando a skill do Claude Code não funciona no teu projeto, a resposta quase nunca é jogar fora

Skill alheia é ponto de partida, não produto final: ela chega com as premissas do autor coladas nela, e teu trabalho é raspar essas premissas

Pega agora uma skill que tu já copiou e roda a checagem:

1. Lê a description inteira e reescreve com os termos do teu domínio, informação decisiva no começo (erro comum: manter o vocabulário do autor e achar que o Claude vai adivinhar)
2. Procura o mesmo nome em ~/.claude/skills/ e em .claude/skills/, lembrando que o pessoal vence o projeto (erro comum: editar a do projeto e ficar testando a pessoal antiga)
3. Varre o SKILL.md atrás de caminho fixo e troca por ${CLAUDE_SKILL_DIR} (erro comum: só descobrir o caminho quebrado no meio da tarefa)
4. Revisa o allowed-tools padrão por padrão, sem confiar no que veio pronto (erro comum: tratar como configuração final)
5. Se veio como plugin, roda claude plugin validate ./seu-plugin antes de culpar a skill (erro comum: registrar o catálogo e achar que já instalou)

Depois disso, refina observando o agente em uso, não por achismo

E se tu quer estudar skill bem escrita pra calibrar a tua, a Anthropic mantém um repositório público de Agent Skills em anthropics/skills

lê o SKILL.md dos outros com olhar de detetive, é de graça e ensina muito 😀

até o próximo post!