Melhores skills para Claude Code e Codex: o que instalar, como auditar um repositório antes e por que uma skill nova não é acionada

Name

Soren Atelier

Atualizado em 15/11/2026

Versão curta: instale poucas skills, não um repositório inteiro. Três regras:

1. Escolha pela tarefa. Comece com um pacote pequeno, só de texto, como o obra/superpowers (15 skills), ou com uma única skill, como a socratic-tutor da Jane Street. Deixe catálogos como google/skills (203 skills) e NVIDIA/skills (452) de lado até precisar de uma skill específica deles.
2. Leia antes de instalar. Uma skill é um conjunto de instruções mais scripts opcionais que rodam com as permissões do seu agente. O script de auditoria do Passo 1, mais abaixo, lista quais skills trazem código e quais arquivos abrir primeiro. Ele só lê arquivos.
3. Confira a listagem depois de instalar. O Claude Code mostra ao modelo uma lista com os nomes e as descrições das skills, e essa lista tem um limite. Em uma máquina que já tinha 98 skills, uma skill recém-instalada apareceu só pelo nome, então o modelo não tinha descrição para comparar com o pedido. Rode /skill-doctor e depois libere orçamento com skillOverrides ou aumente-o com skillListingBudgetFraction.

O que foi testado: todos os números daqui vêm de clones rasos feitos em 15 de novembro de 2026 e do Claude Code 2.1.325 no macOS. O script de auditoria, o claude plugin validate, o /skill-doctor e o log de depuração foram todos executados. Se o modelo depois escolhe uma skill por conta própria não foi testado, e SkillSpector, o instalador npx skills e o Codex também não. A tabela Testado vs. documentado, perto do fim, separa as duas coisas.

Dez repositórios de skills comparados

Agent skills são pastas com um arquivo SKILL.md que o Claude Code, o Codex e outros agentes carregam sob demanda. Se você precisa do formato em si, o guia Codex vs Claude Code Skills (em inglês) cobre caminhos, frontmatter e como compartilhar uma skill entre as duas ferramentas. Esta página trata de escolher e instalar skills de outras pessoas.

O interesse por repositórios de skills disparou no início de novembro. A Jane Street publicou um repositório de uma única skill em 3 de novembro, e ele chegou a 712 pontos no Hacker News. O GoogleChrome/modern-web-guidance lançou a versão 1.0.0 em 10 de novembro. O anthropics/skills ganhou cerca de 6.200 estrelas em uma semana.

A tabela conta todos os SKILL.md de cada repositório. "Caracteres de descrição" é o tamanho total do texto de description, que é o que o agente carrega para cada skill em cada turno. A última coluna compara esse total com o orçamento de listagem de 30.000 caracteres que o Claude Code informou na máquina de teste.

Três pontos chamam atenção.

• O tamanho varia em duas ordens de grandeza. Instalar google/skills ou NVIDIA/skills por inteiro estoura a listagem várias vezes. Os dois READMEs permitem instalar skills avulsas: NVIDIA com --skill, Google pelo prompt do instalador.
• A maioria das skills é Markdown puro. 552 das 782 skills não trazem código nenhum. As que trazem se concentram em skills de documentos, mídia e nuvem, em que um script cuida da parte determinística.
• Ferramentas pré-aprovadas são raras fora de um único catálogo. 126 skills do NVIDIA/skills e 2 do google/skills declaram allowed-tools. Nenhum dos outros oito repositórios faz isso.

Qual usar para cada tarefa

