Duas skills do Claude Code em conflito: qual delas vence e como resolver?

Você baixa uma skill pronta, coloca do lado da sua, e as duas começam a mandar coisas opostas sobre o mesmo assunto

Aí bate a dúvida: qual delas o Claude Code vai obedecer?

Existem dois tipos MUITO diferentes de conflito aqui, e confundir um com o outro é exatamente o que faz a sua correção não pegar

O primeiro é colisão de nome: duas skills se chamam igual e existe uma regra de precedência decidindo quem responde ao comando

O segundo é colisão de escopo: os nomes são diferentes, mas as duas descrições se aplicam à mesma tarefa, e o modelo escolhe a inadequada

Nome se resolve no diretório, escopo se resolve na description

Bora ver sintoma por sintoma? 🙂

Sintoma 1: duas skills com o mesmo nome e só uma responde ao comando

Você digita /deploy esperando a skill do projeto e vem outra coisa

Ou pior: você jura que editou o arquivo certo, salvou, rodou de novo e o comportamento não mudou nadinha

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

A causa: resolução por origem

Quando skills têm o mesmo nome em níveis diferentes, o Claude Code resolve por origem, nesta ordem de precedência: enterprise sobrepõe pessoal, e pessoal sobrepõe projeto

O exemplo da documentação oficial de skills é bem direto: se existe uma skill deploy em ~/.claude/skills/ e outra no .claude/skills/ do projeto, o /deploy roda a pessoal

Ou seja, aquela skill que você criou meses atrás pra usar em todos os projetos está calando a do repositório atual

A tabela abaixo resume quem vence quem:

Como resolver:

1. Localize onde vive cada SKILL.md envolvido: skill pessoal fica em ~/.claude/skills/<nome-da-skill>/SKILL.md e vale em todos os projetos, skill de projeto fica em .claude/skills/<nome-da-skill>/SKILL.md e vale só naquele projeto
2. Decida qual das duas precisa continuar acessível pelo comando atual
3. Renomeie a PASTA da outra, não o campo name do frontmatter

Esse passo 3 é onde quase todo mundo se ferra: em skill pessoal ou de projeto, o campo name define só o rótulo exibido nas listagens, o comando continua vindo do nome do diretório

Mudar name e achar que o comando mudou junto é o erro comum aqui

~/.claude/skills/deploy/SKILL.md          ->  /deploy  (pessoal, vence)
.claude/skills/deploy/SKILL.md            ->  sombreada
.claude/skills/deploy-projeto/SKILL.md    ->  /deploy-projeto  (resolvido)

(Em skill de plugin a história muda: lá o name define o último segmento do comando, e o prefixo do plugin permanece)

Como prevenir:

Convenção de nome por origem, decidida ANTES de instalar skill de terceiro

Se toda skill sua de repositório nasce com um sufixo do projeto, a skill baixada nunca tem com quem brigar

Sintoma 2: o conflito não é entre skills, é com um comando ou com uma skill embutida

Dois cenários bem parecidos e igualmente confusos

O primeiro: seu /deploy de sempre some depois que você criou uma skill nova

O segundo: você fez a sua versão de /code-review, digita /review por costume, e roda a embutida

A causa: precedência de skill e aliases que não te pertencem

Se uma skill e um comando dividem o mesmo nome, a skill tem precedência

Com .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md no mesmo projeto, o /deploy roda a skill

E tem a segunda camada: uma skill de qualquer nível sobrepõe a bundled skill de mesmo nome, mas NÃO os aliases dela

Uma skill code-review no .claude/skills/ do projeto substitui a /code-review embutida, e digitar o alias embutido /review nunca roda a sua

Pra fechar o quadro: alguns comandos embutidos são entregues pela própria ferramenta Skill, então também podem ser sombreados

Estão nessa lista o /init, o /review e o /security-review

Como resolver:

1. Confira se o nome que você escolheu é de um embutido
2. Escolha um nome que não colida, algo como code-review-hdc no lugar de code-review
3. Nunca conte com o alias: chame a sua skill pelo nome completo dela

O erro comum do passo 3 é assumir simetria: você sobrepôs a skill, então acha que sobrepôs tudo que chega nela

Não é assim, o alias continua apontando pro lado embutido

Como prevenir:

Tratar nome de embutido como palavra reservada

Se o comando já existe no Claude Code, ele não é seu, ponto

Sintoma 3: nomes diferentes, mas o Claude sempre aciona a skill errada

Esse aqui é o conflito chato de verdade

As duas skills têm nomes distintos, nenhuma sombreia a outra, e mesmo assim o modelo escolhe justamente a que tem a regra oposta à que você queria

A causa: a description é o único critério de escolha

Na inicialização, só o name e a description de cada skill instalada entram no system prompt

