Claude Skills e SKILL.md para Desenvolvedores: VS Code, JetBrains, Cursor

A maioria das equipes usa Claude Skills de forma inadequada em um dos dois sentidos. Elas ou transformam o SKILL.md em um depósito de informações, ou nunca evoluem além de grandes prompts copiados e colados.

Ambas as abordagens são descuidadas. Se você deseja que Skills funcionem em um fluxo de desenvolvimento real, precisa tratá-las como código e lógica de operações, não como poesia de prompt.

Claude Skills são diretórios ancorados por SKILL.md, com scripts, referências e ativos opcionais. Eles funcionam graças à revelação progressiva. O agente começa carregando apenas metadados compactos, como o nome e a descrição da skill, e só lê as instruções completas quando a tarefa corresponde. Isso permite que um agente mantenha muitas skills disponíveis sem inflar cada sessão desde o início.

Se você também opera o Hermes Agent, a mesma estrutura em disco está alinhada com a especificação no estilo agentskills documentada pelo Hermes — ativação condicional, varredura de hubs e segredos versus configuração estão detalhadas em Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices.

A própria orientação da Anthropic torna a divisão de trabalho pretendida bastante clara. CLAUDE.md é para contexto de projeto durável e sempre ativo. Skills são para conhecimento reutilizável, playbooks e fluxos de trabalho invocáveis que devem ser carregados sob demanda. Isso torna as Skills o lugar natural para codificar um ciclo de desenvolvimento orientado por especificação — especificar, planejar, implementar, validar — quando você quer mais estrutura do que vibe coding, mas menos cerimônia do que um scaffold completo de Spec Kit. Veja GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows para saber como as skills do Claude Code se comparam a alternativas portáveis e integradas a IDEs. Se você prefere instalar esse ciclo pré-construído e aplicado em vez de criá-lo você mesmo, o Superpowers empacota exatamente esse tipo de pilha de skills — brainstorming, planejamento, revisão por subagentes, TDD — como um plugin instalável.