• obra/superpowers é um método de trabalho completo: fazer brainstorming, escrever um plano, executá-lo, depurar de forma sistemática e verificar antes de dar a tarefa por concluída. É o pacote grande mais barato em termos de contexto.
• addyosmani/agent-skills está mais para um conjunto de checklists de engenharia: revisão de código, design de API, CI, observabilidade, reforço de segurança. As descrições são mais longas, então 25 skills custam cerca de quatro vezes o que o Superpowers custa.
• mattpocock/skills aposta em comandos curtos que você mesmo chama (/grill-me, /tdd, /to-spec). Inclui oito skills in-progress.
• anthropics/skills é o conjunto de referência. Quem trabalha com dados costuma querer as skills xlsx, pdf, docx e pptx, que trazem os scripts que de fato geram os arquivos. Se a sua análise vive em notebooks, um agente que trabalha dentro do Jupyter, como o RunCell (opens in a new tab), cobre a parte que essas skills de arquivo não cobrem.
• GoogleChrome/modern-web-guidance são duas skills apoiadas em uma CLI que busca em um índice de guias, com o objetivo de manter os agentes longe de padrões de front-end ultrapassados.
• kajisho5/ffmpeg-skill é uma skill grande com 107 arquivos de código, espelhada em dois lugares, mais 14 skills de projeto do próprio autor em .claude/skills. Instale com o instalador dela, não copiando o repositório.

Passo 1: audite um repositório de skills antes de instalar

As instruções de uma skill entram no contexto do seu agente, e os scripts dela rodam com as permissões que a sua sessão tiver. Ler o repositório antes é a única defesa, então torne essa leitura rápida.

Este script percorre uma pasta, encontra todos os SKILL.md e mostra quais skills trazem código e quais contêm padrões que merecem uma olhada. Ele usa apenas a biblioteca padrão do Python e nunca executa nada da pasta que analisa.

#!/usr/bin/env python3
"""Read-only audit of SKILL.md folders. Runs nothing from the repo it scans."""
import os, re, sys
 
RISKY = {
    "pipe-to-shell": r"(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh",
    "reads-secrets": r"\.ssh/|\.aws/credentials|\.env\b|id_rsa|\.netrc|keychain",
    "sudo": r"\bsudo\s",
    "rm-rf": r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r",
    "skip-permissions": r"dangerously-skip-permissions|bypassPermissions|--yolo",
    "hidden-unicode": r"[\u200b\u200c\u200d\u2060\u202a-\u202e\U000e0000-\U000e007f]",
}
CODE = (".py", ".sh", ".js", ".mjs", ".ts", ".rb", ".ps1")
 
def frontmatter(text):
    m = re.match(r"^---\n(.*?)\n---\n?", text, re.S)
    if not m:
        return None, text
    fields, key = {}, None
    for line in m.group(1).splitlines():
        k = re.match(r"^([A-Za-z_-]+):\s*(.*)$", line)
        if k:
            key = k.group(1)
            fields[key] = k.group(2).strip().strip("\"'")
        elif key and line.startswith((" ", "\t")):
            fields[key] += " " + line.strip()
    return fields, text[m.end():]
 
def audit(root):
    rows = []
    for folder, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in (".git", "node_modules")]
        if "SKILL.md" not in files:
            continue
        text = open(os.path.join(folder, "SKILL.md"), encoding="utf-8", errors="replace").read()
        fields, body = frontmatter(text)
        everything, code_files = text, 0
        for sub, _, names in os.walk(folder):
            for n in names:
                if n.endswith(CODE):
                    code_files += 1
                if n.endswith(CODE + (".md",)) and n != "SKILL.md":
                    try:
                        everything += open(os.path.join(sub, n), encoding="utf-8", errors="replace").read()
                    except OSError:
                        pass
        flags = [name for name, pat in RISKY.items() if re.search(pat, everything)]
        if fields is None:
            flags.append("no-frontmatter")
            fields = {}
        if fields.get("allowed-tools"):
            flags.append("allowed-tools")
        if "hooks" in fields:
            flags.append("hooks")
        if re.search(r"!`[^`]+`|```!", body):
            flags.append("shell-injection-block")
        desc = (fields.get("description", "") + " " + fields.get("when_to_use", "")).strip()
        rows.append((os.path.relpath(folder, root), len(desc), len(body), code_files, flags))
    return rows
 
