Tutorial de Claude Skills: Crie o Seu Primeiro SKILL.md em 10 Minutos (2026)

Tutorial de Claude Skills: Cria o Teu Primeiro SKILL.md em 10 Minutos (2026)

As Skills são a funcionalidade mais importante do Claude Code que provavelmente ainda não estás a usar. Uma Claude skill é uma pasta com um ficheiro SKILL.md que o Claude carrega automaticamente no momento em que o teu prompt corresponde à sua descrição — sem copiar e colar prompts, sem um CLAUDE.md inchado, sem teres de te lembrar de que template usar. Já publicámos 4 skills dentro da pasta .claude/skills/agent/ deste repositório, e com as Skills 2.0 e o Anthropic Marketplace a chegar no início de 2026, o formato finalmente atinge o seu potencial. Aqui está o padrão que funciona depois de ultrapassar as armadilhas.

Pontos-chave

• Uma Claude skill é uma pasta que contém um ficheiro SKILL.md com frontmatter YAML, que o Claude carrega automaticamente quando relevante.
• As Skills ficam em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto) — o Claude verifica ambas no arranque.
• Usa Skills para fluxos de trabalho repetíveis; usa MCP para dados externos em tempo real; usa subagents para planeamento em várias etapas; usa hooks para eventos determinísticos.
• O caminho mais rápido para a tua primeira skill é pedir ao Claude que invoque a sua própria skill skill-creator — ele escreve o SKILL.md por ti.

O Que São as Claude Skills?

Uma Claude skill é uma pasta que contém um ficheiro SKILL.md com frontmatter YAML (name, description, e opcionalmente allowed-tools), que o Claude Code carrega automaticamente para o contexto quando o teu prompt corresponde à descrição. As skills empacotam fluxos de trabalho reutilizáveis, como /commit ou /explain-code, sem incharem o teu system prompt.

Segundo a documentação oficial da Anthropic, cada pasta de skill tem três coisas: um SKILL.md obrigatório, scripts opcionais incluídos (desde um helper em Python até um ficheiro de configuração JSON), e documentação de referência opcional que é carregada juntamente com o corpo. É só isso. Sem passos de build, sem instalação, sem manifest.

O truque inteligente é a divulgação progressiva. No arranque, o Claude apenas analisa o campo description de cada skill. O corpo — instruções, exemplos, padrões de tool-call — fica em disco até que o teu prompt corresponda de facto. Assim, podes ter 50 skills instaladas e pagar zero custo em tokens até que uma seja acionada.

Pensa nas skills como receitas de um livro de culinária para as quais o Claude salta quando vê os ingredientes no teu prompt. Uma skill é uma pasta que o Claude lê a pedido, não um prompt que tens de te lembrar de colar. É essa toda a proposta.

Um SKILL.md minimalista tem este aspeto:

---
name: Summarize file
description: Use when the user asks for a 3-sentence summary of a file or function.
---

Read the file at $ARGUMENTS. Summarize purpose, key dependencies, and the
single most surprising thing about it. Three sentences max.

Dez linhas. Uma skill a sério. Pronta a disparar.

Início Rápido: Crie a Sua Primeira Skill em 10 Minutos

Para criar a sua primeira skill do Claude em 10 minutos: (1) crie ~/.claude/skills/explain-code/, (2) adicione um ficheiro SKILL.md com name, description e o corpo do fluxo de trabalho, (3) reinicie o Claude Code para que este analise o novo diretório, (4) acione-a com um prompt que corresponda à descrição.

Eis o fluxo completo.

Passo 1: Criar o diretório

mkdir -p ~/.claude/skills/explain-code

As skills pessoais (apenas para ti) ficam em ~/.claude/skills/. As skills de projeto (partilhadas via git com a tua equipa) ficam em .claude/skills/ na raiz do teu repositório. Escolhe pessoal para fluxos de trabalho do dia a dia; escolhe projeto quando quiseres que todos os contribuidores do repositório a herdem.

Passo 2: Escrever o SKILL.md

Coloque este ficheiro em ~/.claude/skills/explain-code/SKILL.md:

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
---

You are explaining code to a developer who is new to this codebase.

