Como configurar e usar Skills no Claude com MCP, projetos e arquivos SKILL.md

Desenvolvedores que integram o Claude (abre em nova aba) ao fluxo de engenharia costumam esbarrar em uma dúvida arquitetural logo na configuração do ambiente: o recurso oficial de Skills (habilidades) é apenas outro nome para chamada de ferramentas (Tool Use), servidores MCP ou instruções de projeto? Na plataforma da Anthropic (abre em nova aba), cada um desses elementos cumpre um papel distinto na execução de tarefas. Enquanto um servidor MCP (Model Context Protocol, padrão que conecta o modelo a bancos de dados, APIs e sistemas externos) fornece novas ferramentas sobre as quais o agente pode agir, uma skill é um manual de instruções em Markdown que ensina ao modelo como conduzir um processo específico.⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​​‌‌​‌​‌​​‌‌​‌​​​‌‌​​‌​​​​‌‌​​​‌​‌‌​​‌​​​​‌‌​‌​​​​‌‌​​​‌​​‌‌‌​​‌​​‌​‌‌​‌​‌‌​​​‌‌​‌‌​​​‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​‌​​​‌‌​​​‌‌​‌‌​​‌​‌​​‌‌​​​​​​‌​‌‌​‌​​‌‌‌​​‌​‌‌​​​​‌​​‌‌​‌​‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​​‌‌​​‌‌​‌‌‌​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​​​‌​‌‌​​‌​‌​​‌‌​‌​‌​​‌‌​‌‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌‌‌​​​​​‌‌​‌‌​⁠

Essa separação evita que você sobrecarregue a janela de contexto com regras que só fazem sentido em momentos pontuais do desenvolvimento. No Claude Code (a ferramenta de linha de comando e aplicativo local para leitura, edição de arquivos e execução de scripts) e no Claude Cowork (ambiente voltado para automação de tarefas repetitivas, unificado às conversas web, desktop e mobile), as skills operam sob o padrão aberto Agent Skills (abre em nova aba). Por seguir uma especificação aberta baseada em pastas e arquivos SKILL.md, a mesma skill criada para o agente da Anthropic pode ser lida por outras ferramentas compatíveis no terminal ou no editor.

Pré-requisitos e onde armazenar cada skill

O acesso ao Claude Code para manipular o sistema de arquivos local, assim como o uso integrado de skills no Cowork e na extensão Claude para Google Chrome, exige uma assinatura paga (planos Pro, Max, Team ou Enterprise). A camada gratuita do chat apenas responde a perguntas e gera texto, sem permissão para editar diretórios na máquina ou acionar automações locais. Nos planos Max e Team, a Anthropic também distribui créditos mensais de API vinculáveis ao Claude Console na seção de faturamento para rodar agentes próprios.

A pasta onde você salva a skill define quem tem acesso a ela e como os conflitos de nomes são resolvidos. Toda skill é um diretório contendo obrigatoriamente um arquivo SKILL.md (e, de forma opcional, scripts auxiliares, templates ou exemplos de saída). O agente busca essas pastas em 4 escopos diferentes:

• Escopo de projeto (.claude/skills/nome-da-skill/SKILL.md): restrito ao repositório atual. Como fica dentro da árvore do projeto, esse arquivo vai para o controle de versão no Git e distribui a automação para toda a equipe.
• Escopo pessoal (~/.claude/skills/nome-da-skill/SKILL.md): salvo na pasta do usuário no sistema operacional, fica disponível em todos os projetos daquela máquina.
• Escopo de plugin (skills/ dentro do pacote): utiliza o formato com namespace nome-do-plugin:nome-da-skill, como nos pacotes oficiais mantidos pela Anthropic no GitHub para manipulação de arquivos docx, pdf, pptx, xlsx e construção de artefatos web em React e Tailwind CSS.
• Escopo corporativo (Enterprise): implantado em toda a organização por administradores nos planos Team e Enterprise por meio de configurações gerenciadas.

E o que acontece quando duas skills em pastas diferentes recebem exatamente o mesmo nome? O sistema aplica uma hierarquia estrita de substituição: o nível corporativo (Enterprise) tem prioridade máxima, seguido pelo diretório pessoal do desenvolvedor e, por último, pela pasta local do projeto.⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​​‌‌​‌​‌​​‌‌​‌​​​‌‌​​‌​​​​‌‌​​​‌​‌‌​​‌​​​​‌‌​‌​​​​‌‌​​​‌​​‌‌‌​​‌​​‌​‌‌​‌​‌‌​​​‌‌​‌‌​​​‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​‌​​​‌‌​​​‌‌​‌‌​​‌​‌​​‌‌​​​​​​‌​‌‌​‌​​‌‌‌​​‌​‌‌​​​​‌​​‌‌​‌​‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​​‌‌​​‌‌​‌‌‌​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​​​‌​‌‌​​‌​‌​​‌‌​‌​‌​​‌‌​‌‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌‌‌​​​​​‌‌​‌‌​⁠

Como estruturar o arquivo SKILL.md e evitar falhas de acionamento

Um arquivo SKILL.md é dividido em duas partes: no topo, um bloco de frontmatter YAML (seção de metadados delimitada por linhas com três hifens ---) e, logo abaixo, o corpo em Markdown com o passo a passo que o agente deve cumprir. O campo name no cabeçalho define o atalho manual (por exemplo, /explain-code), enquanto o campo description orienta o modelo sobre quando carregar aquele pacote automaticamente durante uma conversa em linguagem natural.