if __name__ == "__main__":
    rows = audit(sys.argv[1])
    listing = sum(d for _, d, _, _, _ in rows)
    print(f"{len(rows)} skills, {listing:,} description chars (~{listing // 4:,} tokens if all are listed)")
    print(f"{sum(1 for r in rows if r[3])} skills ship code files, {sum(r[3] for r in rows)} code files in total")
    for path, desc, body, code, flags in sorted(rows, key=lambda r: (-len(r[4]), r[0])):
        if flags or "-v" in sys.argv:
            print(f"  {path}: desc={desc} body={body} code={code} flags={','.join(flags) or '-'}")

Clone o repositório em algum lugar fora do seu projeto e aponte o script para ele.

git clone --depth 1 https://github.com/obra/superpowers /tmp/superpowers
python3 audit_skills.py /tmp/superpowers

A saída para o Superpowers em 15 de novembro:

15 skills, 2,317 description chars (~579 tokens if all are listed)
3 skills ship code files, 6 code files in total
  skills/brainstorming: desc=213 body=14933 code=3 flags=rm-rf
  skills/subagent-driven-development: desc=85 body=19484 code=0 flags=rm-rf
  skills/systematic-debugging: desc=91 body=9366 code=2 flags=reads-secrets

Como ler as flags

Uma flag quer dizer "abra este arquivo", não "esta skill é maliciosa". Todas as flags conferidas à mão nesses dez repositórios eram inofensivas. O rm-rf do Superpowers é um rm -rf "$SESSION_DIR" em um script que limpa a própria pasta temporária. O hidden-unicode do ffmpeg-skill é um zero-width joiner dentro de uma nota sobre ligaduras do hindi. reads-secrets dispara em qualquer menção a .env, inclusive no conselho de não fazer commit de um.

As três últimas são as que mais importam no Claude Code. allowed-tools concede ferramentas sem perguntar durante o turno que invoca a skill. Uma entrada hooks continua rodando pelo resto da sessão. Um bloco !`command` executa quando a skill é carregada.

Mais duas verificações

O Claude Code pode validar o frontmatter para você. O comando rodou sem erros em uma pasta com 91 skills instaladas. Em um repositório que não está empacotado como plugin, ele falha com No manifest found, o que indica que o repositório só serve para cópia.

claude plugin validate .claude/skills

Para uma análise mais profunda, o SkillSpector (opens in a new tab) da NVIDIA é um scanner dedicado, com 71 padrões e uma pontuação de risco de 0 a 100. O README dele indica este como o caminho rápido; ele não foi executado para este artigo.

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan ./my-skill/ --no-llm

Passo 2: instale só o que você precisa

Copiar uma pasta é o método de instalação com menos peças móveis, e foi o testado aqui.

git clone --depth 1 https://github.com/janestreet/agent_skills /tmp/agent_skills
mkdir -p .claude/skills
cp -R /tmp/agent_skills/socratic-tutor .claude/skills/

O destino define onde a skill é carregada.

Prefira a pasta do projeto para tudo o que você está experimentando. Assim a skill fica fora das suas outras sessões, e basta apagar a pasta para removê-la.

Os outros dois caminhos vêm do README de cada projeto e não foram executados aqui.

• Plugins instalam um pacote inteiro e são atualizados pelo /plugin. Por exemplo, /plugin marketplace add anthropics/skills e depois /plugin install document-skills@anthropic-agent-skills. O Superpowers é /plugin install superpowers@claude-plugins-official.
• A CLI skills da Vercel Labs copia arquivos para o projeto para vários agentes de uma vez: npx skills add addyosmani/agent-skills --skill test-driven-development -a claude-code. Adicione --list para navegar antes.

Uma ressalva da documentação do Claude Code: skillOverrides não se aplica a skills de plugin. Se um pacote de plugin for grande demais, você desativa o plugin, não skills individuais.