1. Read the file or snippet at $ARGUMENTS.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies or side effects.
5. End with one question the reader should ask before changing this code.

É esta a skill completa. O frontmatter é o contrato; o corpo é o guia de execução.

Passo 3: Reiniciar o Claude Code

A deteção em tempo real é uma funcionalidade do Skills 2.0 — as versões mais antigas do Claude Code precisam de um reinício para reconhecer o novo diretório. Se não tiver a certeza de qual versão está a usar, reiniciar uma vez não custa nada.

Passo 4: Ativá-lo

Abre um projeto e escreve:

walk me through what auth/middleware.ts does

O Claude compara o teu prompt com o campo description, encontra o explain-code e carrega silenciosamente o corpo do SKILL.md para o contexto. Vais ver "Using skill: explain-code" no registo de ferramentas. Feito.

Dica profissional: Não te apetece escrever o ficheiro tu mesmo? Abre o Claude Code e diz Use the skill-creator skill to scaffold an explain-code skill for me. O skill-creator incluído pela Anthropic é uma meta-skill que te faz perguntas, escolhe allowed-tools sensatas e escreve o SKILL.md na pasta certa. O caminho mais rápido para a tua primeira skill, ponto final.

É esta a promessa dos 10 minutos: cinco minutos a escrever, um reinício, um prompt de teste.

Dentro do SKILL.md: A referência do frontmatter

O frontmatter do SKILL.md é YAML envolvido em delimitadores ---. Dois campos são obrigatórios: name (≤64 caracteres, usado como nome do comando de barra) e description (o texto de ativação que o Claude compara com o seu prompt). Os campos opcionais controlam o acesso a ferramentas, a invocação de modelos, os globs de ficheiros e o contexto de execução.

Aqui está a referência completa, obtida a partir da documentação de skills da Anthropic:

A linha context: fork merece um destaque. É uma primitiva do Skills 2.0 que executa a skill dentro de uma janela de contexto isolada, útil para skills de investigação de longa duração ou qualquer coisa que produza muitos tokens intermédios que não quer a poluir o seu thread principal. Se é novo nesta ideia, o nosso guia de engenharia de contexto aborda as compensações. Um frontmatter maximalista de SKILL.md, com todos os campos preenchidos:

---
name: Deploy preview
description: Use when the user wants to deploy a preview build of the current branch to staging.
allowed-tools: ["Bash(git status:*)", "Bash(npm run build:*)", "Bash(vercel:*)"]
disable-model-invocation: true
user-invocable: true
argument-hint: <branch-name or 'current'>
model: claude-opus-4-7
context: fork
globs: ["package.json", "vercel.json"]
references: ["./deploy-runbook.md"]
bundled-files: ["./scripts/preflight.sh"]
tags: ["deploy", "vercel", "preview"]
---

Dica profissional: O maior erro de todos no description: escrevê-lo para humanos. Escreve-o para o Claude, frases-gatilho concretas, não copy de marketing. Mau: "Uma skill poderosa de automação de Git." Bom: "Usar quando o utilizador quiser fazer commit de alterações, escrever uma mensagem de commit ou abrir um PR."

Duas Competências Reais, de Ponta a Ponta

Dois padrões de competências cobrem 80% da utilização no mundo real: (1) uma competência /commit invocável pelo utilizador, com disable-model-invocation: true e allowed-tools: Bash(git *) para ações determinísticas; (2) uma competência /explain-code invocada automaticamente, com frontmatter predefinido, que o Claude aciona quando os prompts correspondem à sua descrição.

A maioria dos tutoriais mostra apenas excertos. Aqui estão dois ficheiros completos que pode copiar para ~/.claude/skills/ ainda hoje.

O skill /commit (invocável pelo utilizador)

---
name: Commit
description: Use when the user wants to stage and commit code changes with an AI-written conventional-commit message.
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git diff:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
---

1. Run `git status` and `git diff` to see what's staged and unstaged.
2. Group changes into one logical commit. If there are multiple unrelated
   changes, ask the user which to include.
3. Draft a Conventional Commits message: `type(scope): subject` (≤72 chars),
   blank line, body explaining *why*, not *what*.
