Skills for Claude Code: o que são e como ativar (guia em português)

Tu pesquisou por skills for Claude Code em inglês, caiu num monte de doc técnica e ficou sem saber onde encostar a mão primeiro

Bora começar pelo começo

Uma skill (o nome oficial é Agent Skill) é uma capacidade modular e reutilizável

Na prática ela é uma pasta contendo um arquivo SKILL.md com instruções em markdown, mais scripts e recursos opcionais quando tu quiser

O melhor: no Claude Code as skills são baseadas em arquivos e não exigem upload por nenhuma API

Se você conhece a ideia de largar um arquivo de configuração no projeto e ele já valer, é bem por aí

Neste guia tu monta a primeira skill do zero, entende onde ela vive e como ativar, beleza?

O que você precisa antes de criar sua primeira skill

Antes de sair criando pasta, o passo que mais gera confusão é ENTENDER onde a skill vive

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

Existem dois lugares:

• Skills pessoais ficam em ~/.claude/skills/ e valem pra você, em qualquer projeto
• Skills de projeto ficam em .claude/skills/ dentro do repositório e valem pra aquele projeto

A diferença de escopo importa

As skills de projeto carregam a partir de .claude/skills/ no diretório atual e em todos os diretórios pais até a raiz do repositório

Ou seja: se você está numa subpasta funda, o Claude Code ainda enxerga a skill que está lá em cima, na raiz do repo

Pra que serve essa separação? Skill pessoal é o teu ferramental que anda contigo

Skill de projeto é aquilo que faz sentido pro time inteiro que clonar o repositório

Se você ainda não tem o Claude Code rodando, dá uma passada no passo a passo pra instalar o Claude Code antes de seguir

Como criar e ativar uma skill no Claude Code passo a passo

Agora bora ver na prática

A anatomia é simples: uma pasta, um SKILL.md dentro, e pronto

1. Crie a pasta da skill em ~/.claude/skills/ (pessoal) ou em .claude/skills/ (projeto)

O nome da pasta importa, guarde isso pro próximo passo

mkdir -p .claude/skills/gerar-changelog

2. Crie o arquivo SKILL.md com o frontmatter YAML no topo

O SKILL.md tem duas partes: o frontmatter YAML entre os marcadores ---, com os campos obrigatórios name e description, e o corpo em markdown com as instruções

---
name: gerar-changelog
description: Gera um changelog a partir dos commits recentes. Use quando o usuário pedir para resumir mudanças ou preparar notas de versão.
---

# Como gerar o changelog

Agrupe os commits por tipo (feat, fix, docs)...

Aqui mora o erro comum deste passo: o campo name deve usar só letras minúsculas, números e hífens, e precisa ser IGUAL ao nome da pasta que contém o SKILL.md

Se a pasta é gerar-changelog e o name é gerarChangelog, quebra

3. Escreva o corpo em markdown com as instruções de verdade, abaixo do frontmatter

É aqui que você diz COMO a tarefa é feita, com os passos, exemplos e o que evitar

O erro comum deste passo está na description, não no corpo

A description explica o que a skill faz E quando usá-la, deve ser escrita em terceira pessoa, e é justamente o que o Claude usa pra decidir auto-invocar a skill

Description vaga tipo "ajuda com código" quebra a descoberta: o Claude não sabe quando chamar

4. Ative a skill

São duas formas

Automática: quando a análise do Claude casa com a description da skill, ele chama sozinho

Manual: você digita /nome-da-skill e força o uso

Uma mão na roda: o Claude Code monitora os diretórios de skills, então adicionar, editar ou remover uma skill passa a valer dentro da sessão atual, sem reiniciar

Se quiser ir mais fundo em criar, usar e migrar do formato antigo, tem o guia de como criar e usar Claude Code Skills aqui no blog

Comando slash ou skill: quando usar cada um

Se você já usava comando slash customizado, se liga nisso: comando slash e skill convergem

Um arquivo .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam AMBOS o mesmo /deploy

Então qual a diferença?

