Desde 1 de setembro de 2026, com o lançamento do Claude Fable 5.1 e do Claude Mythos 5.1, a Anthropic tem vindo a empurrar as Claude Skills para o centro do fluxo de trabalho de quem programa com IA. A ideia é simples: em vez de repetir instruções longas em cada conversa, empacotas esse conhecimento numa pasta com um ficheiro SKILL.md e o Claude passa a carregá-lo sozinho quando faz sentido. Só a palavra-chave “claude skills” já soma cerca de 1.000 pesquisas mensais em Portugal, segundo dados do DataForSEO recolhidos em setembro de 2026, um sinal de que muita gente ainda não sabe bem como isto funciona na prática.

Este tutorial mostra, passo a passo, como criar uma Claude Skill do zero, testá-la no Claude Code e num projeto real, e evitar os erros mais comuns de quem experimenta isto pela primeira vez. Vais precisar de cerca de 60 minutos, uma conta Claude (qualquer plano serve) e alguma familiaridade básica com a linha de comandos.

O Que São as Claude Skills e Porque Importam

Uma Claude Skill é, na prática, uma pasta com um ficheiro de instruções chamado SKILL.md e, opcionalmente, scripts ou documentos de apoio. A Anthropic descreve-a como “a set of instructions – packaged as a simple folder – that teaches Claude how to handle specific tasks or workflows”, segundo o guia oficial de construção de skills. Na prática portuguesa, isto resolve um problema muito concreto: equipas que colam o mesmo checklist de code review, o mesmo template de relatório ou as mesmas normas de estilo em cada nova conversa com o Claude.

O funcionamento assenta em duas camadas. A primeira é o campo description do frontmatter, que fica sempre disponível no contexto do Claude e serve para decidir quando ativar a skill. A segunda é o corpo do ficheiro em Markdown, que só é carregado quando a skill é mesmo invocada, poupando tokens nas conversas onde não é precisa. No anúncio oficial das skills, a Anthropic resume isto de forma direta: “Skills are folders that include instructions, scripts, and resources that Claude can load when needed”.

As skills estão disponíveis nos planos Free, Pro, Max, Team e Enterprise do Claude.ai, e em beta através da ferramenta de execução de código na API, de acordo com a documentação de suporte da Anthropic. Também funcionam no Claude Code, a ferramenta de linha de comandos, com uma sintaxe ligeiramente mais rica que inclui campos exclusivos como allowed-tools ou context: fork, que vamos usar mais à frente neste tutorial.

Vale a pena situar isto no contexto mais amplo de 2026. A Anthropic lançou o Claude Fable 5.1 a 1 de setembro com um corte de 75% no preço de leitura em cache, de 1,00 para 0,25 dólares por milhão de tokens, segundo trackers do mercado como o Digital Applied. Esse detalhe é relevante para quem cria skills: como o corpo de uma skill carrega repetidamente para o contexto sempre que é invocada, beneficia diretamente de caching mais barato. Numa equipa que usa a mesma skill de revisão de código dezenas de vezes por dia, a diferença no custo mensal é sentida.

Skills vs MCP vs Prompts Personalizados: Qual a Diferença

É fácil confundir Claude Skills com o Model Context Protocol (MCP), mas resolvem problemas diferentes. O MCP liga o Claude a ferramentas e fontes de dados externas, como uma base de dados ou uma API de terceiros. Uma skill, por outro lado, não liga nada a nada: ensina o Claude a fazer melhor uma tarefa que já sabe fazer, usando conhecimento específico que tu escreves. Podes combinar os dois: uma skill que instrui o Claude a usar um servidor MCP de forma correta é uma prática comum em equipas que já têm integrações configuradas.

Comparado com colar um prompt longo em cada conversa, uma skill tem três vantagens práticas: fica disponível automaticamente sem copiar e colar, pode incluir scripts executáveis em Python ou Node.js, e é partilhável com a equipa inteira através de uma pasta de projeto ou de um plugin. A tabela seguinte resume as diferenças principais.