4. Show the message to the user. Ask "Commit this?" Wait for explicit yes.
5. On confirmation, run `git add` for the included files and `git commit -m`.
6. Print the resulting commit hash.

Prompt de teste: /commit

O que acontece: O Claude inspeciona o estado do git, redige uma mensagem, pede-lhe confirmação e só depois executa git commit. O disable-model-invocation: true significa que nunca é acionado automaticamente por um prompt vago como "guarda as minhas alterações" — só é executado quando escreve /commit. A lista branca de allowed-tools restringe-o a subcomandos do git; é fisicamente impossível executar rm -rf ou fazer push para o remoto. Este é um skill que usamos em produção na nossa própria pipeline.

Para ações pós-commit determinísticas (executar o lint, regenerar tipos, notificar um webhook do Slack), utilize antes os hooks do Claude Code — os skills são probabilísticos, os hooks são acionados todas as vezes.

A skill /explain-code (invocável pelo modelo)

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
argument-hint: <file path or pasted snippet>
model: claude-opus-4-7
---

1. Read the file or snippet at $ARGUMENTS. If $ARGUMENTS is empty, ask
   the user which file to explain.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies, side effects, or hidden assumptions.
5. End with one question the reader should ask before modifying this code.

Prompt de teste: walk me through what auth/middleware.ts does

O que acontece: repare que o utilizador não escreveu /explain-code. O Claude faz a correspondência de "walk me through" com o campo description, encontra a skill e invoca-a automaticamente. É essa a magia — o description está a fazer o encaminhamento. O campo model: claude-opus-4-7 fixa esta skill ao Opus, independentemente do modelo que tenhas definido como predefinido, para que as análises aprofundadas de código usem sempre o modelo mais inteligente. (Mais sobre como executar o Claude Code com diferentes modelos.)

Porquê dois padrões? A Skill #1 é invocável pelo utilizador + limitada a ferramentas específicas — previsível, segura, perfeita para git ou deploys. A Skill #2 é invocada automaticamente + aberta — a magia das skills — mas confia no teu campo description. As skills invocáveis pelo utilizador dão-te previsibilidade; as skills invocáveis pelo modelo dão-te magia. Escolhe por skill, não por repositório.

Para mais exemplos reais de skills, consulta o repositório oficial anthropics/skills e a lista mantida pela comunidade awesome-claude-skills.

Skills vs. MCP vs. Subagents vs. Hooks: Quando Usar Cada Um

Usa Skills para fluxos de trabalho reutilizáveis que o Claude deve acionar automaticamente ou que invocas como comandos de barra. Usa servidores MCP quando precisas de dados externos em tempo real (bases de dados, APIs, sistemas de ficheiros fora do diretório de trabalho). Usa subagents para planos multi-etapa que o Claude deve delegar a um contexto novo. Usa hooks para eventos determinísticos (pre-commit, post-tool-use) que devem disparar sempre, nunca de forma probabilística.

Enquadramento rápido: skills são fluxos de trabalho, o Model Context Protocol são dados, subagents são planos, hooks são eventos. Cada um vive numa camada diferente do Claude Code, e a camada errada é a ferramenta errada. Segundo o próprio artigo da Anthropic, Skills explained, é este o enquadramento que querem que interiorizes.

Combinam-se entre si. Uma skill pode chamar uma ferramenta MCP através de allowed-tools. Um hook pode disparar depois de uma skill terminar. Um subagent pode usar skills às quais lhe foi dado acesso. O modelo mental mais limpo: escolhe primeiro a camada certa, depois deixa-as empilhar. Skills são a primitiva de engenharia de contexto a que recorres quando queres um fluxo de trabalho que o Claude possa escolher; automatizas com hooks quando queres algo que o Claude não possa saltar. A pior forma de usar incorretamente cada um: Skills para dados em tempo real (use MCP); MCP para modelos de prompt de utilização única (use Skills); subagentes para edições de ficheiros determinísticas (use hooks); hooks para lógica de ramificação (use Skills). Skills são fluxos de trabalho, MCP são dados, subagentes são planos, hooks são eventos. Escolha pela camada, não pela palavra da moda.

