Guia completo para criar Claude Skills

• Claude Skills é um pacote de conhecimento de workflow projetado para definir uma vez fluxos de trabalho repetitivos e reutilizá-los continuamente
• O guia em PDF de 33 páginas, escrito pela própria Anthropic, aborda passo a passo todo o processo, do design de Skills à estruturação, testes e implantação
• Inclui uma ampla variedade de cenários de uso, desde automação de workflows isolados até o reforço da integração de ferramentas com base em MCP
• Foi elaborado com base em padrões e casos de falha validados em ambientes reais de operação
• Se os 2 ou 3 principais workflows já estiverem organizados, é possível construir e testar a primeira Skill em 15 a 30 minutos

---

Introduction

• Este guia tem como objetivo tratar Claude Skills não como prompts de uso único, mas como ativos de workflow reutilizáveis
• Skills são definidas como uma estrutura projetada para ensinar ao Claude uma tarefa ou processo específico uma única vez, permitindo sua reutilização consistente em conversas futuras
• Ao evitar a necessidade de explicar repetidamente preferências, forma de trabalhar e conhecimento de domínio, elas reduzem significativamente os custos cognitivos e operacionais

• Situações em que Skills são especialmente eficazes

  • Skills têm o maior impacto em tarefas repetíveis e estruturadas
    • Geração de design frontend com base em especificações
    • Execução de pesquisas seguindo uma metodologia consistente
    • Redação de documentos refletindo o guia de estilo da equipe
    • Orquestração de processos complexos com múltiplas etapas
  • Elas se combinam naturalmente com os recursos nativos do Claude, como execução de código e geração de documentos

• Diferença de papéis entre MCP e Skills

  • Ao usar integrações MCP, Skills são descritas como uma camada adicional que estabiliza o workflow, indo além da simples conexão com ferramentas
  • Se o MCP fornece “o que pode ser feito”, as Skills cumprem o papel de fixar “como isso deve ser feito”
  • Isso permite transformar acesso bruto a ferramentas em uma experiência de automação confiável

• Objetivo e escopo do guia

  • Este documento cobre todo o processo necessário para construir Skills
    • Planejamento prévio e design da estrutura
    • Forma prática de escrita
    • Testes e melhoria iterativa
    • Implantação e compartilhamento
  • Abrange todo o espectro de uso, de Skills pessoais a Skills padronizadas para equipes e Skills voltadas ao compartilhamento com a comunidade
  • Em vez de focar em teoria, é estruturado em torno de padrões e exemplos validados na prática

• Público-alvo

  • Desenvolvedores que querem que o Claude execute determinados workflows sempre da mesma forma
  • Power users que desejam automatizar tarefas repetitivas
  • Equipes que buscam padronizar, em nível organizacional, a forma de uso do Claude
  • Builders que querem combinar conhecimento de workflow com conectores MCP

• Caminhos de uso do guia

  • Se o objetivo for criar Skills de forma independente:
    • Fundamentals
    • Planning and Design
    • Recomendado focar principalmente nas categorias 1 e 2
  • Se o objetivo for reforçar integrações MCP:
    • Seção Skills + MCP
    • Recomendado focar principalmente na categoria 3
  • Os dois caminhos compartilham requisitos técnicos, e é possível aplicar seletivamente apenas o que for necessário

• Resultado esperado

  • O guia foi projetado para que seja possível concluir uma Skill prática em uma única sessão
  • Se houver 2 ou 3 workflows principais claramente definidos, a primeira Skill poderá ser construída e testada em cerca de 15 a 30 minutos
  • A Introduction deixa claro o ponto de vista central assumido por todos os capítulos seguintes:
    “Skills não são prompts, e sim conhecimento de trabalho reutilizável”

Chapter 1: Conceitos básicos (Fundamentals)

• Explica a base conceitual e a filosofia de design necessárias para entender Claude Skills
• Define Skills não como um simples conjunto de prompts, mas como uma unidade de conhecimento de trabalho reutilizada continuamente
• Organiza os princípios centrais que servem de base para as discussões sobre design, testes e implantação nos capítulos seguintes

