Skills no Claude Code: o que são e como usar na prática

Se você já se pegou colando o mesmo prompt gigante toda vez que abre o Claude Code, as skills existem pra acabar com isso

Elas mudam o fluxo: em vez de você lembrar de pedir, o Claude passa a saber sozinho o que fazer quando o assunto aparece

Se você nunca configurou uma, relaxa que a ideia é simples de entender

Uma skill é só uma pasta com um arquivo de instruções dentro

Você escreve ali o que quer que o Claude faça, e ele usa aquilo quando o momento pede

Bora entender como isso funciona e como montar a sua primeira

Como as skills funcionam por baixo dos panos

Duas coisas fazem a mágica acontecer aqui, e vale entender as duas antes de sair criando pasta

A primeira é que as skills são model-invoked

O que isso significa? Que quem decide usar a skill é o próprio Claude, não você

Ele compara o seu pedido com a description de cada skill que você tem e, quando bate, aciona automaticamente

É como ter um dev sênior do lado que já sabe qual manual pegar da estante quando você fala o problema

Por isso a descrição é a parte mais importante do arquivo: é ela que ensina o Claude QUANDO usar aquilo

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

A segunda coisa é o progressive disclosure, e aqui mora a sacada

"Mas se eu tiver 20 skills isso não vai entupir o contexto?"

Não, e é justamente esse o ponto

No startup, o Claude Code carrega só o nome e a description de cada skill (poucas dezenas de tokens por skill)

O corpo completo, com todas as instruções e scripts, fica parado no disco

Só quando a skill é acionada é que o conteúdo inteiro entra em cena

Assim você pode ter um monte de skills instaladas sem estourar a janela de contexto, porque o peso só chega sob demanda

Como criar e usar uma skill no Claude Code

Criar uma skill do zero é mais tranquilo do que parece

Se você já mexeu com migrar slash commands para skills, boa parte disso já vai soar familiar

1. Escolha onde a skill vai morar. Existem dois lugares: ~/.claude/skills/ guarda as suas skills pessoais, que valem em todo projeto seu; e .claude/skills/ dentro do repositório guarda as skills daquele projeto, que viajam junto com o repo quando alguém clona

O erro comum aqui: jogar tudo no pessoal e depois o colega não ter a skill que o projeto precisava

Se a skill é específica daquele código, ela vai no .claude/skills/ do repo

2. Crie a pasta da skill com um SKILL.md dentro. A pasta pode ter scripts e arquivos de referência opcionais, mas o único arquivo obrigatório é o SKILL.md

.claude/skills/
  revisao-seguranca/
    SKILL.md

O erro comum: esquecer que o nome do arquivo é SKILL.md em caixa alta

3. Escreva o YAML frontmatter no topo do SKILL.md. O frontmatter fica entre marcadores --- e é ali que você configura a skill

---
name: revisao-seguranca
description: Analisa o projeto atrás de secrets expostos, inputs sem validação e problemas de autenticação. Use antes de subir código pra produção.
allowed-tools: Read, Grep, Bash
---

# Revisão de segurança

Aqui vão as instruções do que a skill faz, passo a passo...

O campo description é o recomendado, porque é ele que o Claude lê pra saber quando ativar a skill

Outros campos que você pode usar: name, allowed-tools (pra limitar quais ferramentas a skill pode tocar) e disable-model-invocation

O erro comum, e esse é o mais fatal: escrever uma description vaga tipo "ajuda com segurança"

Se a descrição não deixa claro QUANDO usar, o Claude não aciona na hora certa

Capricha nela como se fosse o gatilho que é

4. Testa na prática. Abre o Claude Code no projeto e faz um pedido que combine com a description

Se você escreveu bem, ele vai acionar a skill sozinho sem você precisar chamar pelo nome

Faça o teste!

Instalar skills prontas via plugins e marketplace

Nem tudo você precisa criar do zero

Dá pra instalar skills prontas através de plugins, e aqui entra um conceito novo

Um plugin é um pacote de nível mais alto: ele é um bundle que pode trazer skills, agentes, hooks e servidores MCP juntos

E esses plugins vivem em marketplaces

O repositório oficial anthropics/skills pode ser registrado como um marketplace, e aí você instala os plugins de dentro dele

A instalação de um plugin sai com um comando tipo esse:

/plugin install document-skills@anthropic-agent-skills

A leitura é direta: você tá instalando o plugin document-skills que vem do marketplace anthropic-agent-skills

O erro comum: tentar instalar o plugin sem ter o marketplace registrado antes

A ordem importa, primeiro você registra a fonte, depois puxa o plugin dela

O passo a passo de cada repositório costuma vir documentado no próprio repo, então vale sempre dar uma olhada nas instruções de lá antes

Skills não são só do Claude Code

Um detalhe que muita gente não sacou ainda: skill não é coisa exclusiva do Claude Code

O Claude na web (Claude.ai) e o Claude Desktop também suportam skills

Na prática isso é topzera, porque você define a skill uma vez e usa ela em vários lugares

