Skills

Uma skill é uma pasta com um arquivo SKILL.md dentro. No arquivo vai um cabeçalho curto dizendo quando usar aquilo, e abaixo as instruções. É só isso.

O que faz a diferença não é o formato, é quando o texto entra em cena. O CLAUDE.md é carregado em toda sessão e cobrado em toda mensagem. O corpo de uma skill só carrega quando ela é usada. Por isso uma skill pode ter centenas de linhas de material de referência sem custar nada até você precisar dela.

Você chama uma skill digitando /nome-da-skill. O Claude também pode carregá-la sozinho quando a descrição bate com o que você pediu — é a descrição, não o nome, que faz esse trabalho.

Skills vivem em três lugares:

Escopo	Caminho	Alcance
Pessoal	~/.claude/skills/<nome>/SKILL.md	todos os seus projetos
Projeto	.claude/skills/<nome>/SKILL.md	só aquele repositório
Plugin	dentro do plugin	onde o plugin estiver ativo

Transforme um processo em skill quando: você colou a mesma lista de instruções pela segunda vez; uma seção do CLAUDE.md deixou de ser um fato e virou um procedimento; ou você acabou de passar horas acertando algo que vai precisar fazer de novo. Esse último caso é o mais rentável — no fim da sessão em que deu certo, o material para escrever a skill está todo ali.

O critério para escolher entre CLAUDE.md e skill é a frequência. Se precisa valer em toda sessão, é CLAUDE.md. Se precisa ser convocado de vez em quando, é skill.

Skill de terceiro e skill própria resolvem coisas diferentes. Instale de terceiro quando o assunto é uma especialidade que não é sua — auditoria de segurança, SEO, acessibilidade — e alguém que entende já escreveu o critério. Escreva a sua quando o processo é da sua casa: seu tom de voz, seu formato de entrega, sua ordem de checagem. Ninguém de fora vai acertar isso.

Sintoma. Você criou ou instalou uma skill, digita / e ela não está na lista. Chamar pelo nome também não funciona.

Causa provável. Depende de onde a skill mora.

• Skill de plugin. Plugin recém-instalado ou recém-ativado nem sempre entra na sessão em andamento. O resumo da instalação diz qual dos dois casos é o seu.
• Diretório de skills que não existia quando a sessão abriu. O Claude Code observa os diretórios de skills e pega alterações sem reiniciar — mas só observa os diretórios que já existiam no início da sessão.
• Skill em subpasta do projeto. Skills em .claude/skills/ abaixo da pasta onde você abriu o Claude só carregam depois que ele lê ou edita algum arquivo daquela subpasta. Até lá elas não aparecem no autocompletar.
• Nome namespaceado. Skill vinda de plugin é chamada como /nome-do-plugin:nome-da-skill. Procurar pelo nome curto pode não encontrar.
• Arquivo no lugar errado. A skill é uma pasta com SKILL.md dentro, não um .md solto.

Verificação.

1. Rode /context e veja se a skill aparece na listagem de skills carregadas.
2. Confirme o arquivo no disco: ls ~/.claude/skills/<nome>/SKILL.md para a pessoal, ou ls .claude/skills/<nome>/SKILL.md para a do projeto.
3. Se for de plugin, abra /plugin e confira na aba de instalados se ele está ativo e sem erro. A aba de erros mostra falhas de carregamento.

Correção.

• Skill de plugin que ainda não ativou: rode /reload-plugins. Se ele avisar que a recarga vai reler a conversa, repita com /reload-plugins --force.
• Diretório de skills criado agora: feche e abra o Claude Code, para ele passar a observar o diretório novo.
• Skill em subpasta: peça a ele para ler um arquivo daquela subpasta, ou abra a sessão a partir dela.
• Skill de plugin encontrada mas não chamada: use o nome completo, com o prefixo do plugin.
• Skills de plugin que somem depois de tudo isso: apague o cache com rm -rf ~/.claude/plugins/cache, reinicie o Claude Code e reinstale o plugin.