• O que é uma Skill

  • Uma Skill é uma estrutura que permite ensinar ao Claude, uma única vez, como executar uma tarefa ou workflow específico, para uso repetido posterior
  • Ela é projetada para eliminar a necessidade de explicar repetidamente preferências, procedimentos e conhecimento de domínio do usuário
  • Tem maior efeito em tarefas com alto grau de repetição
  • Exemplos:
    • Geração de design frontend com base em especificações
    • Realização de pesquisas de maneira consistente
    • Redação de documentos seguindo o guia de estilo da equipe
    • Execução automática de processos com múltiplas etapas

• Componentes básicos de uma Skill

  • Uma Skill é organizada como uma única pasta
  • Componentes obrigatórios:
    • SKILL.md: arquivo principal que inclui frontmatter YAML e instruções em Markdown
  • Componentes opcionais:
    • scripts/: código executável em Python, Bash etc.
    • references/: documentos e guias consultados quando necessário
    • assets/: templates e recursos usados na saída
  • Essa estrutura foi projetada para oferecer simplicidade e escalabilidade ao mesmo tempo

• Princípio central de design 1: Progressive Disclosure

  • Skills seguem uma estrutura de carregamento de informações em 3 níveis

  • Nível 1: frontmatter YAML

    • Sempre é carregado no prompt de sistema do Claude
    • Inclui apenas as informações mínimas necessárias para decidir quando a Skill deve ser usada
    • Tem a função de evitar carregamento desnecessário de contexto

  • Nível 2: corpo de SKILL.md

    • É carregado quando o Claude entende que a Skill é relevante
    • Contém os procedimentos e instruções reais de trabalho

  • Nível 3: arquivos vinculados

    • references, scripts, assets etc.
    • São explorados apenas quando o Claude considera necessário
    • Mantêm a especialização enquanto minimizam o uso de tokens
  • Essa estrutura permite alcançar um equilíbrio entre custo de contexto e precisão na execução

• Princípio central de design 2: Composability

  • O Claude pode carregar várias Skills ao mesmo tempo
  • Portanto, cada Skill:
    • não deve presumir execução isolada
    • deve ser projetada para não entrar em conflito com outras Skills
  • Parte-se do pressuposto de um ambiente em que a colaboração entre Skills é possível

• Princípio central de design 3: Portability

  • Skills são projetadas para funcionar da mesma forma em Claude.ai, Claude Code e ambientes de API
  • Uma Skill criada uma vez pode ser reutilizada sem modificações específicas por plataforma
  • No entanto, scripts, acesso à rede e similares ainda dependem das limitações do ambiente de execução

• Relação entre MCP e Skills

  • Ao usar MCP, Skills cumprem o papel de camada de conhecimento (knowledge layer)
  • O MCP fornece acesso a ferramentas e dados
  • Skills definem como essas ferramentas devem ser usadas

  • Analogia da cozinha

    • MCP: cozinha, ingredientes e utensílios
    • Skills: receita
    • Quando os dois se combinam, o usuário não precisa projetar manualmente processos complexos

• Quando usadas sem MCP

  • Mesmo sem MCP, Skills continuam sendo bastante úteis
  • Apenas com os recursos nativos do Claude, como geração de documentos e execução de código, já é possível:
    • padronizar tarefas repetitivas
    • garantir consistência de qualidade
    • melhorar a velocidade de trabalho

• Mensagem central deste capítulo

• Skills não são uma otimização de prompt de curto prazo, e sim ativos de trabalho acumulados continuamente
• Mais importante do que “o que pode ser feito” é “fixar como isso deve ser feito”
• Os próximos capítulos expandem esse conceito para as etapas práticas de design e operação

Capítulo 2: Planejamento e design (Planning and Design)

• Este capítulo parte da premissa de que o sucesso ou fracasso na criação de Skills é quase determinado pela qualidade do design antes da etapa de escrita