CaraterísticaClaude SkillMCPPrompt colado manualmente
Invocação automáticaSim, via campo descriptionNão aplicável (ferramenta)Não, requer cópia manual
Reutilização entre conversasSim, persiste na pastaSim, persiste na configuraçãoNão, perde-se a cada sessão
Pode executar scriptsSim (Python, Node.js)Sim, via servidor externoNão
Liga a sistemas externosSó através de MCP associadoSim, essa é a função principalNão
Partilhável em equipaSim (pasta, zip ou plugin)Sim (configuração de servidor)Só copiando texto

Pré-Requisitos: Contas, Versões e Ferramentas

Antes de avançar, confirma que tens tudo preparado. Não precisas de nenhuma versão paga para começar: o plano gratuito do Claude.ai já permite criar e testar skills, embora com limites de utilização mais apertados do que os planos Pro ou Team.

RequisitoVersão mínima recomendadaOnde obter
Conta Claude.aiFree, Pro, Max, Team ou Enterpriseclaude.ai
Claude Code (opcional, mas recomendado)Versão atual disponível via npmcode.claude.com
Node.js (para scripts JavaScript)18 LTS ou superiornodejs.org
Python (para scripts Python)3.8 ou superiorpython.org
Editor de textoQualquer um com suporte a MarkdownVS Code, JetBrains, etc.
Execução de código ativaLigada nas definições do Claude.aiCustomize > Skills

Um ponto que costuma gerar dúvidas: a funcionalidade de skills no Claude.ai exige que a execução de código esteja ativada nas definições da conta, algo que a documentação de suporte sublinha explicitamente. Sem isso, o menu de skills nem sequer aparece na interface. Vale a pena confirmar isto antes de perder tempo a escrever uma skill que depois não consegues carregar.

Passo 1: Cria a Estrutura de Pastas da Skill

Tudo começa numa pasta com o nome da skill. Se vais usar o Claude Code, a localização determina o alcance: uma skill pessoal fica em ~/.claude/skills/ e está disponível em todos os projetos da tua máquina, enquanto uma skill de projeto fica em .claude/skills/ dentro do repositório e só é carregada nesse contexto. Cria a pasta e o ficheiro principal assim:

mkdir -p ~/.claude/skills/revisao-codigo
cd ~/.claude/skills/revisao-codigo
touch SKILL.md
mkdir scripts referencias

O nome da pasta importa: se não definires um campo name no frontmatter, o Claude Code usa o nome da diretoria como identificador do comando (por exemplo, /revisao-codigo). Em monorepos, uma skill dentro de apps/web/.claude/skills/deploy/ só carrega quando trabalhas nessa subpasta, e se houver conflito de nomes com uma skill de nível superior, o Claude Code resolve automaticamente para /apps/web:deploy.

Passo 2: Escreve o Frontmatter YAML

O frontmatter é o bloco de metadados entre duas linhas --- no topo do ficheiro. É fundamental que a primeira linha do ficheiro seja exatamente ---, sem espaços antes, caso contrário o Claude Code trata o ficheiro inteiro como conteúdo em vez de reconhecer os metadados. Um frontmatter mínimo tem apenas dois campos:

---
name: revisao-codigo
description: Revê pull requests em Node.js e TypeScript, verificando erros comuns, práticas de segurança e estilo de código
---

# Revisão de Código

Quando pedires para rever código, segue o checklist abaixo...

Existem mais de quinze campos possíveis no frontmatter do Claude Code, desde controlo de invocação até integração com subagentes. Vais conhecer os mais úteis ao longo deste tutorial, mas a tabela seguinte serve de referência rápida para os campos que provavelmente vais usar num projeto real.

CampoTipoPara que serve
nametextoNome apresentado nas listagens (por omissão, usa o nome da pasta)
descriptiontextoExplica quando usar a skill, o Claude usa isto para a invocar sozinho
disable-model-invocationbooleanoSe true, só tu podes invocar a skill manualmente
user-invocablebooleanoSe false, fica escondida do menu “/” e só o Claude a pode chamar
allowed-toolstexto ou listaPré-aprova ferramentas específicas durante a execução da skill
argument-hinttextoSugestão de autocompletar, por exemplo [numero-issue]
contexttextoDefine “fork” para correr a skill num subagente isolado
modeltextoSubstitui o modelo da sessão só para esta skill