Onde vivem as Skills: Pessoal, Projeto, Plugin, Enterprise

As skills do Claude instalam-se em quatro âmbitos: pessoal (~/.claude/skills/, apenas tu), projeto (.claude/skills/ na raiz do repositório, a tua equipa via git), plugin (distribuído através do Anthropic Marketplace ou de qualquer URL de plugin) e enterprise (empurrado pela equipa de TI através de MDM/política de administração). O Claude analisa os quatro no arranque.

As skills de documentos integradas são fáceis de esquecer — o Claude Code já traz as skills pdf, docx, pptx e xlsx de fábrica, além de uma pequena biblioteca de /debug, /simplify e similares. (A ferramenta irmã Claude Design traz as suas próprias skills de fluxo de trabalho integradas para geração de design; o mesmo modelo, um domínio diferente.)

Quando deves distribuir via plugin em vez de projeto? Os plugins ganham quando o mesmo fluxo de trabalho beneficia vários repositórios — uma skill /release que uses em cinco codebases de clientes pertence a um plugin, não copiada e colada na .claude/skills/ de cada repositório. As skills de projeto ganham para convenções específicas do codebase (o template de PR da tua equipa, o teu test runner personalizado). O Anthropic Marketplace, juntamente com o /plugin install a partir de qualquer URL, torna os plugins a resposta certa para a reutilização entre repositórios. Segundo a documentação de plugins, a descoberta e as atualizações são tratadas automaticamente.

Padrões Avançados: $ARGUMENTS, Injeção Dinâmica de Shell, context: fork

Três padrões avançados de skills são os mais relevantes: $ARGUMENTS permite que os utilizadores passem parâmetros para skills invocáveis pelo utilizador (/translate $ARGUMENTS); a injeção dinâmica de shell (com allowed-tools: Bash(...)) permite que uma skill execute scripts e canalize a saída para o contexto; e context: fork (Skills 2.0) executa a skill numa janela de contexto isolada. O whitepaper Complete Guide da Anthropic é a referência canónica para context: fork desde maio de 2026.

$ARGUMENTS para skills parametrizadas

---
name: Translate
description: Translate the most recent message into the target language.
user-invocable: true
argument-hint: <target-language, e.g. spanish, japanese, brazilian portuguese>
---

Translate the user's previous message into $ARGUMENTS. Preserve tone,
preserve markdown formatting, return only the translation.

Prompt de teste: /translate spanish. O Claude substitui spanish por $ARGUMENTS em tempo de execução. A forma mais simples de tornar uma skill multiúso sem escrever variantes.

Injeção dinâmica de shell via allowed-tools

---
name: Review last commit
description: Use when the user wants a code review of the last git commit.
allowed-tools: ["Bash(git diff HEAD~1:*)", "Bash(git log -1:*)"]
---

Run `git diff HEAD~1` and `git log -1`. Review the diff for bugs, security
issues, and style violations. Output a 5-bullet review.

A skill executa comandos de shell, canaliza o diff para o contexto e revê-o. Fixe o allowed-tools em comandos específicos (Bash(git diff HEAD~1:*)), nunca em Bash simples — a permissão de Bash simples é a versão com armadilha de segurança deste padrão.

context: fork (Skills 2.0)

---
name: Deep research
description: Use when the user wants a multi-source research summary on a topic.
context: fork
---

Research the topic in $ARGUMENTS using available web tools. Produce a
2-page summary with citations. Do not pollute the main thread.

Ao fazer fork, a skill passa a ter a sua própria janela de contexto, para que os 50K tokens de notas de investigação intermédias não contaminem a sua sessão principal. Útil para investigações longas, planeamento de refatorações de grande escala ou qualquer tarefa que produza muitos tokens descartáveis. Apenas em Skills 2.0 — as versões mais antigas do Claude Code ignoram o campo.

Resolução de problemas: Porque é que a sua Skill não está a ser acionada