• Antes da implementação técnica, é preciso deixar claro qual problema será resolvido e qual fluxo será fixado

• Um Skill bem projetado torna a implementação mais simples e também reduz bastante os custos de teste e manutenção

• Ponto de partida: definição de casos de uso

  • Antes de escrever um skill, é obrigatório definir 2 a 3 casos de uso concretos (use cases)
  • Casos de uso não são objetivos abstratos, mas devem incluir até as frases que usuários reais diriam e os resultados esperados

  • Componentes de um bom caso de uso

    • O objetivo que o usuário quer alcançar
    • A frase de gatilho que o usuário provavelmente diria
    • As tarefas em etapas que precisam ser executadas internamente
    • As ferramentas usadas (funções nativas do Claude ou MCP)
    • O estado final do resultado
  • Por meio de exemplos, enfatiza-se a importância de uma definição clara de condição inicial – etapas de processamento – estado de conclusão, como em “planejamento de sprint”

• Perguntas-chave a fazer antes do design

  • O que o usuário quer concluir
  • Qual workflow em várias etapas é necessário para chegar a esse resultado
  • Em que etapa cada ferramenta é necessária
  • Onde incorporar conhecimento de domínio ou boas práticas que exigem julgamento humano
  • Se você não consegue responder essas perguntas com clareza, ainda não está pronto para fixar isso como um Skill

• Principais tipos de casos de uso de Skill observados

  • Categoria 1: geração de documentos e ativos

    • Usado para gerar entregas em que a consistência de qualidade é importante
    • Inclui documentos, apresentações, designs, código e entregáveis de UI
    • Características:
      • Guias de estilo e regras de marca incorporados
      • Uso de templates de saída
      • Inclusão de checklist final de qualidade
    • Pode ser concluído apenas com as funções nativas do Claude, sem ferramentas externas

  • Categoria 2: automação de workflow

    • Adequado para processos em que várias etapas precisam ser executadas repetidamente
    • Ex: skill-creator
    • Características:
      • Inclui progresso por etapa e pontos de verificação
      • Fornece templates estruturados
      • Incorpora loops intermediários de revisão e melhoria
    • É descrito como um tipo que prioriza a estabilidade do processo mais do que o resultado

  • Categoria 3: reforço com MCP

    • Converte o acesso a ferramentas fornecido pelo servidor MCP em workflows realmente utilizáveis
    • Características:
      • Combina várias chamadas MCP em sequência
      • Complementa automaticamente contextos que o usuário não precisa especificar diretamente
      • Inclui tratamento para situações de erro do MCP
    • É definido não como simples automação, mas como encapsulamento de uso especializado

• A importância de definir critérios de sucesso

  • Um Skill não deve ser avaliado por “parecer funcionar bem”, mas por gerar efeito de melhoria
  • Os critérios de sucesso são apresentados não como números exatos, mas como critérios com direção clara

  • Critérios quantitativos

    • É acionado automaticamente na maior parte das solicitações pretendidas
    • Reduz o número de chamadas de ferramentas e o uso de tokens ao usar o skill
    • Conclui o workflow sem falhas nas chamadas MCP

  • Critérios qualitativos

    • O processo avança mesmo sem o usuário precisar instruir a próxima etapa
    • A estrutura e a qualidade dos resultados permanecem consistentes em execuções repetidas
    • Mesmo usuários novos conseguem ter sucesso na primeira tentativa
  • Reconhece-se que a avaliação pode incluir certo grau de julgamento intuitivo (vibes), mas fica explícito que os critérios de comparação devem ser mantidos

• Visão geral dos requisitos técnicos

  • O Skill deve seguir uma estrutura de diretórios fixa
  • O arquivo SKILL.md é obrigatório, e o nome deve corresponder exatamente
  • O nome da pasta e o campo name devem usar kebab-case
  • Não se coloca README.md dentro da pasta do Skill

