Claude skills download: o que você realmente baixa e o que ler antes de rodar

Baixar uma skill não é instalar um programa, é entregar um texto de instruções pra um agente que já está com todas as suas ferramentas na mão

E isso muda completamente a pergunta que você precisa fazer antes de rodar

A ideia deste post não é te ensinar a clicar em instalar

Aqui a gente abre a pasta que veio no download e lê o que tem dentro, campo por campo, antes do primeiro uso

Motivo pra não instalar no escuro? A Snyk auditou 3.984 skills do ClawHub e do skills.sh, com corte em 5 de fevereiro de 2026, e encontrou falha de segurança em cerca de 36% delas (estudo ToxicSkills)

É muita coisa pra sair dando next, next e finish

Bora abrir a pasta? 🙂

Antes de abrir: onde a skill vai morar e como ela é carregada:

Toda skill é uma pasta com um arquivo SKILL.md dentro

Esse arquivo tem duas partes: o frontmatter YAML (aquele bloco entre os marcadores ---) e o corpo em markdown, que são as instruções que o agente segue quando a skill roda

Se você quer o conceito antes da anatomia, já escrevi por aqui sobre o que é uma skill e como ela guia o Claude

Os quatro lugares onde ela pode estar:

No Claude Code, uma skill pode viver em quatro locais:

• enterprise, via managed settings
• pessoal, em ~/.claude/skills/<nome-da-skill>/SKILL.md
• de projeto, em .claude/skills/<nome-da-skill>/SKILL.md
• de plugin, em <plugin>/skills/<nome-da-skill>/SKILL.md

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

É mais ou menos como variável de escopo: existe a global da sua máquina e existe a que só vale dentro daquele projeto

E quando duas skills de níveis diferentes têm o mesmo nome, tem ordem, mas ela vale pra três desses quatro locais: enterprise sobrepõe pessoal, e pessoal sobrepõe projeto

Pra skill que vem de plugin, a documentação não coloca ela nessa fila, e vale lembrar que o nome dela chega prefixado pelo namespace do plugin

Tome cuidado com isso ao revisar, porque a pasta que você abriu pode não ser a que está rodando

Outro detalhe que confunde: uma entrada em enterprise, pessoal ou de projeto pode ser um symlink apontando pra um diretório em outro canto do disco

O Claude Code segue o symlink e lê o SKILL.md do destino, e se o mesmo alvo é alcançável por vários locais, ele carrega uma vez só

Divulgação progressiva: por que a description manda tanto?

Aqui está o ponto que mais gente ignora

As skills funcionam por divulgação progressiva: no início, o Claude carrega só os metadados (name e description) e coloca isso no system prompt

O corpo do arquivo e os arquivos extras só entram no contexto quando a skill é acionada

É tipo o índice de um livro: ele decora a lista de capítulos e só vai buscar a página quando precisa

Quando o corpo referencia outros arquivos (um FORMS.md, um schema), o Claude lê esses arquivos com comandos bash adicionais, e o que não é acessado não consome contexto

E quando as instruções mencionam scripts executáveis, o Claude roda o script via bash e recebe apenas a saída: o código do script nunca entra no contexto

Guarde essa frase, ela volta lá no roteiro de leitura

Editou o arquivo? Não precisa reiniciar

Ao adicionar, editar ou remover uma skill em ~/.claude/skills/ (o local pessoal) ou no .claude/skills/ do projeto, o Claude Code detecta a mudança na sessão atual

Mesma coisa vale pra um .claude/skills/ que esteja dentro de um diretório passado com --add-dir, e isso não é um quinto lugar da lista: é o mesmo .claude/skills/ de sempre, só que num diretório extra anexado à sessão

Sem restart, sem fechar tudo

E os outros dois locais? Pra enterprise e pra skill que vem de plugin a documentação não afirma esse recarregamento, então não conte com ele

Isso é ótimo pra revisar: você corrige um campo e já vale

Roteiro de leitura: 7 trechos para revisar antes de rodar a skill:

A estrutura mínima que você vai encontrar é essa:

.claude/skills/
└── revisao-de-seguranca/
    └── SKILL.md

Agora, os sete pontos de parada, na ordem

1. Confirme que existe o SKILL.md e que o nome da pasta bate com o name

O nome da pasta de nível superior precisa bater com o name declarado no frontmatter (a comparação ignora caixa e underscore)

O campo name tem limite de 64 caracteres, aceita apenas letras minúsculas, números e hífens, e não pode conter tags XML nem as palavras reservadas anthropic e claude

O erro comum deste passo: renomear a pasta pra organizar sua vida e quebrar o pareamento com o name

2. Leia a description inteira, com calma

Ela é o gatilho: é o que o Claude compara com o pedido do usuário pra decidir se aciona a skill

Por isso ela precisa dizer o que a skill faz E quando usar

O limite é de 1024 caracteres, ela não pode ser vazia e não pode conter tags XML

---
name: revisao-de-seguranca
description: Revisa alterações de código procurando padrões de risco. Use quando o usuário pedir revisão de segurança antes de um deploy.
---

O erro comum deste passo: aceitar uma description vaga ou abrangente demais

Description genérica é skill disparando em prompt que não pediu nada disso

3. Cheque o allowed-tools

Esse é o trecho de maior consequência do arquivo inteiro

As ferramentas listadas ali ficam liberadas sem aprovação por uso enquanto a skill está ativa

Ou seja: você aprova uma vez, no papel, e não vê mais o pedido durante a execução

O erro comum deste passo: passar o olho e seguir

Se você não entendeu por que aquela ferramenta específica está liberada, a skill ainda não foi revisada

4. Cheque o disallowed-tools

Skills e comandos também podem declarar disallowed-tools no frontmatter, o que remove ferramentas do modelo enquanto a skill está ativa

É o lado bom da força: skill bem escrita costuma restringir o que não precisa

5. Avalie ligar o disable-model-invocation

disable-model-invocation: true

Esse campo bloqueia a invocação programática e esconde a skill do contexto do Claude, deixando ela disponível só por chamada manual

É o freio de mão pra skill nova que você quer testar no seu tempo, sem ela pulando sozinha no meio de outro trabalho

6. Leia o corpo procurando arquivos referenciados e scripts

Lembra da divulgação progressiva? Arquivos de referência são lidos sob demanda via bash, e scripts rodam no bash com só a saída voltando pro contexto

Traduzindo: o código do script nunca vai aparecer pra você durante o uso

Se você não ler agora, não lê nunca

O erro comum deste passo: revisar só o SKILL.md e ignorar os arquivos que ele chama

A parte interessante mora quase sempre no arquivo de apoio

7. Passe o arquivo por um scanner antes de instalar

Tem ferramenta pronta pra isso, e é de graça

O SkillSpector, da NVIDIA, é um scanner open source de segurança pra skills de agente: analisa vulnerabilidades, padrões maliciosos, injeção de prompt, exfiltração de dados e riscos de cadeia de suprimentos em skills de Claude Code, Codex e MCP, antes da instalação

O Agent Scan, da Snyk, analisa arquivos SKILL.md procurando padrões maliciosos conhecidos: instruções escondidas em formatos ofuscados (base64, Unicode, outros idiomas), frases do tipo ignore previous instructions, personificação de mensagem de sistema e tentativas de exfiltração

Por que tanto zelo? Os números do ToxicSkills explicam: 13% de chance de uma skill instalada conter falha de nível crítico, 76 payloads maliciosos confirmados voltados a roubo de credencial, instalação de backdoor e exfiltração de dados

E mais: 91% do malware verificado combina jailbreak em linguagem natural com payload executável

Injeção de prompt é a técnica dominante, e ela cabe inteirinha dentro de um markdown bonitinho 😅

De onde a skill veio muda o que você precisa checar:

Nem toda origem pede o mesmo nível de leitura, beleza?

