Guia de campo do Claude Code em português

Skills no Claude Code: o que são e como criar a primeira no Windows

Uma skill é uma pasta com um arquivo de instruções que o Claude só carrega quando precisa: um procedimento, um checklist, uma referência longa (p. 59). Abaixo, quando ela vale mais que o CLAUDE.md, uma skill pronta para colar no PowerShell, os campos que decidem quem a chama e como provar que ela ajuda.

Skill, CLAUDE.md ou hook?

A skill é uma pasta com um arquivo SKILL.md: no alto, um bloco YAML diz o que ela faz e quando usar; abaixo, em Markdown, vêm as instruções. O Claude a usa sozinho quando o seu pedido casa com a descrição, ou você a chama digitando / e o nome (p. 60). A diferença para o CLAUDE.md está em quando cada um entra na janela: o CLAUDE.md vai inteiro em toda requisição; da skill, na abertura da sessão, entram só o nome e a descrição, e o corpo só quando ela é chamada. Material longo de referência custa quase nada até ser usado.

Quando acontece isto	Ponha em
O Claude erra a mesma convenção duas vezes	CLAUDE.md: fato curto, válido em toda sessão
Você cola o mesmo roteiro de vários passos pela terceira vez	Skill
Algo tem de acontecer toda vez, sem depender de o Claude lembrar	Hook
Uma tarefa lateral enche a conversa de saída que você não vai reler	Subagente

Regra sem exceção ("nunca edite a pasta dist/") não é skill: a skill depende de o Claude segui-la, e o hook roda sempre (p. 60). O antigo comando personalizado virou skill: .claude/commands/publicar.md e .claude/skills/publicar/SKILL.md criam o mesmo /publicar; com os dois, vence a skill.

A primeira skill, colada no PowerShell

O exemplo cria uma skill pessoal, que vale em todos os seus projetos, para resumir as mudanças ainda não commitadas num repositório git e apontar riscos (p. 61):

PowerShell, Windows

$pasta = "$HOME\.claude\skills\resumir-mudancas"
New-Item -ItemType Directory -Force $pasta | Out-Null
$texto = @'
---
description: Resume as mudanças não commitadas e aponta riscos.
  Use quando o usuário perguntar o que mudou, pedir mensagem
  de commit ou revisão do diff.
---
## Mudanças atuais
!`git diff HEAD`
## Instruções
Resuma as mudanças em dois ou três tópicos e liste os riscos que notar.
Se o diff estiver vazio, diga que não há mudanças.
'@
[IO.File]::WriteAllText("$pasta\SKILL.md", $texto)

A linha !`git diff HEAD` é injeção de contexto: o Claude Code roda o comando e troca a linha pela saída antes de o Claude ler a skill, então a resposta parte do diff real. O WriteAllText grava UTF-8 sem BOM no PowerShell 5.1 e no 7, e o arquivo precisa começar com ---, que é onde o Claude Code procura o frontmatter. Para testar, abra o claude num repositório com uma edição qualquer e pergunte "O que eu mudei?", ou digite /resumir-mudancas. Num repositório sem nenhum commit o git diff HEAD falha, e comando injetado que falha aborta a skill inteira: faça o primeiro commit antes (p. 61).

Onde a pasta mora decide quem a vê: ~/.claude/skills/<nome>/ vale para todos os seus projetos nesta máquina; .claude/skills/<nome>/, dentro do repositório, vai para o git e vale para a equipe. Com o mesmo nome em dois lugares, vence o da empresa, depois o pessoal, depois o do projeto (p. 61).

Os campos que mais importam

description: o que faz e quando usar. É o gatilho: o Claude lê só isso para decidir. Ponha o caso de uso principal primeiro, porque descrição e when_to_use somadas são cortadas em 1.536 caracteres (p. 62).
disable-model-invocation: true: só você chama. Use em toda ação com efeito colateral (publicar, enviar, apagar): você não quer o Claude publicando porque achou o código pronto.
allowed-tools: libera comandos sem pergunta só no turno em que a skill é chamada, sem restringir o resto.
argument-hint e $ARGUMENTS: /publicar 2.4.1 troca $ARGUMENTS por 2.4.1 no corpo (p. 63).
context: fork: roda a skill num subagente; o que ele lê fica na janela dele e volta só o resumo (p. 65).

Um cuidado de segurança: o allowed-tools de skill de projeto vale até num claude -p em pasta que você nunca marcou como confiável. Num repositório de terceiros, leia o .claude/skills/ antes de rodar (p. 63). E skill baixada de repositório no GitHub roda como você: leia antes de copiar.

As que já vêm prontas

O Claude Code traz skills embutidas, marcadas como Skill na referência de comandos: /run abre e opera o seu app, /verify constrói, roda e observa o resultado, /doctor checa instalação e configurações, e /update-config edita o settings.json certo a partir de uma frase sua (p. 64). Se você criar uma skill sua chamada verify, o Claude Code instrui o Claude a rodá-la logo antes de cada commit, menos em commit só de docs ou de testes (Claude Code 2.1.286 ou mais novo; a regra some se a skill tiver disable-model-invocation: true).

Disparar não é funcionar

Ver a skill disparar mostra que o Claude a achou, não que ela fez o que você queria. Faça 5 a 10 pedidos realistas, cada um numa sessão nova com a skill e de novo com ela desligada em .claude/settings.local.json ("skillOverrides": { "resumir-mudancas": "off" }), e compare: disparou quando devia, o resultado melhorou, quanto custou a mais (p. 66). Uma skill que dispara e não melhora o resultado só gasta janela. Grafia errada passa calada: na 2.1.301, disable-model-invocations, com s, passou no claude plugin validate --strict.