Passo 3: confira se a skill nova está mesmo listada

Este passo pega uma causa de "instalei, mas nunca é acionada" que não gera nenhum erro.

O Claude Code entrega ao modelo uma listagem com o nome e a descrição de cada skill. A listagem tem um orçamento, por padrão 1% da janela de contexto. Quando ela estoura, o Claude Code mantém todos os nomes, mas descarta descrições, começando pelas skills que você menos usa. Uma skill recém-instalada tem zero usos. A documentação do Claude Code descreve o mecanismo na seção Skill descriptions are cut short (descrições de skills são cortadas) (opens in a new tab); os números abaixo mostram como isso aparece na prática.

Veja como isso ficou em uma máquina que já tinha 84 skills pessoais e 14 skills de plugin. Depois de copiar uma skill nova, o log de depuração dizia:

[WARN] Skill listing over budget: 112 skills, 37491 chars > 30000 budget — descriptions will be truncated.

E o /skill-doctor mostrou a skill nova listada só pelo nome:

Um custo de < 20 sozinho não prova nada, porque uma skill com descrição de uma linha também custa menos de 20. Compare-o com o tamanho da descrição. As contagens abaixo só incluem skills com descrições longas o bastante para dar para distinguir.

Adicionar mais skills piorou a situação de todas as outras. Com 91 skills de projeto instaladas, 76 foram listadas e 70 delas tinham perdido uma descrição de 80 caracteres ou mais. Com 289, o número de skills pessoais que tinham perdido a descrição subiu de 6 para 39: as recém-chegadas expulsaram descrições de skills que vinham funcionando.

Rode a verificação

O /skill-doctor imprime uma linha por skill com o custo dela na listagem. Ele exige o Claude Code 2.1.252 ou mais recente e funciona no modo -p.

claude -p "/skill-doctor"

Para ver o próprio aviso de orçamento, grave um log de depuração e procure nele.

claude --debug-file /tmp/cc-debug.log -p "hello"
grep "Skill listing over budget" /tmp/cc-debug.log

Corrija

Primeiro desligue o que você não usa. Isto vai em .claude/settings.json para o projeto, ou em ~/.claude/settings.json para todos os projetos.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

"name-only" mantém a skill disponível como /name, mas tira a descrição dela da listagem. "off" a esconde por completo. Em uma sessão interativa, /skills grava a mesma configuração: pressione Space em uma linha para alternar o estado dela e depois Esc para salvar.

Se você realmente usa tudo, aumente o orçamento. Isso custa contexto em todos os turnos.

{
  "skillListingBudgetFraction": 0.02
}

O Codex tem o mesmo mecanismo, com números diferentes. A documentação dele diz que a lista inicial de skills usa no máximo 2% da janela de contexto, ou 8.000 caracteres quando a janela é desconhecida, que ele encurta as descrições primeiro e que pode omitir skills da lista com um aviso. skills.max_context_tokens altera o orçamento, e uma entrada [[skills.config]] com enabled = false em ~/.codex/config.toml desativa uma skill.

Passo 4: deixe uma skill rodar sem supervisão

O Claude Code 2.1.325, lançado em 13 de novembro, mudou um comportamento que afeta o trabalho agendado. Tarefas agendadas e o /loop agora perguntam antes de executar uma skill que declara allowed-tools ou hooks. Para rodar uma skill dessas sem prompt, libere-a pelo nome.

{
  "permissions": {
    "allow": ["Skill(release-notes)"]
  }
}

O inverso também funciona. Uma regra deny como Skill(deploy *) impede o modelo de invocar uma skill, e negar Skill sem argumento desliga todas. As duas informações vêm da documentação do Claude Code. O guia Como blindar as permissões do Claude Code cobre o restante das configurações de permissão que vale a pena versionar no repositório.

Passo 5: remova uma skill