Normalmente, as skills falham a ativação por uma de quatro razões: (1) a description é demasiado genérica para o Claude a conseguir associar ao seu prompt, (2) o diretório está no caminho errado (.claude/skills/ e não claude/skills/), (3) o Claude Code não foi reiniciado depois de a skill ter sido adicionada (apenas em versões anteriores ao Skills 2.0) ou (4) o nome da skill entra em conflito com uma skill integrada ou de prioridade mais elevada. Segundo os modos de falha mais pesquisados no Google no registo de issues do Claude Code no GitHub, estes quatro cobrem cerca de 95% dos relatos de «porque é que isto não está a funcionar».

Modo de falha 1: "A minha skill não aparece de todo"

A causa número um é um caminho errado: .claude/skills/ (com o ponto) versus claude/skills/ (sem ponto) é um erro que todos nós já cometemos à 1 da manhã. Executa ls -la ~/.claude/skills/ para confirmar que o diretório existe com o ponto. Se estiver lá e o Claude continuar sem o detetar, reinicia o Claude Code uma vez. As versões anteriores ao Skills 2.0 só fazem a verificação no arranque.

Modo de falha 2: "O Claude não está a invocar automaticamente o meu skill"

O campo description é demasiado vago ou está escrito para humanos, não para o Claude. Reescreve-o com frases de ativação concretas que espelhem a forma como os utilizadores realmente formulam os pedidos. Depois de criar 4 skills para este repositório, a rasteira em que caí foi deixar descrições como "Um skill útil para SEO." Inútil. Reescreve para: "Usa quando o utilizador quiser adicionar schema JSON-LD, meta tags ou frontmatter de SEO a um artigo em Markdown." A precisão de ativação passou de ~30% para ~95%. A precisão de ativação decide-se no campo description. Escreve-o para o Claude, não para o teu currículo.

Modo de falha 3: "A descrição foi truncada na paleta de comandos slash"

Ou a sua description tem mais de 1024 caracteres, ou o seu name tem mais de 64 caracteres. Ambos têm limites rígidos. Solução: divida o skill em dois skills mais específicos, ou mova os detalhes extensos para o corpo do SKILL.md. O frontmatter serve para encaminhamento, não para documentação.

Modo de falha 4: "A deteção de alterações em tempo real não está a funcionar"

O Claude Code anterior ao Skills 2.0 requer um reinício completo após qualquer edição ao SKILL.md. Se está a iterar numa skill e as suas alterações não estão a surtir efeito, provavelmente está a usar uma versão mais antiga. Ou atualize para uma versão do Claude Code que inclua o Skills 2.0 (deteção em tempo real) ou habitue-se a reiniciar após cada gravação. É irritante, mas barato.

Competências para além do Claude: O padrão aberto Agent Skills

Sim, as skills são um padrão aberto. O padrão Agent Skills em agentskills.io define o formato SKILL.md de forma independente de qualquer fornecedor. O Codex CLI da OpenAI e o ChatGPT Desktop adotaram o padrão em dezembro de 2025; o mesmo SKILL.md que escreves para o Claude Code funciona no Codex com pequenos ajustes ao frontmatter.

Aqui está a matriz de suporte entre ferramentas à data de maio de 2026: o Claude Code tem suporte total de Agent Skills (a implementação de referência). O Codex CLI da OpenAI tem suporte total. O ChatGPT Desktop tem suporte parcial — name, description e o corpo funcionam, mas a paridade do allowed-tools ainda não está lá. O Gemini CLI anunciou suporte no início de 2026, mas ainda não o tinha lançado à data de escrita deste artigo. O Cursor é a exceção — usa o seu próprio formato de Cursor rules e não lê nativamente o SKILL.md, embora existam shims da comunidade.

O que escrever hoje para que as tuas skills sobrevivam ao ano: mantém o name e a description limpos e agnósticos em relação à ferramenta. Isola qualquer frontmatter específico de um fornecedor atrás de um namespace (claude: ou codex:) se quiseres ser multi-ferramenta. A superfície portável — name, description, corpo, $ARGUMENTS — funciona em todo o lado; campos avançados como context: fork são específicos do Claude até que outros fornecedores lancem equivalentes. A Anthropic está também a apostar numa integração mais profunda com o marketplace, de acordo com o roadmap do Claude Code que foi divulgado, pelo que a portabilidade só vai ficar mais fácil.