Esse é o primeiro nível da divulgação progressiva: o corpo do SKILL.md só é carregado quando a skill é acionada

Traduzindo: aquele texto lindo de instrução que você escreveu dentro do arquivo não participa da decisão

A description é o que o modelo usa pra decidir qual skill se aplica

Se as duas descrições são amplas, você criou um ponto de decisão ambíguo

E aqui vale o princípio de design da própria Anthropic: um dos modos de falha mais comuns é um conjunto de ferramentas inchado, que cobre funcionalidade demais ou gera pontos de decisão ambíguos sobre qual usar

Se um engenheiro humano não consegue dizer com certeza qual deve ser usada, não dá pra esperar que o agente faça melhor

Leia sua description em voz alta e responda honestamente: você saberia escolher só com aquilo?

Como resolver:

1. Abra o SKILL.md das duas skills envolvidas
2. Reescreva cada description dizendo o que a skill faz E quando usar, em terceira pessoa
3. Troque o genérico pelo específico

A recomendação oficial é description específica em vez de ampla, com escopo explícito

Os exemplos do guia são ótimos pra calibrar: Processes PDF legal documents for contract review no lugar de Processes documents

E PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries

O erro comum do passo 2 é misturar ponto de vista, escrevendo "eu faço" ou "você deve" no meio

Ponto de vista inconsistente na description causa problema de descoberta, justamente porque ela é injetada no system prompt

Como prevenir:

Toda vez que entrar uma skill nova no MESMO domínio, revise a description das que já existem ali

Skill nova não chega sozinha, ela chega dentro de um vizinhança

Sintoma 4: as duas skills se aplicam de verdade e o escopo precisa de fronteira

Situação diferente da anterior: aqui as duas descrições estão certas

Cada uma descreve bem o que faz, e ainda assim elas competem, porque o território realmente se toca

A causa: sobreposição legítima

Não tem descrição errada pra corrigir

Tem fronteira faltando

Isso não é exclusivo de skill, é a mesma confusão de quando duas ferramentas do mesmo fornecedor cobrem assuntos vizinhos e ninguém sabe qual abrir, tipo a relação entre Gemini e NotebookLM

Enquanto ninguém escreve a fronteira, ela não existe

Como resolver: gatilho negativo

A recomendação oficial pra skills que se sobrepõem é usar gatilho negativo na description, apontando qual é a skill correta

O exemplo do guia:

---
name: data-analysis
description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead)
---

Se liga no detalhe que faz a diferença: a description não só recusa, ela ENDEREÇA

Dizer "não use pra X" sem dizer quem usa deixa o modelo sem destino

E aplique nos dois lados: se a A aponta pra B, a B tem que apontar pra A no caso inverso

Gatilho negativo só de um lado resolve metade do conflito

Como prevenir:

Cada skill nova declara explicitamente o que NÃO é dela

É uma linha a mais na description e economiza uma tarde de investigação depois

Sintoma 5: a skill de outro projeto aparece onde não deveria

Você achava que aquela skill era coisa de um repositório só

Aí ela pipoca em outro contexto e atropela a regra local

A causa: alcance de nível e diretórios pais

Skill pessoal vale em todos os projetos, sem exceção

E skill de projeto não vem de um lugar só: elas carregam do .claude/skills/ do diretório onde o Claude Code foi iniciado E de todo diretório pai até a raiz do repositório

É isso que amplia o campo de colisão

Em monorepo isso pesa MUITO: você abre o Claude Code dentro de um pacote e leva junto tudo que está nos níveis acima

Como resolver:

1. Liste de onde a skill indesejada está vindo: pasta pessoal, pasta do pacote atual ou algum diretório pai
2. Decida qual deve ser o alcance real dela
3. Mova o SKILL.md pro nível que corresponde a esse alcance

O erro comum do passo 1 é olhar só a pasta do projeto atual e não subir a árvore até a raiz do repositório

Como prevenir:

Decida o nível pelo ALCANCE, nunca pela conveniência de onde o arquivo caiu na hora que você criou

É o mesmo cuidado de quem precisa compartilhar memória entre agentes sem espalhar estado onde não deveria

Sintoma 6: você já ajustou tudo e ainda quer desligar uma das duas

Às vezes o ajuste fino não basta

Você quer silenciar a skill perdedora sem apagar o arquivo, porque ela ainda serve pra outra coisa

A causa: por padrão o modelo pode acionar qualquer skill instalada

Enquanto ela estiver instalada e visível, ela é candidata

Como resolver: as três formas documentadas de controle

1. Desabilitar todas: negue a ferramenta Skill em /permissions
2. Permitir ou negar skills específicas com regras de permissão: Skill(nome) faz correspondência exata e Skill(nome *) cobre o prefixo com qualquer argumento
3. Esconder uma skill individual do modelo com disable-model-invocation: true no frontmatter dela