Passo 3: Define uma Descrição que Ative a Invocação Automática

O campo description é, na prática, a parte mais importante de toda a skill. É o único elemento que fica sempre presente no contexto do Claude, por isso é ele que decide se a skill é ou não convocada para uma determinada tarefa. No Claude.ai, este campo tem um limite de 200 carateres, segundo a documentação de suporte, e deve responder claramente a uma pergunta: “quando é que esta skill deve ser usada?”

Descrições vagas como “Ajuda com código” quase nunca disparam a invocação automática, porque o Claude não tem forma de perceber se se aplicam à conversa atual. Compara os dois exemplos:

  • Fraca: “Skill para programação”
  • Forte: “Revê pull requests em Node.js e TypeScript antes do merge, verificando injeção SQL, gestão de erros e cobertura de testes”

No Claude Code existe ainda um campo adicional, when_to_use, que é concatenado à descrição e permite dar mais contexto sem sobrecarregar o campo principal. Usa-o quando a lógica de ativação depende de várias condições, por exemplo “usa isto apenas em ficheiros dentro de src/api/ que alterem rotas HTTP”.

Passo 4: Escreve as Instruções em Markdown

Depois do frontmatter, tudo o que escreveres é o corpo da skill, que só carrega para o contexto quando ela é invocada. A Anthropic recomenda manter o SKILL.md com menos de 500 linhas e mover o detalhe técnico para ficheiros de apoio. A razão é simples: cada linha do ficheiro é um custo recorrente de tokens, e um documento inchado torna a skill mais lenta e mais cara de usar sem trazer benefício proporcional.

---
name: revisao-codigo
description: Revê pull requests em Node.js e TypeScript antes do merge
---

# Revisão de Código

Ao rever um pull request, segue esta ordem:

1. Confirma que não há segredos (chaves de API, palavras-passe) no diff
2. Verifica se as rotas HTTP validam entrada do utilizador
3. Confirma que erros assíncronos têm tratamento com try/catch
4. Sinaliza funções com mais de 60 linhas para possível refactor
5. Confirma que existem testes novos para a lógica alterada

Usa um tom direto e aponta o número da linha em cada observação.
Consulta referencias/checklist-seguranca.md para a lista completa
de padrões de vulnerabilidade a verificar.

Nota o último parágrafo: em vez de meter o checklist de segurança inteiro dentro do ficheiro principal, o texto aponta para um ficheiro de referência separado. É essa divisão entre instrução curta e detalhe profundo que mantém a skill eficiente.

Passo 5: Adiciona Ficheiros de Referência e Scripts Auxiliares

Uma skill pode incluir mais do que o SKILL.md. Ficheiros Markdown adicionais funcionam como um “segundo nível de detalhe” que o Claude só consulta se precisar, e scripts em Python ou Node.js podem ser executados diretamente. No plano API, os pacotes têm de estar pré-instalados, porque as skills nesse contexto não instalam dependências em tempo de execução. No Claude.ai, é possível instalar pacotes de repositórios como PyPI ou npm ao carregar a skill.

revisao-codigo/
├── SKILL.md
├── referencias/
│   └── checklist-seguranca.md
└── scripts/
    └── contar_complexidade.py

Um exemplo prático de script auxiliar: um pequeno programa Python que conta a complexidade ciclomática de um ficheiro e devolve um número que o Claude depois interpreta e comenta.

#!/usr/bin/env python3
import sys, re

def contar_complexidade(caminho):
    with open(caminho) as f:
        codigo = f.read()
    pontos = len(re.findall(r"\bif\b|\bfor\b|\bwhile\b|\bcatch\b", codigo))
    return pontos + 1

if __name__ == "__main__":
    resultado = contar_complexidade(sys.argv[1])
    print(f"Complexidade estimada: {resultado}")

Passo 6: Testa a Skill no Claude Code

Com a estrutura pronta, abre o Claude Code dentro de um repositório de teste e confirma que a skill aparece. As alterações ao SKILL.md são detetadas dentro da mesma sessão, o que facilita muito a iteração, exceto em modo “bare”, onde a monitorização de pastas fica desativada.

