Sua skill do Claude Code dispara quando não devia? Como limitar o escopo dela

Fala aí, beleza? Quase todo conteúdo sobre skills ensina a mesma coisa: como fazer a sua skill disparar

Só que tem MUITA gente hoje com o problema exatamente inverso…

Você pede um ajuste bobo de CSS e a skill de deploy entra em cena, ocupa contexto e desvia a resposta pra um assunto que ninguém pediu

E isso não é implicância sua: a documentação de boas práticas de skills reconhece que skills podem degradar a performance do agente quando disparam incorretamente, conflitam com outras skills ou trazem instruções ruins

A boa notícia é que a correção não mora em nenhum prompt mágico, ela mora no frontmatter do SKILL.md

Bora destrinchar sintoma por sintoma? 🙂

Sintoma 1: a skill entra em tarefas parecidas, mas erradas

Você tem uma skill de análise de dados e pede só pra listar as colunas de um CSV

Ela dispara

O pedido era adjacente ao domínio dela, encostou no assunto, e isso bastou

A causa: a description é o campo de matching

O Claude decide se aciona uma skill comparando a tarefa que você pediu com o campo description do SKILL.md

Description genérica, acionamento genérico, é bem direto assim

A documentação pede que a description carregue duas coisas: o que a skill faz E quando usá-la

E que seja escrita em terceira pessoa

Por quê? Porque a description é injetada no system prompt, e ponto de vista inconsistente atrapalha a descoberta da skill

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

A solução: identidade positiva clara + linha de exclusão

Primeiro você deixa explícito o que a skill é

Depois deixa explícito o que ela NÃO é

Guias da comunidade sobre autoria de skills chamam isso de negative triggers: frases de exclusão dentro da própria description, no estilo "Do NOT use for basic data exploration", pro agente filtrar os pedidos vizinhos (guia sobre triggers na description)

Antes de sair escrevendo, se liga nos limites do spec: name aceita no máximo 64 caracteres, só letras minúsculas, números e hífens, sem tags XML e sem as palavras reservadas "anthropic" e "claude"

Já a description vai até 1024 caracteres, não pode ser vazia e também não aceita tags XML

---
name: sql-query-review
description: Reviews SQL queries for correctness, indexes and query plans. Use when the user asks to review, optimize or debug a SQL query. Do NOT use for basic data exploration, CSV inspection or schema documentation.
---

Repara que o texto está em terceira pessoa, descreve o "quando" e ainda fecha a porta do caso vizinho

Como prevenir:

Escreva a linha de exclusão no MESMO momento em que escreve a description, nunca depois do incidente

Se você só escreve a exclusão quando a skill já pisou na bola, tu vira bombeiro da própria skill haha

Sintoma 2: a skill certa não aparece e outra qualquer assume

Esse aqui é o primo do sintoma 1 e costuma chegar junto com aquela fase de "instalei um monte de skill de uma vez"

O pedido é claro, existe uma skill perfeita pra ele, e mesmo assim outra assume o turno (ou nenhuma aparece)

A causa: os metadados competem por atenção

Skills funcionam por progressive disclosure: até a skill ser acionada, só o name e a description dela ocupam contexto

O corpo do SKILL.md só entra depois, sob demanda

Só que isso vale pra TODAS as skills instaladas ao mesmo tempo

Com skill demais ativa, esses metadados competem por atenção no system prompt e o Claude pode escolher a errada ou não achar a certa

A orientação oficial é justamente limitar quantas skills ficam carregadas ao mesmo tempo (visão geral de agent skills)

Tem um reforço importante nisso: no Claude Code, as skills reanexadas dividem um orçamento combinado de 25.000 tokens, preenchido a partir da skill invocada mais recentemente (documentação da janela de contexto do Claude Code)

Ou seja: numa sessão com muitas invocações, skill antiga pode ser descartada depois de uma compactação

A solução: cortar o excesso

O primeiro corte é o óbvio, reduzir o número de skills ativas

O segundo é desligar as embutidas, com disableBundledSkills no settings.json

{
  "disableBundledSkills": true
}

Essa configuração desliga todas as skills embutidas do Claude Code, com uma exceção: o /doctor continua digitável a partir da versão 2.1.205, como registra a referência de settings do Claude Code

E antes de criar mais uma skill pra resolver alguma coisa, vale conferir a diferença entre skills, comandos e subagentes, porque parte do que vira skill funcionaria melhor em outro formato

Como prevenir:

Trate skill instalada como custo fixo de contexto, não como enfeite de perfil

Cada uma que fica ali disputa a atenção da seleção, mesmo quando você não usa faz semanas

Sintoma 3: a skill dispara e já executa algo com efeito colateral

Esse é o que dá aquele frio na barriga

A skill não só apareceu, ela AGIU: commitou, subiu, mandou mensagem

A causa: skill visível é skill candidata

Qualquer skill que o modelo enxerga é candidata a acionamento automático

Não existe meio termo: se ela está lá com name e description no system prompt, ela pode ser escolhida

A solução: esconder a skill do modelo

No Claude Code você define disable-model-invocation: true no frontmatter do SKILL.md

Com isso a skill fica escondida do Claude até você invocar manualmente, e o acionamento automático some

---
name: deploy-staging
description: Deploys the current branch to the staging environment and reports the deployment status.
disable-model-invocation: true
---

E olha que interessante: a documentação de skills do Claude Code indica esse campo exatamente pra fluxos com efeito colateral ou de timing controlado, citando exemplos como /commit, /deploy e /send-slack-message

Ou seja, não é gambiarra minha, é o uso previsto

Como prevenir:

Separe suas skills por natureza, não por assunto

Skill que só lê e analisa pode ficar automática

Skill que escreve no mundo (repositório, servidor, Slack) nasce manual, sempre

Sintoma 4: a skill dispara certo, mas mexe em mais coisa do que deveria

Aqui o acionamento até está correto

O problema é o tamanho do estrago possível: você pediu uma auditoria e ela saiu editando arquivo

A causa: sem restrição declarada, não existe restrição

O campo allowed-tools no frontmatter limita quais ferramentas o Claude pode usar enquanto a skill está ativa

Se você omite esse campo, a skill simplesmente não restringe ferramenta nenhuma

A solução: declarar o que pode e o que não pode

---
name: security-audit
description: Audits the repository for insecure patterns and reports findings. Use when the user asks for a read only security review.
allowed-tools: Read, Grep, Glob
---

Esse trio de exemplo é o clássico acesso somente leitura

E quando o caminho mais prático é tirar ferramenta específica em vez de listar tudo que pode, skills e comandos do Claude Code também aceitam disallowed-tools no frontmatter, removendo a ferramenta do modelo enquanto a skill está ativa

E se existirem duas skills com o mesmo nome?

Acontece mais do que parece, principalmente quando você copia uma skill do seu setup pessoal pra dentro de um projeto

A resolução é por origem: enterprise sobrepõe pessoal, e pessoal sobrepõe projeto

Vale lembrar onde cada uma mora: skills pessoais em ~/.claude/skills/ e skills de projeto em .claude/skills/, carregadas a partir do diretório onde o Claude Code foi iniciado e em cada diretório pai até a raiz do repositório

Já me confundi com isso: você edita a versão do projeto, testa, e o comportamento não muda, porque quem está valendo é a pessoal

Como prevenir:

Skill de auditoria e de diagnóstico nasce somente leitura por padrão

Se um dia ela precisar escrever, tu abre a permissão de forma consciente, e não por esquecimento

Como testar se a sua correção pegou: rotina de falso positivo

Agora a parte que quase todo mundo pula: como saber se limitar escopo de skill do Claude Code realmente funcionou?

1. Monte um conjunto de avaliações com 3 a 5 consultas representativas da skill, cobrindo três grupos: casos em que ela DEVE disparar, casos em que ela NÃO deve e casos ambíguos de fronteira

É a orientação da própria doc de boas práticas, e é o passo que transforma achismo em teste

Erro comum deste passo: escrever só as consultas fáceis, aquelas em que a skill obviamente entra

É mais ou menos o mesmo raciocínio de quando você precisa melhorar performance sem ter métrica nenhuma: sem um critério combinado antes, qualquer resultado parece bom

2. Rode o teste de falso positivo: digite um pedido adjacente, que a skill NÃO deveria atender

Se ela disparar, a description está larga demais e a linha de exclusão precisa apertar (essa técnica de teste também vem dos guias da comunidade)

Erro comum deste passo: escolher um pedido distante demais do domínio da skill, tipo pedir receita de bolo pra uma skill de SQL

O teste só vale se o pedido for realmente vizinho

3. Edite a description e salve

Não precisa reiniciar nada: o Claude Code detecta alterações em skills dentro de ~/.claude/skills/, do .claude/skills/ do projeto ou de um .claude/skills/ em diretório passado via --add-dir, durante a própria sessão