O repositório oficial é o github.com/anthropics/skills, e vale abrir mesmo que você não vá instalar nada de lá: é referência de como um SKILL.md bem escrito se parece

Pra registrar um marketplace, o comando é esse:

/plugin marketplace add <repo>

Se o assunto é garimpo, já mostrei por aqui onde encontrar skills prontas e como esse fluxo funciona

E quando vem dentro de um plugin?

Aí o pacote é maior do que você imagina

Um plugin agrupa uma ou mais skills junto de extensões opcionais como hooks e configurações de servidor MCP, além de comandos e agentes

Instalar o plugin traz todas as skills que ele contém, não dá pra escolher uma só

A boa notícia: ao selecionar um plugin pra ver os detalhes, o painel mostra o que será instalado, ou seja, os comandos, agentes, skills, hooks e servidores MCP e LSP

Leia esse painel antes de confirmar, ele existe exatamente pra isso

Dentro de um plugin, as skills ficam no diretório skills/, e o nome da pasta vira o nome da skill prefixado pelo namespace do plugin

A pasta hello/ em um plugin chamado my-first-plugin vira /my-first-plugin:hello

Tem uma proteção boa aqui também: symlinks que apontam pra fora do marketplace de plugins são ignorados, justamente pra impedir que um plugin puxe arquivos arbitrários da sua máquina pro cache

O formato não é exclusivo do Claude

Detalhe que muda o tamanho do problema: o estudo da Snyk cobriu skills que atingem usuários de OpenClaw, Claude Code e Cursor

Ou seja, o SKILL.md é um formato compartilhado por várias ferramentas agênticas

A skill que você baixou pensando em uma ferramenta pode acabar sendo lida por outra

O que aprendi na prática com skill pronta já instalada:

Eu já tinha skills instaladas na máquina, vindas do uso do dia a dia com outras ferramentas agênticas

E segui pro Codex nesse cenário, sem limpar nada

Aí veio a surpresa: rodei um prompt simples de landing page em um projeto novo e vi o Codex acionando essas skills instaladas sem que eu tivesse pedido nada relacionado a elas

No vídeo eu faço a ressalva pra quem assiste, porque o resultado não seria igual pra quem está começando limpo: quem não tem skills instaladas não vê esse comportamento

Minha leitura é que isso acontece porque as minhas estão em pasta genérica, disponíveis pra qualquer ferramenta agênica ler, e não presas a um projeto

Skill, no fim, é arquivo markdown com instruções pra executar alguma tarefa no projeto: análise de saúde do código, revisão, planejamento de deploy, verificação de segurança, verificação de performance, criação de componente ou página, por aí vai

E é justamente por ser tão fácil acumular que eu bato nessa tecla: excesso de skill atrapalha

A ferramenta passa a usar quando ninguém pediu, e isso pode aumentar o consumo

Já tratei desse mesmo problema em vídeos anteriores sobre outras ferramentas agênicas, então não é caso isolado não

No vídeo acima eu mostro o Codex do zero, com skills e um projeto de verdade, e dá pra ver esse acionamento automático acontecendo ao vivo

Conclusão

Skill é texto, e é isso que resolve o problema e cria o problema ao mesmo tempo

Como é texto, leitura é a defesa: dá pra abrir, entender e recusar antes de rodar qualquer coisa

O trecho decisivo é o frontmatter, sempre: a description, que decide quando a skill acorda, e o allowed-tools, que decide o que ela pode fazer sem te perguntar

Próximo passo bem concreto pra próxima skill que você baixar:

1. coloque em .claude/skills/ do projeto, não na pasta pessoal, pra deixar o alcance curto
2. revise pelo roteiro dos 7 trechos
3. passe no SkillSpector ou no Agent Scan
4. só então use

E se quiser segurar ela na coleira enquanto observa, começa com disable-model-invocation: true e chama na mão

Revisar leva alguns minutos, e é bem mais barato que descobrir depois o que aquele script fazia 😀

até o próximo post!