$ claude
> /revisao-codigo
Carregando skill "revisao-codigo"...
Skill ativa. A analisar as alterações do diretório atual.

Se preferires testar a invocação automática em vez da manual, escreve uma pergunta que corresponda à descrição da skill, sem usar o comando “/”, e confirma nos registos da conversa se o Claude decidiu carregá-la sozinho. Este é o teste mais importante, porque é o comportamento que a maioria dos utilizadores finais vai encontrar no dia a dia.

Passo 7: Configura allowed-tools e Permissões

Por omissão, sempre que uma skill tenta executar um comando de terminal, o Claude Code pede confirmação. Para skills de uso repetido e já validadas, o campo allowed-tools pré-aprova comandos específicos, evitando interrupções constantes.

---
name: commit-rapido
description: Junta e faz commit de alterações com mensagem gerada automaticamente
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Analisa as alterações pendentes com git status e git diff,
escreve uma mensagem de commit curta e objetiva, e regista-a.

A sintaxe distingue correspondência exata de correspondência por prefixo: Bash(git commit *) aceita qualquer argumento depois de “git commit”, enquanto Bash(git status) sem asterisco só aceita o comando exato. A aprovação concedida por uma skill expira assim que envias a próxima mensagem, por isso não fica permanentemente aberta.

Passo 8: Injeta Contexto Dinâmico com Comandos de Shell

Uma das funcionalidades mais úteis do Claude Code é a possibilidade de correr comandos de shell antes de enviar o conteúdo ao Claude, substituindo o resultado diretamente no texto da skill. Isto poupa um passo manual e garante que o Claude trabalha sempre com dados atuais.

---
name: resumo-alteracoes
description: Resume as alterações por commitar no repositório atual
---

## Alterações atuais

!`git diff HEAD`

## Instruções

Resume as alterações acima em três frases, indicando
os ficheiros mais afetados e possíveis riscos de regressão.

Se o comando falhar com um código de saída diferente de zero, a skill inteira é abortada, o que evita que o Claude trabalhe com dados incompletos. Esta injeção fica desativada em skills sincronizadas a partir do claude.ai, por razões de segurança, e pode também ser bloqueada por política através da definição disableSkillShellExecution.

Passo 9: Cria Argumentos Nomeados para Invocação Direta

Quando queres que a skill funcione mais como um comando parametrizado do que como uma sugestão automática, o campo arguments permite definir posições nomeadas que substituem variáveis no texto.

---
name: corrigir-issue
description: Corrige uma issue do GitHub identificada pelo número
disable-model-invocation: true
arguments: [numero-issue]
---

Corrige a issue #$numero-issue do GitHub:

1. Lê a descrição da issue com gh issue view $numero-issue
2. Implementa a correção
3. Escreve testes para o caso corrigido
4. Cria um commit referenciando a issue

Repara no campo disable-model-invocation: true: como corrigir uma issue é uma ação com impacto real no repositório, faz sentido impedir que o Claude a dispare sozinho e exigir sempre um comando explícito, neste caso /corrigir-issue 482.

Passo 10: Isola Tarefas Pesadas com context: fork

Para tarefas de investigação longas, como explorar um repositório inteiro à procura de um padrão, vale a pena correr a skill num subagente isolado em vez de poluir a conversa principal com dezenas de resultados intermédios. É para isso que serve o campo context: fork, combinado com agent para escolher o tipo de subagente.

---
name: investigar-padrao
description: Investiga em profundidade onde um padrão de código aparece no repositório
context: fork
agent: Explore
background: false
---

Investiga $ARGUMENTS no repositório:
1. Usa Glob e Grep para localizar ocorrências
2. Analisa o código encontrado
3. Devolve uma lista com ficheiro, linha e explicação

Com background: false, a conversa principal espera pelo resultado do subagente antes de continuar. Deixando o valor por omissão, true, a skill corre em segundo plano e o Claude pode continuar a responder a outras perguntas entretanto, o que é mais rápido mas exige um pouco mais de atenção ao que está a decorrer.

Passo 11: Publica e Partilha a Skill com a Equipa