• O papel do frontmatter YAML

  • O frontmatter é o sinal principal para o Claude decidir quando carregar o skill
  • Campos mínimos obrigatórios:
    • name
    • description
  • A description deve necessariamente incluir:
    • O que o skill faz
    • Quando ele deve ser usado
    • Expressões concretas que o usuário provavelmente diria
  • Mais importante do que explicações técnicas é a linguagem sob a perspectiva do usuário

• Princípios de design do frontmatter

  • Manter dentro de 1024 caracteres
  • É proibido usar tags XML
  • Por motivos de segurança, há restrição ao uso de determinados nomes (claude, anthropic)
  • Metadados são opcionais, mas recomenda-se incluir versão e informações do autor

• Direção de design do corpo de SKILL.md

  • Fornecer instruções claras e executáveis em etapas
  • Apresentar exemplos junto com os resultados esperados
  • Incluir erros frequentes e formas de resolvê-los
  • Explicações excessivas devem ser separadas no diretório references

• O ponto central do Capítulo 2 é que Skills não devem ser tratados como um “conjunto de prompts”, mas como um artefato de design de workflow com intenção

Capítulo 3: Testes e melhoria iterativa (Testing and Iteration)

• Este capítulo foca no processo de elevar as Skills a um nível realmente confiável
• Mais do que escrever a skill em si, o essencial é validar quando ela é carregada, como é executada e como os resultados melhoram
• É importante ajustar a intensidade dos testes de acordo com o escopo de uso e o impacto

• Escolhendo o nível de teste

  • Os testes de Skills podem ser realizados em diferentes níveis, dependendo da qualidade exigida e do alcance da implantação

  • Testes manuais (Claude.ai)

    • Inserir consultas diretamente no Claude.ai para verificar o comportamento
    • Permite iteração rápida sem configuração adicional
    • Adequado para validar o design inicial e fazer correções rápidas

  • Testes baseados em script (Claude Code)

    • Automatizar casos de teste no ambiente Claude Code
    • Útil para testes de regressão quando as mudanças se acumulam
    • Adequado para skills usadas por equipes internas

  • Testes programáticos baseados em API

    • Executar automaticamente um conjunto de testes definido usando a Skills API
    • Permite comparação quantitativa e validação sistemática
    • Adequado para implantações em larga escala e ambientes corporativos
• Skills pequenas para uso interno e skills públicas não exigem os mesmos critérios de teste

• Abordagem recomendada: começar com uma tarefa difícil

  • Criadores de skills eficazes se concentram em uma única tarefa desafiadora e a aprimoram iterativamente
  • No momento em que o Claude consegue executar essa tarefa com estabilidade, extrai-se essa abordagem e ela é consolidada como uma Skill
  • Em vez de testes amplos, repetir um único caso com sinal forte proporciona aprendizado mais rápido
  • Só depois disso os testes são expandidos para casos variados

• Áreas centrais de teste

  • 1. Teste de gatilho

    • Objetivo: verificar se a skill é carregada automaticamente apenas nas situações apropriadas
    • Itens incluídos:
      • É acionada em solicitações claras
      • É acionada mesmo quando a formulação da solicitação muda
      • Não é carregada em solicitações irrelevantes
    • A qualidade do gatilho está diretamente ligada ao design do campo description

  • 2. Teste funcional

    • Objetivo: confirmar se a skill gera com precisão o resultado pretendido
    • Itens de validação:
      • Precisão do resultado gerado
      • Sucesso ou não das chamadas MCP
      • Comportamento de tratamento de erros
      • Resposta a edge cases
    • A avaliação não é baseada apenas em sucesso simples, mas na integridade do workflow completo

  • 3. Teste comparativo de desempenho

    • Objetivo: confirmar o efeito real de melhoria antes e depois do uso da skill
    • Itens de comparação:
      • Número de idas e vindas de mensagens
      • Ocorrência de falhas em chamadas MCP
      • Uso total de tokens
    • A skill não deve apenas provar que “funciona”, mas que “melhora o resultado”