Por que muitas skills recém-criadas simplesmente são ignoradas pelo agente durante o trabalho? A documentação oficial aponta que o Claude tem tendência a sub-acionar (undertrigger) uma skill se a descrição for curta ou genérica demais. Como o agente avalia apenas a lista de nomes e descrições antes de decidir se carrega o conteúdo completo do arquivo para a memória da sessão, a linha description precisa ser incisiva sobre os gatilhos de ativação, equilibrando clareza e economia no orçamento de contexto (context budget, o limite de tokens disponível para a conversa).

Em vez de escrever apenas Gera um checklist de deploy, um guia técnico publicado pela equipe da Sherlock mostra que você deve explicitar os termos de disparo: Gera um checklist de deploy. Use sempre que o usuário mencionar implantação, lançamento, envio para produção ou perguntar sobre prontidão de release, mesmo que não peça um checklist explicitamente.

---
name: [nome_da_skill]
description: [acao_principal]. Use sempre que o usuário mencionar [palavras_gatilho], mesmo que não invoque o comando pelo nome.
---

# Instruções de Execução

Quando esta skill estiver ativa, siga rigorosamente as etapas abaixo:

[passos_execucao]

Você também pode criar uma skill a partir de uma tarefa já concluída na sessão: basta executar o processo uma vez conversando com o agente e pedir para o Claude converter aquele histórico em um arquivo SKILL.md reutilizável. Para verificar na prática se a ferramenta foi reconhecida, digite / no prompt para listar os comandos disponíveis no diretório de trabalho atual ou faça um pedido usando uma das frases-gatilho da descrição e observe se o agente passa a seguir o roteiro do arquivo.

Limites operacionais e riscos de segurança em repositórios

O primeiro limite prático das skills de projeto é o isolamento de diretório. A descoberta automática baseia-se na pasta de trabalho atual até a raiz do repositório Git: se você estiver trabalhando no projeto A, o agente não enxergará as skills salvas exclusivamente na pasta .claude/skills/ do projeto B. Outro fator é o custo de processamento e tempo de resposta conforme o modelo escolhido na sessão: a família Haiku prioriza velocidade e baixo custo para alto volume, o Sonnet atua como equilíbrio intermediário e o Opus entrega a maior capacidade analítica com custo superior e ajuste de tempo de raciocínio (effort setting). No caso do Claude Opus 5.5, a execução custa 40% menos que a geração anterior Opus 5.

No ambiente de equipe, o maior ponto de atenção não é o formato do texto, mas a segurança da cadeia de suprimentos de software (supply chain). Um levantamento técnico da empresa de segurança StepSecurity destaca que compartilhar pastas .claude/skills/ em repositórios Git abre 3 vetores de risco que exigem auditoria antes de rodar o agente:

1. Execução com privilégios locais: uma skill pode empacotar scripts, declarar hooks (ganchos de execução automática) e embutir comandos de shell que rodam no instante em que a skill é carregada. Tudo o que ela executa roda com as permissões do usuário logado na máquina, no mesmo ambiente que armazena chaves SSH (protocolo Secure Shell), credenciais de provedores de nuvem e tokens de publicação de pacotes.
2. Pré-aprovação silenciosa de ferramentas: no Claude Code, o campo de frontmatter allowed-tools autoriza o agente a utilizar as ferramentas listadas sem exibir pedido de confirmação ao desenvolvedor durante o turno em que a skill é invocada. A própria documentação do Claude Code alerta que a configuração de confiança do diretório (workspace trust) não bloqueia esse campo, exigindo revisão manual do allowed-tools ao clonar repositórios de terceiros.
3. Aparência de documentação comum: como o SKILL.md é um arquivo Markdown, em uma revisão de código (pull request) ele se parece com um README.md tradicional e costuma ser aprovado sem a mesma inspeção aplicada a arquivos executáveis.

Para controlar o grau de liberdade do agente ao lidar com arquivos e ferramentas locais, o desenvolvedor pode alternar a operação do Claude Code entre 3 modos de autonomia: o modo manual (solicita permissão a cada alteração), o modo plan (pesquisa o código e propõe um roteiro para aprovação antes de agir) e o modo auto (executa as tarefas de forma independente enquanto uma segunda instância de IA monitora comportamentos de risco). Fora do plano gratuito restrito a conversas simples, a assinatura mensal de entrada para desbloquear essa edição local de arquivos no aplicativo custa em torno de US$ 20.⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​​‌‌​‌​‌​​‌‌​‌​​​‌‌​​‌​​​​‌‌​​​‌​‌‌​​‌​​​​‌‌​‌​​​​‌‌​​​‌​​‌‌‌​​‌​​‌​‌‌​‌​‌‌​​​‌‌​‌‌​​​‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​‌​​​‌‌​​​‌‌​‌‌​​‌​‌​​‌‌​​​​​​‌​‌‌​‌​​‌‌‌​​‌​‌‌​​​​‌​​‌‌​‌​‌​​‌‌​‌‌‌​​‌​‌‌​‌​​‌‌​​‌‌​​‌‌​‌‌‌​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​​​‌​‌‌​​‌​‌​​‌‌​‌​‌​​‌‌​‌‌‌​‌‌​​​‌‌​​‌‌​‌‌‌​​‌‌‌​​​​​‌‌​‌‌​⁠