O Claude Code até mesmo incorporou os antigos comandos personalizados no mesmo mecanismo, então os arquivos legados .claude/commands/*.md ainda funcionam, mas as Skills são agora a forma mais adequada a longo prazo — e o bloco de construção mais reutilizável em qualquer fluxo de trabalho de desenvolvimento impulsionado por IA.

Quando usar Claude Skills: CLAUDE.md vs Skills vs Hooks

Vale a pena criar uma Claude Skill quando você continua colando a mesma lista de verificação, o mesmo playbook de implantação, a mesma rubrica de revisão de código ou as mesmas pegadinhas da API interna no chat. A Anthropic recomenda explicitamente criar uma skill quando você continua reutilizando o mesmo procedimento, ou quando uma seção do CLAUDE.md cresceu até se tornar um processo em vez de um fato. Essa é a resposta prática para a pergunta de FAQ “O que é uma Claude Skill e quando devo usar uma”. Use uma Skill para procedimentos repetíveis, não para gosto geral ou regras amplas do repositório.

A verdadeira vantagem é o controle sobre o custo de contexto e o comportamento. Uma boa Skill é carregada apenas quando relevante, enquanto um CLAUDE.md inchado é carregado em cada sessão. A Anthropic recomenda manter o CLAUDE.md curto e mover conhecimento de domínio ou procedimentos para Skills precisamente porque o carregamento sob demanda mantém o agente focado na tarefa em frente a ele.

Minha regra opinativa é simples. Se a instrução deve se aplicar em cada sessão, ela pertence ao CLAUDE.md. Se a instrução é um método, lista de verificação ou fluxo de trabalho reutilizável que só importa às vezes, ela pertence a uma Skill. Se a ação deve acontecer automaticamente em cada evento correspondente, ela provavelmente pertence a um hook, não a uma Skill. A visão geral de recursos da Anthropic enquadra essas ferramentas em quase exatamente esse modelo de camadas.

Um sinal prático para cada um: se você se pega colando as mesmas instruções em cada chat, é uma Skill. Se uma seção do CLAUDE.md cresceu até se tornar um processo passo a passo, extraia-a para uma Skill. Se você quer que algo dispare silenciosamente sempre que um arquivo é salvo, escreva um hook em vez disso. Há também uma quarta camada que vale a pena conhecer: quando uma tarefa gera muita saída intermediária barulhenta que você não quer poluindo a sessão principal — exploração de base de código, uma grande execução de testes — isso é um trabalho para um subagente, não uma Skill.

Suporte a IDE para Claude Skills: VS Code, JetBrains, Cursor e Codex

O Claude Code funciona em CLI, Desktop, VS Code, JetBrains, web e fluxos relacionados a controle remoto móvel. A Anthropic descreve o CLI como a superfície local mais completa, enquanto as integrações de IDE trocam algumas capacidades exclusivas do CLI por revisão nativa do editor, contexto de arquivo e ergonomia de fluxo de trabalho mais apertada. A configuração, a memória do projeto e os servidores MCP são compartilhados entre as superfícies locais, então sua configuração .claude o segue, em vez de ficar presa em um editor.

Para o VS Code, a Anthropic diz que a extensão é a interface recomendada dentro do editor. Ela fornece revisão de plano, diffs inline, suporte a menção de arquivos e acesso integrado ao CLI. O mesmo fluxo de instalação também expõe um caminho direto para o Cursor. Para o JetBrains, a lista atual de suportados inclui IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm e GoLand, com visualização de diffs, compartilhamento de seleção, atalhos de referência de arquivo e compartilhamento de diagnósticos incorporados ao plugin.

O suporte a JetBrains é melhor do que muitos desenvolvedores percebem. Se você executar claude do terminal integrado da IDE, os recursos de integração estão ativos automaticamente. Se você iniciar de um terminal externo, a Anthropic documenta o comando /ide para reconectar o Claude Code à sessão do JetBrains, e recomenda explicitamente iniciar a partir da mesma raiz do projeto para que o Claude veja os mesmos arquivos que sua IDE vê. Se você usar modos de auto-edição no JetBrains, a Anthropic também alerta que os arquivos de configuração da IDE podem se tornar parte da superfície editável, então aprovações manuais são o padrão mais seguro nesse ambiente.

Agora o ponto maior. Claude Skills não são apenas uma coisa do Claude Code. Agent Skills é um padrão aberto. O quickstart oficial de Agent Skills diz que a mesma skill pode funcionar no VS Code com GitHub Copilot, Claude Code e OpenAI Codex, e os próprios docs do Codex da OpenAI dizem que Skills estão disponíveis no Codex CLI, extensão de IDE e app. O guia de implementação de Agent Skills adiciona um detalhe importante de portabilidade: .agents/skills emergiu como a convenção entre clientes, enquanto alguns clientes também varrem .claude/skills para compatibilidade pragmática.

Então aqui está a regra prática de compatibilidade que eu recomendo. Se você está construindo primeiro e apenas para o Claude Code, autorize em .claude/skills. Se você genuinamente quer portabilidade entre clientes, mire na forma aberta de Agent Skills e use .agents/skills como o caminho canônico. Não finja que esses dois objetivos são idênticos. Eles estão relacionados, não idênticos.

Referência rápida de compatibilidade:

Estrutura, Layout de Pastas e Locais de Armazenamento do Arquivo SKILL.md

Uma Skill adequada é uma pasta, não um arquivo markdown aleatório na raiz do repositório. A especificação central requer um diretório com um arquivo SKILL.md e permite diretórios opcionais scripts/, references/ e assets/. SKILL.md deve conter frontmatter YAML seguido de instruções em markdown. Na especificação, name e description são obrigatórios, name é limitado a 64 caracteres usando letras minúsculas, números e hífens, compatibility é apenas para requisitos reais de ambiente, e allowed-tools é explicitamente experimental entre implementações.

O Claude Code é um pouco mais flexível do que a especificação portável porque pode derivar um nome do diretório e fazer fallback para o primeiro parágrafo quando description estiver ausente. Você não deve depender disso se se importa com portabilidade ou previsibilidade. O Claude.ai requer que o nome do diretório corresponda ao campo name, e seu caminho de upload de skill personalizada limita descrições a 200 caracteres, mesmo que a especificação mais ampla permita muito mais. A escolha portável é definir um name explícito, manter o diretório idêntico e escrever uma descrição precisa que caiba em limites apertados. Isso responde ao tópico de FAQ “O que um arquivo SKILL.md deve conter” sem rodeios.

Comece com uma estrutura tão sem graça quanto esta:

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Se a portabilidade entre clientes compatíveis com Skills importar mais do que a conveniência do Claude Code, mantenha a mesma forma interna e troque .claude/skills/ por .agents/skills/. A estrutura de pastas é a mesma ideia em qualquer caso.

Para o Claude Code, os locais de armazenamento são diretos. Skills de projeto ficam em .claude/skills/<skill-name>/SKILL.md. Skills pessoais ficam em ~/.claude/skills/<skill-name>/SKILL.md. Skills distribuídas por plugin ficam sob <plugin>/skills/<skill-name>/SKILL.md. A Anthropic documenta precedência entre os escopos integrados como empresa sobre pessoal sobre projeto, enquanto skills de plugin evitam colisões usando uma forma com namespace, como plugin-name:skill-name. No Windows, ~/.claude resolve para %USERPROFILE%\.claude, e CLAUDE_CONFIG_DIR pode realocar todo o diretório base.

A escolha entre escopo de projeto e pessoal é direta. Use .claude/skills/ dentro do repositório quando a Skill estiver acoplada a essa base de código — por exemplo, um playbook de implantação que conhece seus nomes específicos de cluster ou uma rubrica de revisão ajustada às convenções da sua equipe. Use ~/.claude/skills/ para Skills que viajam com você entre projetos: listas de verificação pessoais, geradores genéricos de changelog, fluxos de trabalho de depuração preferidos. Qualquer coisa que você colocaria em um repositório de dotfiles pertence ao escopo pessoal.

Algumas arestas afiadas valem a pena memorizar. SKILL.md deve ser nomeado exatamente com essa capitalização. O guia em PDF da Anthropic recomenda nomes de pastas em kebab-case e diz explicitamente para não colocar um README.md dentro da pasta da skill, porque a documentação operacional deve estar em SKILL.md ou references/. O mesmo guia também enfatiza que a nomenclatura de SKILL.md é sensível a maiúsculas e minúsculas. Essas são restrições sem graça, mas restrições sem graça são o que tornam as ferramentas confiáveis.

O Claude Code também faz a coisa certa para monorepos. Ele descobre automaticamente diretórios aninhados .claude/skills/ quando você trabalha dentro de subdiretórios, o que é ideal para skills de nível de pacote ou de serviço. Ele também monitora diretórios de skills existentes por mudanças ao vivo durante a sessão atual. A única armadilha de reinicialização é criar um diretório de skills de nível superior que não existia quando a sessão começou. A Anthropic documenta isso como o caso em que você precisa reiniciar para que o novo diretório possa ser monitorado.

Boas Práticas de Claude Skills: Descrições, Scripts e Escopo

A maneira mais rápida de criar uma Skill inútil é pedir a um LLM para inventar uma a partir do conhecimento de treinamento genérico. O guia de boas práticas da Anthropic adverte contra exatamente isso. As partes valiosas são as correções específicas do domínio, casos extremos, escolhas de ferramentas e convenções que o modelo não inventaria de forma confiável por conta própria. O fluxo de trabalho certo é resolver a tarefa uma vez com o agente, corrigi-la até que funcione, e então extrair o método para uma Skill.

Delimite a Skill como uma boa função, não como uma wiki. A Anthropic diz que Skills devem encapsular uma unidade de trabalho coerente. Muito estreita, e você força múltiplas skills a se empilhar para uma tarefa. Muito ampla, e o agente não consegue ativá-las com precisão. O guia de boas práticas é direto ao dizer que skills excessivamente abrangentes podem prejudicar mais do que ajudar porque o modelo persegue instruções irrelevantes e perde o sinal.

A qualidade da descrição não é uma preocupação cosmética. É a camada de roteamento. Tanto a Anthropic quanto os docs de Agent Skills dizem que o campo description é o mecanismo primário que o modelo usa para decidir se carrega uma Skill ou não. Boas descrições dizem o que a Skill faz, quando usá-la e as frases de gatilho ou tipos de arquivo que um usuário realmente mencionaria. Más descrições são vagas, excessivamente técnicas ou amplas o suficiente para corresponder a qualquer coisa. Essa é a resposta real para a pergunta de FAQ “Por que uma Claude Skill não está disparando”. Geralmente o roteador é ruim, não o modelo.

O contraste é claro lado a lado:

Más descrições — vagas demais para rotear com confiabilidade:

• Helps with code review — corresponde a tudo, não desambigua nada
• Useful for development tasks — mais amplo do que uma consulta de busca
• Assists with writing — não é um roteador, apenas um rótulo de categoria

Boas descrições — linguagem de gatilho específica:

• Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
• Generate a changelog from git log output. Use when preparing a release, writing release notes, or summarising commits since last tag.
• Scaffold a new Go HTTP handler with request validation and error middleware. Use when adding a new endpoint or route to a Go service.

O padrão é o mesmo cada vez: declare o que a Skill faz, nomeie as frases exatas do usuário que devem ativá-la e, opcionalmente, nomeie tipos de arquivo ou ferramentas que sejam relevantes. Se sua descrição corresponder a uma consulta genérica do Google, ela não é específica o suficiente.

Se um fluxo de trabalho tem efeitos colaterais, torne-o manual. O Claude Code expõe isso diretamente. disable-model-invocation: true torna uma Skill apenas invocada pelo usuário, o que a Anthropic recomenda para ações como implantações, commits ou mensagens de saída. user-invocable: false vai no sentido oposto e esconde a Skill do menu de barras, enquanto ainda permite que o Claude a use como conhecimento de fundo. Isso responde ao tópico de FAQ “Quando uma skill deve ser manual em vez de automática” em uma frase: manual para risco, automático para orientação repetível e segura.

Mantenha o SKILL.md pequeno o suficiente para permanecer inteligível. A Anthropic recomenda mantê-lo abaixo de 500 linhas e cerca de 5.000 tokens, e então mover material detalhado para references/ ou arquivos semelhantes com instruções de carregamento explícitas. “Leia references/api-errors.md se a API retornar um não-200” é um bom padrão. “Veja references/” é preguiçoso. O Claude Code também injeta a Skill renderizada na conversa como uma mensagem e não continua relendo o arquivo em turnos posteriores. Após a compactação de contexto, apenas o conteúdo recente da Skill é levado adiante dentro dos orçamentos de tokens. Skills enormes, portanto, não são apenas feias. Elas são frágeis em sessões longas.

Um bom SKILL.md pode permanecer muito simples:

---
name: review-pr
description: Review pull requests for security issues, migration risk, and missing tests. Use when reviewing a PR, git diff, or release critical change.
compatibility: Designed for Claude Code. Requires git and gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Review PR

Read references/checklist.md before running any commands.

1. Collect the diff and changed files.
2. Flag correctness, security, and test coverage issues.
3. Return findings grouped by severity with file references.
4. Suggest the smallest safe fix first.

Use scripts quando a determinação importe mais do que a eloquência. O guia de scripts de Skills é excelente aqui. Ele diz que scripts voltados para agentes devem evitar prompts interativos, documentar o uso através de --help, emitir mensagens de erro úteis, preferir saída estruturada, como JSON ou CSV, no stdout, enviar diagnósticos para stderr e suportar uso seguro para retry. Ele também recomenda fixar versões de ferramentas de uso único e descrever requisitos de runtime explicitamente em SKILL.md ou no campo compatibility em vez de assumir que o ambiente tem os pacotes certos.

Um script mínimo, mas correto, voltado para agentes parece com este:

#!/usr/bin/env bash
# scripts/collect-diff.sh — called by review-pr skill
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Structured output to stdout so the agent can parse it
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Três coisas tornam isso seguro para agentes. set -euo pipefail garante que o script termine com erro em qualquer falha, em vez de continuar silenciosamente. JSON no stdout dá ao agente um formato que ele pode analisar sem adivinhar. Diagnósticos vão para stderr para que o fluxo de stdout do agente permaneça limpo. Nada disso é inteligente. Tudo é necessário.

Uma armadilha sutil é allowed-tools. Na especificação, é experimental e o suporte varia. No Claude Code, ele pré-aprova ferramentas específicas enquanto a Skill está ativa, mas não restringe o universo de ferramentas chamáveis, e regras de negação ainda pertencem às permissões do Claude Code. No Claude Agent SDK, a Anthropic diz explicitamente que o frontmatter allowed-tools em SKILL.md não se aplica, então aplicativos SDK devem aplicar o acesso a ferramentas na configuração principal allowed_tools ou allowedTools. Se você ignorar essa diferença, sua Skill se comportará de forma diferente no CLI e em automação baseada em SDK.

Um padrão avançado mais vale a pena roubar. Quando um fluxo de trabalho inundaria sua thread principal com logs, buscas de arquivos ou saída de pesquisa longa, o Claude Code permite que uma Skill seja executada em um subagente bifurcado usando context: fork e um agent como Explore. A Anthropic mostra isso para fluxos de trabalho de pesquisa, onde o trabalho pesado acontece em contexto isolado e a conversa principal recebe o resumo. Para exploração profunda de base de código, esse é um design muito melhor do que uma Skill inline gigante que polui a sessão principal.

Uma Skill bifurcada parece com isto no frontmatter:

---
name: explore-codebase
description: Deep exploration of an unfamiliar codebase. Use when onboarding to a new repo, auditing architecture, or mapping module dependencies.
context: fork
agent: Explore
compatibility: Requires Claude Code CLI.
---
# Explore Codebase

1. Walk the directory tree and summarise the top-level modules.
2. Identify the main entry points and their responsibilities.
3. Map the dependency graph between packages.
4. Return a structured summary to the main session — not the raw file list.

A linha-chave é context: fork. Sem ela, a saída da exploração cai inline na sua conversa. Com ela, o subagente roda em sua própria janela de contexto e devolve um resumo. A diferença importa em repositórios grandes, onde a exploração por si só pode consumir milhares de tokens.

Testando Claude Skills: Gatilhos, Correção e Comparações de Linha de Base

Uma Skill não é testada porque um demo de caminho feliz funcionou uma vez. O guia da Anthropic divide o teste em três camadas: teste manual no Claude.ai, teste com script no Claude Code e teste programático via a API de Skills. As áreas de avaliação recomendadas são gatilho, correção funcional e desempenho em relação a uma linha de base sem a Skill. Essa também é a melhor resposta para a pergunta de FAQ “Como você testa se uma skill é confiável”. Você testa a seleção de rota, a qualidade da saída e a eficiência, não apenas se o modelo soou confiante.

A orientação oficial de avaliação dá uma estrutura limpa para casos de teste. Cada caso deve incluir um prompt de usuário realista, uma descrição legível por humanos da saída esperada e arquivos de entrada opcionais. Os docs armazenam esses em evals/evals.json dentro do diretório da Skill, o que é uma convenção sensata, mesmo que você crie seu próprio harness.

Use um arquivo de fixture e um layout de avaliação sem rodeios como este:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Review this PR for security issues and missing tests",
      "expected_output": "Findings grouped by severity with file references and at least one test recommendation.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Summarise last week's commits",
      "expected_output": "The skill should not activate.",
      "files": []
    }
  ]
}

Minha regra de teste é mais severa do que a maioria das equipes usa, mas está alinhada com a orientação oficial. Toda Skill séria deve ter consultas que devem disparar, consultas que não devem disparar, pelo menos um teste de caso extremo e uma comparação de linha de base sem a Skill. Os exemplos da Anthropic comparam chamadas de ferramentas, chamadas de API falhas, loops de esclarecimento e uso de tokens com e sem a Skill porque “funciona” não é o mesmo que “melhora o fluxo de trabalho”.

Se você testa através do Claude Agent SDK, lembre-se da tubulação. Skills são artefatos de sistema de arquivos ali, não registros programáticos. A Anthropic diz que você deve habilitar a ferramenta "Skill" e carregar as configurações de sistema de arquivos relevantes através de settingSources ou setting_sources. Se você omitir user ou project, ou apontar cwd para o lugar errado, o SDK não descobrirá a Skill. A Anthropic até mesmo recomenda perguntar “What Skills are available?” como um verificação direta de descoberta.

Também teste no modelo e cliente que você realmente pretende lançar. O quickstart aberto de Agent Skills adverte explicitamente que a confiabilidade do uso de ferramentas varia entre modelos, e alguns modelos podem responder diretamente em vez de executar o comando que a Skill pretende. Isso nem sempre é um problema de design da Skill. Às vezes é um problema de seleção de modelo, e sua matriz de teste deve expô-lo.

Solução de Problemas de Claude Skills: Falhas Comuns e Correções

Quando uma Skill se comporta mal, assuma embalagem antes de inteligência. As falhas mais comuns ainda são as sem graça.

• Se a Skill não for encontrada de todo, verifique se o arquivo é nomeado exatamente SKILL.md, com a capitalização certa, dentro do diretório correto. O guia de solução de problemas da Anthropic destaca a capitalização do nome do arquivo explicitamente, e seus docs de Claude Code e SDK apontam diretamente para .claude/skills/*/SKILL.md e ~/.claude/skills/*/SKILL.md como as primeiras verificações.
• Se o frontmatter for inválido, verifique primeiro os delimitadores e as aspas do YAML. Os exemplos da Anthropic mostram os erros clássicos: falta de ---, aspas não fechadas ou nomes inválidos com espaços e maiúsculas. Os nomes de Skills devem ser minúsculos e hifenizados.
• Se a Skill existe, mas não dispara, a descrição geralmente é vaga demais. A própria solução de problemas do Claude Code diz para incluir palavras-chave que os usuários diriam naturalmente, verificar se a Skill aparece quando você pergunta “What skills are available?”, e tentar reformular mais próximo da descrição. O guia em PDF da Anthropic adiciona um truque de diagnóstico ótimo: pergunte ao Claude quando ele usaria a Skill e ouça como ele parafraseia a descrição de volta para você.
• Se a Skill dispara com frequência demais, estreite o escopo. A Anthropic recomenda tornar a descrição mais específica, adicionar gatilhos negativos e usar disable-model-invocation: true para fluxos de trabalho que você quer apenas por comando explícito. Disparo excessivo geralmente é apenas linguagem de roteamento sub-especificada.
• Se a Skill parece perder influência em sessões longas, lembre-se de que as descrições podem ser encurtadas no catálogo do Claude Code quando muitas skills estão presentes, e Skills invocadas são levadas adiante dentro de orçamentos de tokens após a compactação. A Anthropic recomenda colocar palavras-chave no início da descrição, cortar texto excessivo e, especificamente para o Claude Code, ajustar SLASH_COMMAND_TOOL_CHAR_BUDGET se as listagens de descrição estiverem sendo espremidas agressivamente demais.
• Se um script embutido travar ou se comportar erraticamente, verifique se ele espera entrada interativa. O guia de scripts diz que agentes rodam em shells não interativos, então prompts TTY, diálogos de senha e menus de confirmação são bugs de design. Aceite entrada através de flags, variáveis de ambiente ou stdin e torne as falhas explícitas.
• Se o SDK não vê sua Skill, confirme que allowed_tools inclui "Skill", que settingSources ou setting_sources contém user e/ou project, e que cwd aponta para o diretório que realmente contém .claude/skills/. Sem essa configuração, o sistema de Skills não é habilitado, não importa o quão correto seu markdown pareça.
• Se uma Skill baseada em MCP carrega, mas as chamadas de ferramenta falham, a lista de verificação de solução de problemas da Anthropic é sensata: verifique se o servidor MCP está conectado, confirme autenticação e escopos, teste a ferramenta MCP diretamente sem a Skill, e então verifique os nomes exatos das ferramentas, porque eles são sensíveis a maiúsculas e minúsculas.

A verdade sem graça é que boas Claude Skills parecem com boa engenharia operacional. Nomes claros. Arquivos pequenos. Gatilhos explícitos. Scripts determinísticos onde necessário. Testes reais. Se sua Skill lê como um runbook conciso, o agente tem uma chance de luta. Se ela lê como um brainstorm, você simplesmente escondeu o caos em uma pasta.