Há três formas principais de partilhar uma skill. A primeira é através do próprio repositório, com uma pasta .claude/skills/ versionada no Git a chegar automaticamente a toda a equipa que clonar o projeto. A segunda é através de um plugin do Claude Code, útil quando a skill não está ligada a um único repositório. A terceira é carregar um ficheiro zip diretamente na interface do claude.ai, em Customize > Skills, para uso pessoal ou, em contas Team e Enterprise, para toda a organização.

Um detalhe que trava muitos utilizadores: ao carregar uma skill para o claude.ai, só os campos definidos na especificação aberta Agent Skills são aceites (name, description, license, compatibility, metadata e allowed-tools). Campos exclusivos do Claude Code, como context ou hooks, provocam um erro “Unexpected key” na importação. Se pretendes que a skill funcione nos dois ambientes, mantém-na dentro do subconjunto compatível ou cria duas versões.

Passo 12: Projeto Completo – Skill de Revisão de Código

Para fechar o tutorial, junta tudo o que viste num projeto funcional: uma skill de revisão de código pronta a usar num repositório Node.js. A estrutura final fica assim.

.claude/skills/revisao-codigo/
├── SKILL.md
├── referencias/
│   └── checklist-seguranca.md
└── scripts/
    └── contar_complexidade.py
