6 padrões que fazem os arquivos de habilidade do Claude Code realmente ativarem

Um desenvolvedor no r/ClaudeAI testou mais de 2.300 arquivos de skill da comunidade e criados por ele mesmo ao longo de três meses para descobrir por que a maioria das skills do Claude Code nunca é ativada. A principal descoberta: muitas skills ficam em ~/.claude/skills/ e nunca são acionadas porque os usuários as colocam lá sem seguir os padrões de ativação que o Claude realmente usa. Aqui estão os seis padrões que determinam se uma skill carrega.

Padrão 1: Linguagem de Acionamento Específica na Descrição

O Claude lê o campo description: do YAML para decidir quando uma skill é relevante. Uma descrição genérica como "Ajuda com coisas de banco de dados" nunca é acionada. Uma específica como "Use ao configurar pool de conexões de banco de dados, escolher tamanhos de pool ou depurar esgotamento de conexões" é acionada de forma confiável. A descrição é a primitiva de descoberta da skill, não um texto decorativo.

Padrão 2: Uma Capacidade por Arquivo, com Escopo Restrito

Uma skill que cobre "todas as coisas de SQL" perde para três skills separadas que cobrem escrever migrações, corrigir injeção e explicar planos de consulta. A correspondência do Claude usa similaridade de cosseno entre o prompt do usuário e a descrição de cada skill. Descrições diluídas correspondem fracamente; as específicas vencem.

Padrão 3: Convenções de Frontmatter Importam

Os campos que o Claude realmente usa: name, description, category, difficulty. Opcionais, mas úteis: tags. Chaves personalizadas são analisadas, mas não afetam a ativação. Adicionar metadados aleatórios não atrasa nada, mas também não ajuda.

Padrão 4: Listas de Quando Não Usar

Listas explícitas de "não use esta skill quando..." tornam a ativação mais precisa, não menos. Elas fornecem ao Claude exemplos negativos que delimitam a superfície de acionamento. Pular esta seção é o erro mais comum em skills da comunidade.

Padrão 5: Exemplos de Código Que Realmente Compilam

Se uma skill tem um bloco de código cercado com sintaxe quebrada, o Claude se afasta da skill na ativação porque o exemplo contradiz a descrição. Execute cada bloco de código em um verificador de sintaxe antes de salvar.

Padrão 6: Etapas de Verificação no Corpo

Skills que incluem seções "após executar isso, verifique por..." obtêm maior confiabilidade de ativação em tarefas no meio da execução. A âncora de verificação ajuda o Claude a decidir "sim, esta é a skill que corresponde ao que eles estão tentando fazer".

Exemplos de Skills Que Atendem aos 6 Padrões

• smart-commit — padrão 1 + 6
• connection-pool-setup — padrão 2
• sql-injection-fix — padrão 4
• redis-lua — padrão 5
• error-handling-audit — padrão 6
• api-documentation — padrão 1
• angular-rxjs — padrão 2
• trpc-router — padrão 5
• dockerfile-generator — padrão 4
• infrastructure-as-code — padrão 3
• custom-slash-commands — padrão 1
• placebo-detector — padrão 4

Essas skills estão disponíveis em clskillshub.com/browse para referência, ou você pode criar as suas próprias usando os seis padrões.