O formato de skill adiciona recursos opcionais que o comando slash puro não tem: arquivos de apoio junto, frontmatter pra controlar a invocação e carregamento automático pela relevância da description

Resumindo numa tabela:

O detalhe bacana do carregamento: ele é em duas fases

Na descoberta, toda sessão, o Claude lê APENAS o nome e a description de cada skill (custo mínimo de tokens)

O corpo do SKILL.md só entra no contexto na hora da invocação, sob demanda

E tem mais um caminho: skills chegam via plugins

O comando /plugin abre o gerenciador de plugins, com abas pra descobrir (Discover) e ver os instalados (Installed)

O marketplace oficial da Anthropic, o claude-plugins-official, já vem embutido assim que o Claude Code inicia, sem precisar adicionar nada

Um plugin é o pacote completão: empacota skills, agentes, hooks, servidores MCP e LSP numa unidade instalável

O que aprendi usando skills no dia a dia

Eu testei isso num projeto meu de gestão de produtos, um CRUD simples de itens, pra mostrar na prática

A skill que usei é a abordagem que anda circulando como "Karpathy Skills", aquele arquivo que promete parar a briga com o Claude Code

O foco dela: código mínimo, mexer só no necessário e diff limpo, atacando o over-engineering e as suposições silenciosas da IA

O caminho que segui foi instalar via plugin: adicionar o marketplace e depois o plugin

Optei por instalar só pro projeto, não global, porque acho mais limpo pra testar antes de decidir usar em tudo

Um aviso que quase me ferrou, e presta atenção na distinção porque ela confunde muita gente: editar uma skill já vale na hora, sem reiniciar, como falei lá em cima

Instalar um plugin novo é OUTRA história: o plugin recém-instalado só apareceu pra mim depois que recarreguei os plugins e reiniciei a sessão do Claude Code

Então guarda a regra: mexeu num SKILL.md, vale na hora; instalou plugin, dá o reload

Depois disso rodei um prompt simples: adicionar um botão de exportar CSV que exporta só os produtos visíveis/filtrados

Por ser tarefa simples, a IA não fez pergunta nenhuma e foi direto pra execução

Durante a execução dava pra ver as skills sendo carregadas e ativadas, o que pra mim foi a prova de que o plugin estava ativo de verdade

Aqui a economia de tokens faz sentido: na descoberta o Claude só lê o metadata, e o corpo da skill entra só quando ela é invocada

No fim recebi um relatório do que mudou, e a IA ainda fez uma verificação conferindo que as colunas exportadas batiam com as colunas visíveis da tabela

Cliquei no botão, o CSV foi gerado do jeito que eu queria e abriu direto no editor

Depois joguei um prompt vago e de escopo bem maior: adicionar um sistema de autenticação

Nesse caso a IA parou pra perguntar e alinhar as escolhas antes de implementar, em vez de sair codando

Pela experiência do teste, essa etapa de perguntas existe pra IA não assumir coisa por conta própria, mas ela não pergunta à toa quando dá pra resolver pelo prompt

No vídeo abaixo eu mostro esse passo a passo completo, os dois prompts e as skills ativando ao vivo

Minha conclusão foi que a skill resolve de uma vez três problemas clássicos de código gerado por IA: suposição silenciosa, over-engineering e falta de teste

É simples de instalar e, por ser gratuita, vale pelo menos testar pra melhorar a qualidade dos teus projetos

Próximos passos com skills no Claude Code

Se você chegou até aqui buscando por skills for Claude Code, já tem o mapa na mão

Começa pequeno: crie UMA skill de projeto pra uma tarefa que você repete sempre, tipo gerar changelog ou padronizar commit

Monta a pasta, escreve o SKILL.md com uma description boa e testa com /nome-da-skill na sessão atual

Deu certo? Aí você evolui: transforma teus comandos slash em skills, empacota num plugin e um dia até publica no marketplace

O caminho é esse, do arquivo solto pro pacote completo

Agora bora criar a tua primeira e ver ela ativando na prática =)