---
name: revisao-codigo
description: Revê pull requests em Node.js e TypeScript, verificando segurança, tratamento de erros e cobertura de testes antes do merge
allowed-tools: Bash(git diff *) Bash(git log *) Bash(node scripts/*)
---

# Revisão de Código

## Alterações a rever

!`git diff main...HEAD`

## Checklist

1. Confirma que não há segredos expostos no diff
2. Verifica validação de entrada em rotas HTTP novas ou alteradas
3. Confirma tratamento de erros em código assíncrono
4. Sinaliza funções com mais de 60 linhas
5. Confirma que existem testes para a lógica alterada
6. Corre `node scripts/contar_complexidade.py ` em
   ficheiros com mais de 200 linhas e comenta o resultado

Consulta referencias/checklist-seguranca.md para os padrões
de vulnerabilidade completos antes de aprovar o pull request.
Aponta sempre o número da linha em cada observação.

Guarda isto dentro de um repositório de teste, faz um commit com uma alteração propositadamente insegura (por exemplo, uma rota sem validação de entrada) e pede ao Claude Code para rever o pull request sem invocar a skill manualmente. Se a descrição estiver bem escrita, o Claude deteta o contexto e carrega a skill sozinho, sinalizando o problema com o número da linha exato.

Exemplo de Resultado: o que o Claude Devolve

Depois de correres a skill de revisão de código do Passo 12 contra um pull request com uma rota sem validação de entrada, o resultado típico do Claude Code tem este aspeto. Repara como a resposta segue à risca a ordem definida no checklist e aponta sempre o ficheiro e a linha, exatamente como pedido nas instruções da skill.

Skill "revisao-codigo" carregada automaticamente.

Revisão do pull request #128:

1. Segredos expostos: nenhum encontrado.
2. Validação de entrada: FALHA em src/routes/pagamento.js:34
   O corpo do pedido é usado diretamente na query sem
   sanitização. Sugestão: adicionar validação com Zod ou Joi
   antes de construir a query.
3. Tratamento de erros assíncronos: OK em todos os ficheiros
   alterados.
4. Funções longas: src/routes/pagamento.js:12-89 tem 77 linhas.
   Considerar dividir em funções mais pequenas.
5. Testes: não existem testes novos para a rota alterada.

Complexidade estimada (scripts/contar_complexidade.py):
pagamento.js: 14

Recomendação: não aprovar o merge até o ponto 2 ser corrigido
e existirem testes para o novo comportamento.

Este tipo de resultado estruturado, com número de ficheiro e linha em cada observação, é o que distingue uma skill bem escrita de um prompt genérico. Se a tua skill devolver respostas vagas sem referências concretas ao código, o problema está quase sempre nas instruções do SKILL.md, não no modelo em si.

Segurança: Como Auditar uma Skill Antes de Ativar

Como uma skill corre com as mesmas permissões da tua sessão, instalar uma sem a rever é comparável a correr um pacote npm desconhecido em produção. Antes de ativares uma skill descarregada de um repositório público ou partilhada por outra equipa, vale a pena seguir um pequeno processo de auditoria.

  • Lê o SKILL.md por completo, incluindo qualquer bloco de comando injetado com !`comando`, que corre automaticamente assim que a skill é carregada.
  • Confirma que nenhum ficheiro de referência ou script contém chaves de API, tokens ou credenciais escritas em texto simples.
  • Revê o campo allowed-tools e pergunta-te se cada comando pré-aprovado é mesmo necessário para a tarefa descrita. Um comando Bash(*) genérico numa skill de “resumo de texto” é um sinal de alerta.
  • Verifica se scripts em Python ou Node.js fazem pedidos de rede para domínios que não reconheces, sobretudo em skills descarregadas de fontes não oficiais.
  • Prefere skills com disable-model-invocation: true para qualquer ação irreversível (apagar ficheiros, fazer deploy, enviar mensagens), para garantires que só correm quando as invocas explicitamente.

Este cuidado ganhou relevância prática depois de casos como o GitSpawn, que expôs oito falhas em configurações de agentes de IA no Claude Code e no Cursor. A lição para quem gere infraestrutura em Portugal é a mesma que já se aplica a extensões de navegador ou dependências de projeto: qualquer coisa que execute código com as tuas permissões merece revisão antes de entrar no fluxo de trabalho de produção.

Erros Comuns ao Criar Claude Skills

  • Descrição vaga: frases genéricas como “ajuda com o código” quase nunca disparam a invocação automática porque não dão ao Claude nenhum sinal de contexto.
  • SKILL.md demasiado longo: ficheiros com milhares de linhas encarecem cada invocação e tornam a skill mais lenta a carregar. Move detalhe para ficheiros de referência.
  • Esquecer o “—” na primeira linha: se a primeira linha do ficheiro não for exatamente três traços, o frontmatter inteiro é ignorado e tratado como texto normal.
  • Credenciais escritas na skill: a documentação de suporte é direta sobre isto, nunca escrevas chaves de API ou palavras-passe dentro do ficheiro. Usa integrações MCP para acesso a serviços externos.
  • Confundir pasta pessoal com pasta de projeto: guardar em ~/.claude/skills/ quando querias que a skill ficasse só no repositório (e vice-versa) é um erro frequente que faz a skill “desaparecer” ou “aparecer a mais”.
  • Não rever skills de terceiros antes de ativar: instalar uma skill descarregada sem ler o conteúdo é equivalente a correr um script desconhecido com acesso ao teu ambiente.
  • Nomes de skills em conflito: em monorepos com várias pastas .claude/skills/, nomes repetidos obrigam a invocações mais longas como /apps/web:deploy, o que confunde quem não sabe da regra.

Resolução de Problemas: 10 Situações Frequentes

1. A skill não aparece no menu “/”. Confirma que user-invocable não está definido como false e que a pasta está num dos caminhos válidos (~/.claude/skills/ ou .claude/skills/).

2. O Claude nunca invoca a skill sozinho. O problema está quase sempre na descrição. Reescreve-a para incluir palavras-chave concretas da tarefa, não conceitos abstratos.

3. Erro “Unexpected key” ao carregar para o claude.ai. Estás a usar um campo exclusivo do Claude Code (como context ou hooks) numa skill destinada à interface web. Remove-o ou cria uma versão separada.

4. Um comando shell injetado aborta a skill. Qualquer código de saída diferente de zero cancela a execução. Testa o comando isoladamente no terminal antes de o colocares na skill.

5. A skill funciona no Claude Code mas não aparece no telemóvel ou na app. Só skills sincronizadas a partir do claude.ai aparecem fora do Claude Code. Skills locais de projeto não sincronizam automaticamente.

6. Scripts Python falham por falta de dependências. Na API, os pacotes têm de estar pré-instalados porque as skills não instalam nada em tempo de execução nesse contexto.

7. Alterações ao SKILL.md não são detetadas na sessão atual. A monitorização de ficheiros fica desativada em modo “bare”. Reinicia a sessão nesse caso.

8. Pedidos de permissão constantes apesar de usares allowed-tools. Confirma a sintaxe do padrão: Bash(git commit *) aceita qualquer argumento a seguir, mas Bash(git commit) sem asterisco só corresponde ao comando exato, sem argumentos.

9. A skill consome demasiado contexto e a conversa fica lenta. Reduz o corpo do SKILL.md e usa ficheiros de referência separados. O Claude Code mantém apenas os últimos 5.000 tokens por skill quando o contexto fica cheio.

10. Alterações a plugins não têm efeito. Skills instaladas via plugin exigem /reload-plugins para atualizar hooks, subagentes ou estilos de resposta associados.

Dicas Avançadas para Quem Já Domina o Básico

Depois de dominares o essencial, vale a pena explorar combinações mais avançadas. Podes empilhar várias skills numa só invocação, por exemplo /revisao-codigo /resumo-alteracoes, e o Claude processa ambas em sequência. O campo paths permite restringir o carregamento automático a determinados padrões de ficheiros, útil quando tens dezenas de skills e queres evitar que todas concorram pela atenção do modelo ao mesmo tempo.

Para equipas maiores, o campo hooks permite registar automações (como correr um linter) sempre que a skill é invocada, e metadata guarda pares chave-valor arbitrários que ferramentas internas podem ler. Se distribuis skills fora da tua organização, o repositório público anthropics/skills no GitHub serve de referência para estrutura e boas práticas, com exemplos mantidos pela própria Anthropic.

Um último conselho, sobretudo para quem já lida com incidentes de segurança: trata skills de terceiros como código que corre com as tuas permissões, porque é exatamente isso que são. A mesma cautela que já se aplica a extensões de navegador ou pacotes npm faz sentido aqui, ainda mais depois de casos como o descoberto no GitSpawn, que mostrou como configurações de agentes de IA mal validadas podem ser exploradas.

Se ainda não experimentaste a API do Claude diretamente, o nosso guia prático da Claude API é um bom ponto de partida complementar a este tutorial, sobretudo se quiseres integrar skills num produto próprio em vez de usares apenas a interface do claude.ai.

Perguntas Frequentes

As Claude Skills funcionam em todos os planos do Claude?
Sim. Segundo a documentação de suporte da Anthropic, estão disponíveis nos planos Free, Pro, Max, Team e Enterprise do claude.ai, além de uma versão em beta na API através da ferramenta de execução de código.

Preciso de saber programar para criar uma skill?
Não para o essencial. Uma skill de referência simples é só um ficheiro Markdown com instruções. Programar só é necessário se quiseres adicionar scripts executáveis ou lógica mais avançada como context: fork.

Qual a diferença entre uma skill e o Model Context Protocol?
O MCP liga o Claude a ferramentas e dados externos, enquanto uma skill ensina o Claude a executar melhor uma tarefa usando conhecimento que tu escreves. Podes usar os dois em conjunto.

As skills conseguem aceder à internet?
Só indiretamente, através de scripts que façam pedidos de rede ou de integrações MCP associadas. Uma skill isolada, por si só, não tem acesso direto à internet.

Posso partilhar uma skill com a minha equipa?
Sim, de três formas: versionando a pasta .claude/skills/ no Git, distribuindo-a como plugin do Claude Code, ou carregando um zip nas definições de organização do claude.ai (disponível em planos Team e Enterprise).

Existe um limite de tamanho para uma skill?
A documentação oficial não define um limite rígido de ficheiro, mas recomenda manter o SKILL.md abaixo de 500 linhas, movendo detalhe para ficheiros de referência à parte.

Como sei se uma skill de terceiros é segura antes de a ativar?
Lê o conteúdo completo do SKILL.md e de todos os scripts incluídos antes de ativar, tal como farias com qualquer pacote de código externo. Confirma que não pede credenciais escritas em texto simples e que qualquer comando de shell é compreensível.

As skills funcionam com todos os modelos Claude, incluindo o Fable 5.1?
Sim, a funcionalidade de skills não está limitada a um modelo específico e aplica-se à gama de modelos Claude disponível na tua conta, incluindo lançamentos recentes como o Claude Fable 5.1.