---
name: deploy-manual
description: Deploy manual do ambiente de produção. Use apenas quando solicitado explicitamente
disable-model-invocation: true
---

O erro comum do passo 1 é usar a bomba atômica quando o problema era uma skill só: negar a ferramenta derruba TODAS

E tem mais um nível de controle, dentro do frontmatter, pro que a skill pode fazer enquanto está ativa: allowed-tools concede ferramentas sem aprovação por uso quando a skill é acionada, e disallowed-tools remove ferramentas do pool disponível do Claude enquanto ela está ativa

Como prevenir:

Aplique sempre o controle mais restrito que resolve o caso

Se dá pra resolver no frontmatter de uma skill, não mexa na permissão global

Sintoma 7: a precedência não está sendo aplicada e as duas skills aparecem

Esse é o caso que quebra a teoria bonitinha

Você criou a skill de projeto com o mesmo nome de uma global esperando sobrepor, e as duas aparecem no seletor

A causa: comportamento relatado publicamente

Existe uma issue pública sobre isso: a issue #25209 do repositório anthropics/claude-code, aberta em 12/02/2026, relata skill de projeto com mesmo nome de skill global aparecendo nas duas no seletor de skills, em vez de o comportamento de sobreposição ser aplicado

Como resolver:

Não dependa da sobreposição como mecanismo de desligamento

Sobrepor é uma regra de resolução de comando, não um botão de desligar

1. Dê nomes distintos às duas skills
2. Se quiser mesmo silenciar uma, desabilite de forma explícita (o Sintoma 6 tem as três formas)

Como prevenir:

Prefira sempre a separação por nome à disputa por precedência

Duas skills com nomes diferentes nunca dependem de quem ganha de quem

Como juntar skills de origens diferentes sem elas se atropelarem

Agora a parte prática: três arranjos que funcionam quando o material vem de lugares diferentes

Arranjo 1: a skill de terceiro empacotada como plugin

Skills de plugin usam namespace, e por isso não colidem com os outros níveis

O formato é plugin-name:skill-name

Uma skill em my-plugin/skills/deploy/SKILL.md vira /my-plugin:deploy e carrega junto com uma skill deploy do projeto, sem uma matar a outra

É o arranjo mais limpo pra material de origem externa: a origem fica no próprio comando

Arranjo 2: a genérica no pessoal, a especializada no projeto

A skill ampla, que vale em qualquer repositório, mora em ~/.claude/skills/

A especializada mora no .claude/skills/ do projeto, com nome PRÓPRIO (nada de repetir o nome da genérica) e com gatilho negativo na description dos dois lados

Assim você nem entra na briga de precedência, o modelo escolhe pelo escopo escrito

Arranjo 3: a skill que só roda quando você pedir

Tem skill que não deveria ser acionada sozinha nunca

Essa recebe disable-model-invocation: true e sai do radar do modelo, continuando disponível pra quando você chamar

Testando os ajustes sem reiniciar nada

O melhor da mecânica: editar skill não exige reiniciar a sessão

Ao adicionar, editar ou remover uma skill em ~/.claude/skills/, no .claude/skills/ do projeto ou em um .claude/skills/ dentro de diretório passado por --add-dir, o Claude Code detecta a mudança na sessão atual, sem reinício

Dá pra ajustar a description, testar, ajustar de novo, tudo na mesma conversa

Só não quebre a skill no meio do ajuste: todo SKILL.md precisa do frontmatter YAML entre os marcadores ---, com name e description obrigatórios, mais o conteúdo markdown com as instruções

E os limites de validação:

• name: máximo 64 caracteres, só letras minúsculas, números e hífens, sem tags XML e sem palavras reservadas
• description: máximo 1024 caracteres, não vazia, sem tags XML

Aquele gatilho negativo caprichado cabe folgado em 1024 caracteres, então não tem desculpa pra description preguiçosa 😀

Conclusão

Conflito de nome e conflito de escopo parecem o mesmo problema, mas não são

Nome se resolve por precedência: enterprise sobre pessoal, pessoal sobre projeto, skill sobre comando, e o comando vindo do nome do diretório

Escopo se resolve na description, porque ela é a única coisa da skill que o modelo vê antes de decidir

O próximo passo é bem concreto: abra o SKILL.md das duas skills envolvidas, confira o nome do DIRETÓRIO de cada uma e leia as duas descriptions lado a lado

Se as duas descrevem a mesma tarefa, aplique o gatilho negativo nos dois lados, apontando a skill certa

Só depois disso vá pras permissões, que são o último recurso e não o primeiro

até o próximo post!