Como instalar uma skill no Claude Code: passo a passo

Skill é você ensinar o Claude Code a repetir um jeito de trabalhar, sem ter que explicar tudo de novo a cada conversa

E o mais legal: instalar uma skill é quase copiar um arquivo pro lugar certo

Não tem mágica, não tem prompt secreto, não tem PC da Nasa

É um SKILL.md na pasta que o Claude Code lê, e pronto, ele passa a enxergar aquilo

Bora montar isso passo a passo, do jeito pessoal (que vale em tudo) até o plugin (que dá pra compartilhar com o time) 😀

O que você precisa antes de instalar a skill

Antes de sair criando pasta, se liga no básico que precisa estar de pé

• Claude Code instalado e funcionando na sua máquina
• Acesso ao diretório onde a skill vai morar: o ~/.claude/ (skill pessoal) ou a raiz do seu projeto (skill de time)
• O arquivo SKILL.md com o frontmatter YAML certinho

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

Esse SKILL.md é o coração de tudo

Ele tem duas partes: um bloco de YAML no topo (entre os marcadores ---) e, logo abaixo, as instruções escritas em Markdown

No YAML, dois campos são obrigatórios: name (o nome da skill) e description (quando ela deve ser ativada)

Se você quer entender a fundo como esse arquivo é montado por dentro, dá uma olhada em como criar e usar skills, que aí o foco é a anatomia do SKILL.md

Aqui a gente foca no instalar

Passo a passo: instalando uma skill pessoal

A skill pessoal é a que fica disponível em TODOS os seus projetos

Ela vive no seu diretório pessoal de skills do Claude Code

1. Crie a pasta da skill dentro de ~/.claude/skills/, com o nome dela:

mkdir -p ~/.claude/skills/minha-skill

2. Crie o arquivo SKILL.md dentro dessa pasta. O caminho final fica assim: ~/.claude/skills/minha-skill/SKILL.md

3. Escreva o frontmatter YAML no topo do arquivo, entre os marcadores ---, com os campos obrigatórios, e logo abaixo as instruções em Markdown:

---
name: minha-skill
description: Descreva aqui QUANDO o Claude deve usar esta skill, com as palavras que você diria naturalmente
---

# Instruções da skill

Aqui vão os passos e regras que o Claude deve seguir quando ativar esta skill

O erro comum deste passo: esquecer os marcadores --- em volta do YAML, ou deixar de fora o name ou o description

Sem esses dois campos a skill não sobe

Tome cuidado com a indentação do YAML também, que ele é chato com espaço 😛

Instalando uma skill de projeto (compartilhada com o time)

Às vezes você não quer a skill só pra ti, quer que todo mundo que trabalha no repositório tenha ela

Aí o caminho muda: em vez do diretório pessoal, ela vai pra dentro do próprio projeto

1. Crie a pasta .claude/skills/ na raiz do repositório (não confunda com o ~/.claude/ da sua home)

2. Coloque o SKILL.md ali dentro, na mesma estrutura de antes

3. Versione junto com o código (commit e push), que assim quem clonar o repo já recebe a skill

mkdir -p .claude/skills/minha-skill
# cria o SKILL.md dentro e commita junto com o projeto

O erro comum deste passo: confundir a pasta do projeto (.claude/skills/ na raiz do repo) com a pessoal (~/.claude/skills/)

São lugares diferentes

A pessoal vale em tudo que é seu, a de projeto vale só naquele repositório e viaja junto com ele pro time

Instalando uma skill via plugin e marketplace

Skills também podem vir empacotadas dentro de um plugin

Esse é o caminho quando alguém distribui a skill num marketplace, e é o que eu sigo quando a recomendação é instalar via plugin

1. Adicione o marketplace apontando pro repositório ou caminho dele:

/plugin marketplace add anthropics/claude-plugins-community

2. Instale o plugin a partir do marketplace que você acabou de adicionar:

/plugin install nome-do-plugin@nome-do-marketplace

3. Valide a sintaxe do marketplace/plugin, se quiser conferir antes de confiar:

/plugin validate .

Ou, direto no terminal, claude plugin validate .

4. Reinicie a sessão pro plugin passar a valer: feche e abra o Claude Code de novo

Esse último passo é fácil de esquecer, mas é ele que faz a skill do plugin realmente entrar em cena

Um detalhe massa: se o plugin traz só UMA skill, ele pode botar o SKILL.md direto na raiz, sem precisar criar uma pasta skills/

O Claude Code carrega usando o campo name do frontmatter mesmo assim