• Testes e melhorias com o skill-creator

  • O skill-creator é uma meta-ferramenta que ajuda no design e no aprimoramento de skills
  • Principais funções:
    • Gerar rascunhos de skills com base em descrições em linguagem natural
    • Gerar automaticamente o formato de SKILL.md e o frontmatter
    • Detectar risco de gatilhos em excesso ou em falta
    • Sugerir casos de teste adequados ao objetivo
  • Não substitui testes de execução nem avaliação quantitativa

• Melhoria iterativa baseada em feedback

  • Skills não são entregáveis fixos, mas algo que deve ser refinado continuamente

  • Sinais de gatilho insuficiente

    • A skill não é carregada automaticamente
    • O usuário ativa a skill manualmente
    • Surge a pergunta “quando isso deve ser usado?”
    • Solução: adicionar expressões e termos específicos na description

  • Sinais de gatilho excessivo

    • A skill é carregada mesmo em perguntas irrelevantes
    • O usuário acaba desativando a skill
    • Surge confusão sobre o propósito
    • Solução: reduzir o escopo e adicionar gatilhos negativos

  • Sinais de problemas de execução

    • Falta de consistência nos resultados
    • Ocorrência de erros de MCP ou novas tentativas
    • Necessidade de intervenção do usuário para corrigir
    • Solução: esclarecer as instruções e reforçar o tratamento de erros

• Mensagem central da etapa de testes

  • Testar é o processo de validar não só a precisão da skill, mas também sua confiabilidade
  • O critério “a skill executa” não é suficiente
  • O critério final é: “o usuário consegue concluir tudo até o fim sem precisar dar a próxima instrução?”
• O Capítulo 3 é a etapa que transforma Skills de ferramenta experimental em ativo operacional de workflow

Capítulo 4: Distribuição e compartilhamento (Distribution and Sharing)

• Skills são o elemento que completa o valor dos conectores MCP, e mesmo com a mesma conexão de ferramentas, quando skills são fornecidas junto, é possível atingir valor mais rapidamente
• Do ponto de vista do usuário, há uma tendência de preferir conectores que incluam fluxos de trabalho prontos para execução imediata em vez de conectores que ofereçam apenas MCP
• Este capítulo resume o método de distribuição vigente em janeiro de 2026, a distribuição em nível organizacional, o uso via API e as estratégias operacionais recomendadas

• Modelo atual de distribuição (em janeiro de 2026)

  • Método de distribuição para usuários individuais

    • Baixar a pasta da Skill localmente
    • Se necessário, compactar a pasta inteira em um arquivo zip
    • Fazer upload no Claude.ai em Settings → Capabilities → Skills
    • Ou colocá-la diretamente no diretório skills do ambiente Claude Code
    • Após o upload, o próprio usuário precisa ativar a skill manualmente

  • Distribuição em nível organizacional

    • O administrador pode distribuir skills para todo o workspace
    • O recurso de distribuição em nível organizacional está disponível desde 18 de dezembro de 2025
    • Suporte a gerenciamento centralizado e atualizações automáticas
    • Adequado para impor ou manter de forma consistente fluxos de trabalho padrão dentro da organização

• Skills como padrão aberto

  • Agent Skills são publicadas como padrão aberto, assim como o MCP
  • O objetivo é que a mesma skill funcione em várias ferramentas de IA, sem depender de uma plataforma específica
  • Algumas skills podem aproveitar ativamente recursos de uma plataforma específica e, nesse caso, é possível indicar restrições de ambiente no campo compatibility
  • O padrão está sendo desenvolvido em colaboração com participantes do ecossistema