Os três sítios onde procurar exemplos de skills: anthropics/skills (oficial), awesome-claude-skills (comunidade) e agentskills.io (a página da especificação do padrão). As skills já não são uma funcionalidade do Claude. São um padrão aberto que o Claude lançou primeiro.

Perguntas Frequentes

Qual é a diferença entre um skill do Claude e um servidor MCP?

Um skill do Claude é um ficheiro SKILL.md com instruções de fluxo de trabalho que o Claude carrega quando o seu prompt corresponde à descrição desse skill. Um servidor MCP é um processo separado que o Claude invoca para obter dados em tempo real (bases de dados, APIs, sistemas de ficheiros fora do diretório de trabalho). Use Skills para fluxos de trabalho; use MCP para dados. Podem combinar-se: os skills podem invocar ferramentas MCP.

As skills do Claude são gratuitas?

Sim, as Skills são uma funcionalidade integrada do Claude Code, sem custos adicionais. Paga apenas pelos tokens do modelo consumidos quando uma skill é executada. As skills que instalar a partir do Anthropic Marketplace podem ser pagas (raro atualmente), mas o repositório oficial anthropics/skills e as awesome-lists da comunidade são totalmente gratuitos para copiar e utilizar.

Onde são instaladas as skills do Claude?

As skills pessoais ficam em ~/.claude/skills/{skill-name}/, e as skills de projeto em .claude/skills/{skill-name}/ na raiz do teu repositório. As skills de plugin são instaladas através de /plugin install <url> e ficam no teu diretório de plugins. As skills empresariais são distribuídas pelos TI da tua organização através das definições geridas. O Claude Code analisa os quatro âmbitos no arranque.

Como crio uma skill do Claude do zero?

Cria uma pasta em ~/.claude/skills/, adiciona um ficheiro SKILL.md com frontmatter YAML (name, description) seguido das instruções do workflow e reinicia o Claude Code. O caminho mais rápido: abre o Claude Code e pede-lhe para invocar a skill skill-creator incluída — ele gera a estrutura do SKILL.md por ti em menos de um minuto.

Porque é que a minha skill do Claude não é ativada?

As quatro causas mais comuns: (1) a description é demasiado vaga para o Claude a associar ao teu prompt — reescreve-a com frases de ativação concretas; (2) a skill está no caminho errado (.claude/skills/ e não claude/skills/); (3) o Claude Code precisa de ser reiniciado em versões anteriores ao Skills 2.0; (4) o nome da skill entra em conflito com uma skill incluída. Verifica com ls -la ~/.claude/skills/.

O ChatGPT ou o Cursor conseguem usar as skills do Claude?

O ChatGPT Desktop e o Codex CLI suportam o mesmo padrão Agent Skills que o Claude, o mesmo SKILL.md funciona em ambos com pequenas alterações no frontmatter. O Cursor usa o seu próprio formato de Cursor rules e não lê nativamente o SKILL.md. O Gemini CLI anunciou o suporte no início de 2026, mas ainda não o tinha lançado em maio de 2026.

O que é a skill skill-creator?

A skill-creator é uma meta-skill incluída no repositório anthropics/skills que ajuda o Claude a escrever novos ficheiros SKILL.md por ti. Diz ao Claude o que queres que a skill faça; a skill-creator entrevista-te para obter a descrição, escolhe allowed-tools sensatas e escreve o SKILL.md na pasta certa. O scaffold mais rápido possível.

O que faz o disable-model-invocation?

Definir disable-model-invocation: true no frontmatter da sua skill impede o Claude de acionar automaticamente a skill com base na correspondência de prompts. A skill passa a poder ser invocada apenas pelo utilizador: aparece na paleta de comandos de barra como /skill-name e só é executada quando chamada explicitamente. Utilize-o para ações destrutivas ou determinísticas, como /commit ou /deploy.

Crie algumas skills, lance-as num projeto e veja o que resulta. Se a sua equipa se estiver a deparar com o conjunto de armadilhas de "a skill não é acionada" em vários repositórios e quiser um segundo par de olhos sobre a configuração de .claude/skills/, contacte-nos — terei todo o gosto em analisar a situação.