O erro comum deste passo: tentar instalar o plugin sem ter adicionado o marketplace antes

A ordem importa: primeiro o marketplace add, depois o install

Como confirmar que o Claude Code reconheceu a skill

Instalou, e agora, como saber se pegou?

Primeiro, uma boa notícia pra quem editou em ~/.claude/skills/: adicionar, editar ou remover skill nesse diretório já vale na própria sessão, sem reiniciar o Claude Code

Ou seja, mexeu, valeu na hora (isso é pra skill pessoal, o plugin é que pede aquele reinício)

Segundo, entenda COMO a ativação acontece

O Claude não liga a skill por um botão, ele combina o pedido que você faz com o description da skill, por similaridade semântica

É aqui que mora o pulo do gato: o description tem que estar escrito com as palavras que VOCÊ diria naturalmente pra pedir aquilo

Se a description fala a mesma língua do seu prompt, o Claude conecta e ativa

Se está vaga ou fora de contexto, ele não liga, mesmo com o arquivo no lugar certo

Então a melhor confirmação é prática: peça algo que deveria acionar a skill e veja se ela entra em ação

Skill não aparece? Como resolver

Caso a skill de plugin simplesmente não apareça, não entra em pânico

O sintoma clássico é: você instalou o plugin, mas as skills dele não são reconhecidas

A causa costuma ser cache de plugin velho

A solução é limpar o cache e reinstalar:

rm -rf ~/.claude/plugins/cache

Depois reinicie o Claude Code e reinstale o plugin

Pra PREVENIR esse tipo de dor de cabeça:

• Escreva uma description clara, com as palavras que o usuário usaria de verdade (isso resolve o "instalei mas nunca ativa")
• Valide a sintaxe antes com /plugin validate .

Muita coisa que parece "a skill não funciona" é, na real, description ruim ou cache sujo

O que aprendi usando skills na prática

No vídeo abaixo eu mostro tudo isso rodando de verdade, então deixa eu te contar o que rolou

Instalei a skill pelo Claude Code em duas etapas: primeiro adicionei o marketplace de plugins, depois instalei o plugin em si

Na hora de instalar, dá pra escolher entre instalar pro usuário, pra quem trabalha no repositório ou só pro projeto atual

Escolhi só pro projeto, pra deixar mais limpo e testar antes de decidir usar global

Antes de rodar o primeiro prompt, tem um passo que muita gente esquece: reiniciar a sessão (fechar e abrir de novo) pro plugin passar a valer

Aí fui testar num projeto meu de gestão de produtos, um CRUD simples

Pedi pra adicionar um botão de exportar CSV que exportasse só os produtos visíveis, os filtrados na tabela

Quando testei, a interface mostrou as skills sendo ativadas/carregadas, e isso é a prova viva de que o plugin está funcionando

Uma coisa que reparei: nessa tarefa simples, a skill não fez perguntas e partiu direto pra execução

E faz sentido, a etapa de perguntas serve só pra IA não assumir coisa errada

Se o prompt já resolve, ela segue direto

No fim, a IA entregou um relatório do que mudou e ainda rodou um teste conferindo se as colunas exportadas batiam com as colunas visíveis da tabela

Cliquei no botão gerado e o CSV apareceu com exatamente os produtos que eu queria 😀

Pra provar o comportamento num caso maior, dei um prompt vago de propósito: "adicione um sistema de autenticação"

E aí a skill mudou de postura, passou a fazer perguntas antes de implementar, alinhando as escolhas em vez de sair codando no chute

Esse é o contraste que a skill promete resolver

Sem ela, a IA faz suposição silenciosa, over-engineering, mexe em arquivo além do pedido e entrega sem testar

Com ela, o código sai mínimo, cirúrgico, com critério de sucesso definido antes e um diff bem mais limpo

Pra mim resolveu de uma vez os principais problemas de código gerado por IA no modo vibe coding

Se você quer ir além dessa, vale espiar quais skills valem a pena instalar e montar seu kit

Conclusão

Instalar skill no Claude Code é menos complicado do que parece

Comece com uma skill pessoal simples em ~/.claude/skills/<nome>/SKILL.md, com name e description bem escritos

Valide na própria sessão (que já vale sem restart) e veja se ela ativa quando você pede algo relacionado

Quando fizer sentido compartilhar, evolua pra skill de projeto em .claude/skills/ ou empacote num plugin pra distribuir

O segredo mesmo está no description: escreve do jeito que você fala, e o Claude vai saber a hora de usar

Bora testar? 🙂