• Uso de Skills via API

  • Objetivo do uso de API

    • Adequado para cenários de uso programático como aplicações, pipelines de automação e sistemas de agentes
    • Em vez de uso manual pela UI, permite controlar skills no nível do sistema

  • Principais recursos

    • Consultar e gerenciar a lista de skills pelo endpoint /v1/skills
    • Especificar skills com o parâmetro container.skills ao fazer uma requisição à Messages API
    • Controle de versionamento e distribuição via Claude Console
    • Integração com o Claude Agent SDK para montar agentes customizados

  • Guia de escolha do ambiente de uso

    • Claude.ai / Claude Code:
      • Uso direto pelo usuário final
      • Testes manuais durante o desenvolvimento e iteração rápida
      • Fluxos de trabalho individuais e esporádicos
    • API:
      • Embutida em aplicações
      • Distribuição em produção em larga escala
      • Agentes e pipelines automatizados

  • Observações

    • Ao usar Skills via API, é necessário o Code Execution Tool beta
    • Pressupõe um ambiente de execução seguro

• Estratégia de distribuição recomendada

  • 1. Manter um repositório público no GitHub

    • A própria skill deve ser gerenciada como uma única pasta
    • Na raiz do repositório, fornecer um README voltado para pessoas
    • Recomenda-se incluir método de instalação, objetivo de uso e capturas de tela de exemplo
    • Dentro da pasta da Skill, não incluir README.md

  • 2. Integrar com a documentação do MCP

    • Apresentar a Skill junto na documentação do conector MCP
    • Explicar claramente o valor da combinação com Skill em comparação ao uso isolado do MCP
    • Fornecer um guia de início rápido

  • 3. Fornecer um guia de instalação

    • Especificar como baixar a skill
    • Instruções passo a passo para instalar no Claude.ai ou Claude Code
    • Incluir o procedimento para verificar a conexão com o servidor MCP
    • Fornecer exemplos simples de prompts de teste

• Princípios de posicionamento da skill

  • Explicar com foco no resultado, não na funcionalidade

    • Em vez de descrever a implementação interna ou a estrutura técnica, enfatizar o resultado que o usuário obtém
    • Colocar em destaque efeitos como economia de tempo, redução de erros e garantia de consistência

  • A combinação MCP + Skills é importante

    • MCP fornece acesso às ferramentas
    • Skills fornecem o conhecimento sobre como essas ferramentas devem ser usadas
    • Quando os dois elementos se combinam, a automação baseada em IA se completa
• Distribuição e compartilhamento não são apenas entrega, mas o processo de fazer com que o usuário entenda o valor da skill e consiga aproveitá-la imediatamente

Capítulo 5: Padrões e solução de problemas (Patterns and Troubleshooting)

• Este capítulo organiza padrões de design cuja eficácia foi comprovada repetidamente entre usuários iniciais de Skills e em casos de equipes internas, além de métodos para resolver problemas frequentes na operação real
• Os padrões apresentados não são normas, mas sim um conjunto de abordagens validadas, partindo do princípio de que devem ser escolhidos e combinados de acordo com o objetivo de cada skill
• A mensagem central não é “conectar ferramentas”, mas sim projetar o fluxo que resolve o problema

• Escolhendo a abordagem: centrada no problema vs. centrada na ferramenta

  • No design de Skills, é importante escolher uma entre duas perspectivas

  • Centrada no problema (Problem-first)

    • O usuário informa o resultado que deseja alcançar
    • A skill decide internamente quais ferramentas MCP usar e em que ordem chamá-las
    • Exemplo: “crie um workspace de projeto para mim” → a skill cuida de todas as chamadas de ferramenta
    • Adequada para experiências orientadas a resultado

  • Centrada na ferramenta (Tool-first)

    • O usuário já conhece a conexão MCP
    • A skill fornece conhecimento especializado sobre como usar bem essa ferramenta
    • Exemplo: como usar o MCP do Notion, orientação sobre o fluxo de trabalho ideal
    • Adequada para usuários especialistas e guias de ferramentas internas
• A maioria das skills se aproxima mais de um desses lados, e reconhecer isso com clareza influencia diretamente a qualidade do design