• Skill copiada: apague a pasta dela em .claude/skills/ ou .agents/skills/.
• Skill de plugin: /plugin uninstall <plugin>@<marketplace>, ou desative-a em /plugin.
• Manter, mas sem uso automático: defina "name-only" ou "off" para ela em skillOverrides, ou adicione disable-model-invocation: true ao frontmatter, se o arquivo for seu.

Testado vs. documentado

O orçamento de 30.000 caracteres é o que uma máquina informou. O seu depende da janela de contexto do modelo, então leia o seu próprio log de depuração antes de confiar na coluna de porcentagem.

FAQ

Quais agent skills devo instalar primeiro no Claude Code?

Comece pequeno. O obra/superpowers entrega um fluxo completo de plano, teste, depuração e revisão em 15 skills. O addyosmani/agent-skills acrescenta 25 checklists de engenharia. Para planilhas, PDFs e slides, instale o plugin document-skills do anthropics/skills. Dos catálogos grandes, instale skills avulsas em vez do pacote todo.

Por que minha skill nova do Claude Code não é acionada?

Em uma máquina com muitas skills, a listagem provavelmente passou do orçamento e a skill nova está listada só pelo nome. Rode /skill-doctor. Um custo de contexto abaixo de 20 em uma skill com descrição longa significa que a descrição foi descartada. Desligue skills não usadas com skillOverrides ou aumente skillListingBudgetFraction.

Como verifico se uma skill é segura antes de instalar?

Clone fora do seu projeto e leia. Procure scripts embutidos, allowed-tools, hooks e blocos !`command`. O script de auditoria acima lista tudo isso para cada SKILL.md sem executar nada.

Quantas skills são demais para o Claude Code?

Depende do tamanho das descrições, não da quantidade. Vinte skills do anthropics/skills usam cerca de 9.500 caracteres de um orçamento de 30.000. O google/skills inteiro precisa de cerca de 107.600.

O que o /skill-doctor faz?

Ele imprime todas as skills carregadas com a origem, o custo na listagem, o uso de tokens em 7 dias e o número de invocações, e sinaliza as que nunca foram usadas. Exige o Claude Code 2.1.252 ou mais recente.

Onde coloco uma skill para o Claude Code e o Codex usarem?

.claude/skills/ para o Claude Code e .agents/skills/ para o Codex, no projeto ou no seu diretório home. Mantenha uma cópia e crie um symlink para a outra.

Posso desativar uma skill sem apagá-la?

Sim: skillOverrides nas configurações do Claude Code, ou [[skills.config]] com enabled = false no Codex. Skills de plugin são gerenciadas pelo /plugin.

Por que uma tarefa agendada pergunta antes de executar minha skill no Claude Code 2.1.325?

Tarefas agendadas e o /loop agora perguntam antes de executar uma skill que declara allowed-tools ou hooks. Adicione Skill(name) a permissions.allow.

Fontes

• Extend Claude with skills (opens in a new tab) e a referência de configurações (opens in a new tab), documentação do Claude Code
• Changelog do Claude Code (opens in a new tab), versão 2.1.325
• Build skills (opens in a new tab), documentação do Codex
• Especificação Agent Skills (opens in a new tab)
• READMEs de vercel-labs/skills (opens in a new tab) e NVIDIA/SkillSpector (opens in a new tab)
• Socratic Tutor no Hacker News (opens in a new tab)

Guias relacionados

• Como blindar as permissões do Claude Code: bloquear gravações fora do repositório, negar em vez de perguntar e auditar o settings.local.json
• Tutorial de Claude Code Mods: como criar, testar e instalar seu primeiro mod
• Guia prático de como usar o OpenCode: primeiros passos, 7 dicas e quando somar Oh My OpenCode
• Guia prático de como usar o Codex: primeiros passos, 5 dicas e best practices
• Claude Code Desktop: como ativar Bypass permissions