Erro comum deste passo: editar um SKILL.md que está fora desses caminhos e ficar esperando o hot reload que nunca vem

4. Confirme o que realmente carregou na sessão

A documentação de debug de configuração do Claude Code indica /context, /doctor, /hooks e /mcp pra isso

E no terminal, claude doctor imprime o diagnóstico de instalação e settings sem nem precisar abrir sessão

claude doctor

Erro comum deste passo: assumir o que está carregado a partir da sua memória do que você instalou, em vez de olhar

5. Se a suspeita for de conflito entre customizações, isole a causa

claude --safe-mode

Esse comando inicia uma sessão com todas as customizações desativadas, incluindo CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes customizados (mesma doc de debug)

Se o comportamento some ali, o problema é seu setup, e você vai religando aos poucos

Erro comum deste passo: rodar em safe mode, ver tudo funcionando e declarar vitória sem descobrir QUAL customização era a culpada

O que acontece na prática quando você instala um pacote inteiro de skills

Se liga nesse contraponto honesto, porque ele conversa direto com o Sintoma 2

No vídeo eu instalo uma skill de design pronta e uso ela pra montar um projeto do zero

Logo na instalação apareceu a primeira decisão: instalar no projeto ou global

E isso muda tudo, porque no projeto a skill só existe ali, e global ela aparece em qualquer outro projeto meu

Minha posição é que nem toda skill compensa instalar globalmente: se ela só vai ser usada em um projeto, global não faz sentido pra mim

Ainda na instalação dava pra selecionar quais editores e assistentes receberiam a skill, e depois eu apaguei as pastas geradas pras outras ferramentas, deixando só a do Claude Code

Optei também por symlink em vez de baixar o arquivo pra máquina, e no vídeo dá pra ver a skill aparecendo como link, não como arquivo copiado

Aí veio a parte engraçada: na primeira tentativa a skill não foi encontrada de cara

Pelo que observei, o assistente procurou primeiro no escopo global, não achou, e só encontrou depois ao procurar no escopo local do projeto

Ou seja, o meu problema foi o OPOSTO do tema deste post, mas com a mesma raiz: a etapa de encontrar e casar a skill com a tarefa

O contorno que eu recomendo é citar a skill explicitamente no prompt em vez de esperar a ativação acontecer sozinha

Depois que ela foi reconhecida e marcada como ativa na sessão, deixei ela conduzir a criação do projeto e aceitei os comandos sugeridos

Pra fechar eu gerei duas versões do mesmo projeto, uma com a skill de design ativa e outra sem, e comparei lado a lado

A versão sem skill tinha a mesma estrutura, mas bem menos polida: ícones genéricos, emojis e cores mal escolhidas, enquanto a versão com skill seguiu paleta e padrões de design

A moral pro assunto de hoje: um pacote grande de skills é ótimo em capacidade, e é exatamente o cenário em que a seleção começa a errar pros dois lados

No vídeo abaixo dá pra ver a parte que o texto não mostra: a instalação real, a skill não sendo encontrada na primeira tentativa e a comparação visual dos dois projetos lado a lado

Qual trava usar em cada situação

Mapa rápido pra você não sair aplicando tudo de uma vez:

E fica o alerta que vem dos guias da comunidade: lista longa de exclusão NÃO substitui identidade positiva clara

Se a sua description precisa de um monte de cláusula de exceção pra funcionar, o problema não é a redação, é o desenho da skill

E se a saída que você pensou foi juntar várias skills estreitas em uma mais ampla, a orientação de boas práticas é consolidar só quando as avaliações da skill consolidada confirmarem performance equivalente às individuais que ela substitui

Sem avaliação, consolidar é troca de um problema por outro

Conclusão

Limitar escopo faz parte da autoria da skill, não é conserto de emergência

Description é campo de matching, então ela é o seu principal instrumento de controle: diz o que a skill faz, diz quando usar, e diz onde ela não entra

O resto é ajuste fino, disable-model-invocation pro que tem efeito colateral, allowed-tools pro que age demais, e menos skill carregada ao mesmo tempo

Próximo passo concreto pra hoje: abre o SKILL.md daquela skill mais barulhenta, reescreve a description em terceira pessoa com uma linha de exclusão, salva (o hot reload pega na hora) e roda o teste de falso positivo com 3 a 5 consultas antes de voltar pro trabalho

Leva uns minutos e devolve o contexto que ela estava comendo à toa 😀

Até o próximo post!