A mesma lógica de pasta com SKILL.md autocontida vale nesses outros ambientes

E se você quer ver exemplo real pra se inspirar, o repositório público anthropics/skills é a fonte

Lá tem skills de exemplo que vão de aplicações criativas a tarefas técnicas e fluxos empresariais

Cada uma é autocontida na própria pasta, com o seu SKILL.md

É um ótimo lugar pra estudar como as pessoas escrevem uma boa description e estruturam as instruções

Skills que uso em todos os meus projetos

No vídeo abaixo eu mostro na prática como as skills se encadeiam pra levantar um projeto do zero

Peguei uma pasta em branco e usei seis skills em sequência pra construir um app de controle de despesas pessoais

Comecei pela skill de brainstorm, voltada a planejamento

Ela faz perguntas em estilo socrático antes de codar qualquer linha: se o app tem múltiplos usuários com autenticação, se o login é e-mail e senha, se as categorias de gasto são fixas ou customizáveis

Ela até ofereceu gerar mockups e diagramas no navegador durante a conversa, mas avisou que isso consome mais token

Recusei pra ir direto pra implementação

Com o documento de design aprovado, pedi pra uma segunda skill transformar tudo num plano de implementação: tarefas em ordem, dependências e critério de aceitação por tarefa

Deu um plano com 14 tarefas

Aí usei uma terceira skill pra executar o plano e gerar o código

Uma dica que dou: marca o arquivo do plano com @ pra garantir que o Claude execute o certo

Na execução aparece MUITO pedido de aceite

Recomendo usar o modo de pular (skip) na fase de criar arquivo e setup, senão você fica aprovando coisa a sessão inteira

teve etapa de configuração de sessão que rodou por quase 10 minutos

Quando testei no navegador, deu um erro no fluxo de cadastro e login

Copiei o erro, mandei o Claude analisar e corrigir, e considero isso normal no prompt inicial

Depois do ajuste o app funcionou: telas do gerenciador financeiro, cadastro de despesa e autenticação rodando em localhost:3000

Cadastrei uma despesa de exemplo de R$ 1.000 com alimentação e tava tudo de pé

Só que a interface saiu genérica, sem alma, aquele AI slop clássico

Corrigi com uma skill de frontend design, com um prompt de redesign (visual clean e moderno, modo escuro, passar confiança financeira)

Mudou bastante: tipografia, cores de acento, cards, navbar e até animações

E aqui vai o recado que eu bato sempre: o resultado do design depende do prompt

Muita gente reclama que a IA não entrega o que quer, mas na real o problema costuma ser prompt ruim

As duas últimas do fluxo não vieram prontas de prateleira: são skills que eu criei sob medida pro projeto

Eu prefiro criar sob medida em vez de baixar pronto, e às vezes mando o próprio Claude criar

Uma delas é uma skill de segurança do projeto (não global) que analisa o código e dá uma nota de 0 a 100

Ela tem verificação mecânica que roda comandos reais e conta problemas em áreas como secrets, inputs, autenticação, dependências e headers

No fim ela imprime a nota total, o breakdown por categoria e a lista de problemas

Quando vale a pena criar uma skill

"Beleza, mas eu preciso mesmo disso ou um prompt resolve?"

Pergunta justa

Skill não é pra tudo

Ela brilha quando existe um padrão que se repete e que você não quer explicar de novo toda vez

Algumas situações onde a skill ganha do prompt solto:

• Padrões recorrentes. Se toda semana você pede a mesma coisa do mesmo jeito, isso vira uma skill e o Claude passa a aplicar sozinho
• Revisão de segurança. Aquela minha skill de nota 0 a 100 é o exemplo perfeito: é uma checagem que você quer rodando sempre igual, com os mesmos critérios
• Setup de sessão. Se todo projeto começa com o mesmo ritual de configuração, empacota num skill e para de repetir
• Tarefas técnicas autocontidas. Coisa que tem começo, meio e fim bem definidos, com instruções que valem sempre

Um bom termômetro: se você já escreveu o mesmo prompt três vezes, provavelmente ele merece virar skill

E se o seu fluxo envolve versionamento, dá pra combinar com o jeito de usar o Claude Code com Git pra fechar o ciclo de ponta a ponta

Conclusão

As skills deixam o Claude Code construir projeto do zero com uma arquitetura melhor: planejam antes, implementam, dão identidade ao front-end e ainda checam segurança

Mesmo demorando mais e gastando mais token, o resultado sai mais certeiro e cobre ponto que passaria batido

O custo de entrada é baixo: uma pasta e um SKILL.md com uma boa description

Meu conselho de próximo passo é começar por uma skill pessoal simples em ~/.claude/skills/, algo que você já pede sempre

Ou, se quiser ver como os outros fazem antes, instala uma skill do repositório oficial anthropics/skills e observa a estrutura por dentro

Começa pequeno, testa, e vai crescendo o seu arsenal a partir dali…

até o próximo post!