• Padrão 1: Orquestração de workflow sequencial

  • Adequado para casos em que várias etapas precisam ser executadas obrigatoriamente em uma ordem definida
  • Cada etapa depende do resultado da etapa anterior
  • Pode incluir validação por etapa e instruções de rollback em caso de falha
  • Adequado para tarefas como onboarding, criação de contas e configuração de assinaturas

• Padrão 2: Colaboração entre múltiplos MCPs

  • Para casos em que vários serviços (MCPs) precisam ser usados em sequência para obter um único resultado
  • Separe os MCPs por etapa e defina claramente o fluxo de passagem de dados
  • A validação é obrigatória antes de avançar para a próxima etapa
  • Adequado para workflows complexos como design → armazenamento → criação de tarefa → notificação

• Padrão 3: Refinamento iterativo (Iterative Refinement)

  • Adequado para tarefas em que a qualidade melhora significativamente por meio de iterações, mais do que com o resultado inicial
  • Projete explicitamente o loop de geração de rascunho → validação → correção → revalidação
  • É preciso definir com clareza os critérios de qualidade e as condições de encerramento das iterações
  • Eficaz para geração de relatórios e melhoria da qualidade de documentos

• Padrão 4: Seleção de ferramentas com base em reconhecimento de contexto

  • Usado quando, mesmo com o mesmo objetivo, a ferramenta ideal muda conforme o contexto
  • São necessários critérios de decisão claros, como tamanho do arquivo, tipo e necessidade de colaboração
  • Explique ao usuário o motivo da escolha para garantir confiabilidade
  • Adequado para fluxos de armazenamento, gestão de documentos e versionamento de código

• Padrão 5: Inteligência especializada embutida no domínio

  • Skills que vão além da simples chamada de ferramentas e incorporam conhecimento e regras especializados
  • A etapa de julgamento e validação antes da execução da tarefa é o ponto central
  • Registre todo o processo de decisão para permitir trilha de auditoria
  • Adequado para áreas de alto risco, como finanças, compliance e segurança

• Guia de solução de problemas

  • Falha no upload

    • Ocorre quando o nome do arquivo SKILL.md não está exato
    • Erros de formato como ausência do delimitador YAML (---) ou aspas não fechadas são causas comuns
    • O upload é rejeitado se o campo name contiver letras maiúsculas ou espaços

  • Quando a skill não é acionada

    • Ocorre quando a description é abstrata demais ou não reflete a forma como o usuário se expressa
    • É preciso revisá-la para incluir frases que um usuário real provavelmente diria
    • É possível depurar perguntando ao Claude “quando esta skill deve ser usada?”

  • Quando a skill é acionada em excesso

    • A causa é uma description com escopo excessivamente amplo
    • Adicione gatilhos negativos (Do NOT use when…)
    • Diferencie claramente o que deve ser processado e o que deve ser excluído

  • Falha na chamada de MCP

    • Verifique o estado da conexão com o servidor MCP
    • Confira as credenciais de autenticação (chave de API, token OAuth)
    • Isole a causa do problema chamando o MCP sozinho, sem a skill
    • Verifique se maiúsculas e minúsculas no nome da ferramenta estão corretas

  • Quando as instruções não são seguidas corretamente

    • Isso ocorre quando as instruções são longas demais ou o essencial fica escondido
    • Coloque as condições importantes no topo e reforce-as repetidamente
    • Em vez de expressões ambíguas, use uma lista de condições verificáveis
    • Para validações importantes, implementar em script é mais confiável

  • Queda de desempenho causada por contexto muito grande

    • Ocorre quando o SKILL.md é excessivamente grande
    • Separe a documentação detalhada em references
    • Se houver skills demais ativadas ao mesmo tempo, recomenda-se reduzir esse número
    • Ativar simultaneamente mais de 20 a 50 skills pode causar degradação de desempenho
• “Uma skill não é um artefact criado uma vez e encerrado, mas sim um objeto operacional que amadurece por meio da escolha de padrões e do refinamento iterativo”

[kaydash]

A Anthropic é boa demais, de verdade

[pluto]

de verdade