Claude Skills, explicado: o que elas realmente são, e a letra miúda sobre planos em que duas páginas da própria Anthropic discordam

O que uma Skill realmente é, mecanicamente

Tirando o marketing, uma Skill é um diretório com um arquivo obrigatório. O SKILL.md traz um frontmatter em YAML (no mínimo um name e uma description) seguido de instruções em Markdown. Ao redor dele, opcionalmente, ficam uma pasta scripts/ de código executável, uma pasta references/ de documentação que a Claude só abre quando precisa, e uma pasta assets/ de templates, fontes ou ícones para o que a skill produzir. A própria documentação da plataforma da Anthropic descreve o mecanismo de forma quase literal: o modelo roda o equivalente a bash: cat pdf-processing/SKILL.md. É uma leitura do sistema de arquivos, não um primitivo especial de API.

O que torna isso diferente de simplesmente colar um system prompt longo é a divulgação progressiva, e ela tem custos de token reais e documentados, não uma garantia vaga. A documentação da plataforma da Anthropic divide isso em três níveis: o Nível 1, o name e a description da skill, carrega automaticamente em toda conversa a um custo de cerca de 100 tokens por skill instalada. O Nível 2, o corpo completo do SKILL.md, só carrega quando a Claude julga que seu pedido corresponde à descrição, e a Anthropic limita isso a menos de 5.000 tokens (seu guia separado de construção de skills expressa o mesmo conselho como menos de 5.000 palavras) especificamente para conter esse custo. O Nível 3, quaisquer arquivos de referência ou scripts empacotados, só carrega se a Claude realmente os abrir, e o código-fonte de um script nunca entra na janela de contexto, só o que ele imprime no stdout quando roda. O próprio guia de 32 páginas da Anthropic sobre construção de skills usa uma analogia de cozinha que vale citar diretamente: "o MCP oferece a cozinha profissional: acesso a ferramentas, ingredientes e equipamentos. As Skills oferecem as receitas: instruções passo a passo."

Onde as Skills realmente funcionam, e o plano que você precisa

Essa é a parte que vale a pena ser precisa, porque duas páginas da própria Anthropic descrevem isso de forma diferente. A central de ajuda para consumidores da Anthropic afirma: "As skills estão disponíveis para usuários nos planos Free, Pro, Max, Team e Enterprise. Este recurso exige que a execução de código esteja ativada." Já a documentação da plataforma para desenvolvedores da Anthropic, descrevendo o mesmo recurso subjacente em termos mais técnicos, diz que as skills personalizadas estão "disponíveis nos planos Pro, Max, Team e Enterprise com execução de código ativada", e acrescenta que, no claude.ai, elas "não são compartilhadas em toda a organização e não podem ser gerenciadas centralmente por administradores". O Free está presente numa frase e ausente na outra.

Lendo as duas juntas, a explicação provável é que as quatro skills de documento pré-construídas da Anthropic, geração de PDF, Word, Excel e PowerPoint, funcionam automaticamente para todo mundo, inclusive usuários do plano Free, enquanto enviar e rodar sua própria skill personalizada exige Pro ou superior com execução de código ativada. Se você está no plano Free e uma skill não aparece onde você esperava, esse é o motivo provável, não um bug.

Surface              Pre-built doc skills    Custom skills              Sharing model
----------------------------------------------------------------------------------------------
claude.ai              Yes, all plans          Pro/Max/Team/Enterprise    Per-user, no org
                        automatically           + code execution on       admin management
Claude Code             No (own reference       Yes, filesystem-based,    Personal (~/.claude),
                        skill ships instead)    no upload needed          project, or plugin
API                     Yes, via skill_id in    Yes, via /v1/skills       Workspace-wide, all
                        the container param     upload endpoints          members share access
Cowork / cloud          N/A                     Loads skills enabled on   Doesn't read your
sessions                                        your claude.ai account,  local ~/.claude/skills
                                                 synced at session start  unless committed to it
Enterprise (org-wide)   Inherits API behavior   Admins can push skills    Org-wide, automatic
                                                 workspace-wide since     updates
                                                 18 Dec 2025

A linha que vale a pena planejar em torno é a falta de sincronização. Uma skill enviada pelo painel de Configurações do claude.ai não fica visível para chamadas de API, e uma skill enviada pelo endpoint /v1/skills da API não aparece no claude.ai. As skills do Claude Code são arquivos simples na sua máquina, em ~/.claude/skills/ para uso pessoal ou .claude/skills/ dentro de um repositório para uma skill de projeto compartilhada, e uma sessão na nuvem do Cowork só enxerga as que foram commitadas naquele repositório, não o que está no seu notebook. Se você construir uma boa skill, espere ter que instalá-la de novo em cada superfície que você realmente usa, não uma vez só para todas.

Como instalar e usar uma de fato hoje

• No claude.ai: Settings → Capabilities (chamado de "Features" em algumas contas) → Skills, e então "Browse skills" para abrir o diretório da própria Anthropic, ou "Upload a skill" para adicionar uma pasta compactada que você construiu ou baixou, e ativar o interruptor.
• No Claude Code: crie ~/.claude/skills/<nome>/SKILL.md para uma skill pessoal, detectada ao vivo sem precisar reiniciar, ou .claude/skills/<nome>/SKILL.md dentro de um repositório para compartilhar com sua equipe via controle de versão. As skills oficiais da Anthropic se instalam pelo marketplace de plugins: /plugin marketplace add anthropics/skills, depois /plugin install document-skills@anthropic-agent-skills. Invoque uma skill explicitamente com /nome-da-skill, ou deixe a Claude carregá-la automaticamente quando seu pedido corresponder à descrição.
• Pela API: referencie as skills pré-construídas da Anthropic por skill_id (pdf, docx, pptx, xlsx) dentro do parâmetro container de uma chamada da Messages API junto com a ferramenta de execução de código, ou envie uma personalizada pelos endpoints /v1/skills do Console para todo o workspace compartilhar.
• Construindo a sua própria: use a própria skill skill-creator, a meta-skill da Anthropic para construir skills. Descreva em linguagem simples o fluxo de trabalho que você repete com frequência, e ela monta um SKILL.md corretamente formatado, sugere frases de gatilho para a descrição, e sinaliza formulações vagas demais para disparar de forma confiável. O próprio guia da Anthropic descreve isso como um processo de 15 a 30 minutos, uma vez que você já sabe quais são suas duas ou três tarefas mais repetidas.

Skills vs MCP vs Custom GPTs vs Gemini Gems

A comparação que realmente esclarece o que é uma skill é a que a própria Anthropic traça em relação ao seu MCP (Model Context Protocol): "O MCP conecta a Claude a serviços externos e fontes de dados. As Skills fornecem conhecimento procedural, instruções sobre como completar tarefas ou fluxos de trabalho específicos. Você pode usar os dois juntos: as conexões MCP dão à Claude acesso a ferramentas, enquanto as skills ensinam a Claude a usar essas ferramentas de forma eficaz." Mecanicamente, o MCP é um protocolo que expõe novas ferramentas, capacidades que a Claude genuinamente não conseguiria executar de outra forma, como chamar uma API privada. Uma Skill é conteúdo de prompt mais código opcional que diz à Claude como sequenciar chamadas de ferramentas que ela já consegue fazer. Esse é o núcleo honesto do argumento cético coberto abaixo: uma skill sem script e sem conexão MCP por trás não consegue fazer nada que um prompt avulso suficientemente detalhado já não conseguisse fazer. Seu valor está no empacotamento e na reutilização eficiente em termos de contexto, não em capacidade nova.

                 Claude Skills             MCP                      Custom GPTs (OpenAI)   Gemini Gems
-----------------------------------------------------------------------------------------------------------
Grants new        No - packages prompting   Yes - exposes new        No - system prompt +    No - saved
capability?       Claude already has        tools/API access         optional Actions        persona/prompt
Invocation        Automatic, matched to     Always-on connection     Manual - pick the GPT   Manual - switch
                  your request's wording    once configured          from a list             into the Gem
Portable across   Yes in spirit (open       Yes, it's a protocol,    No - ChatGPT only       No - Gemini
tools?            agentskills.io standard), works with any MCP                                ecosystem only
                  but doesn't sync accounts client
Entry cost        Pro+ for custom skills,   Varies by server, often  ChatGPT Plus/Team/       Included with
                  code execution required   free/self-hosted         Enterprise               most Gemini plans
Instruction       ~5,000 words recommended  N/A - it's a tool        Knowledge files, no      Reportedly capped
length limit      per SKILL.md              connection, not a prompt hard length limit stated ~4,000 characters

Aquela última linha sobre os Gemini Gems merece uma ressalva: ela vem de comparações escritas por terceiros, não de uma ficha técnica publicada pelo Google, então trate o número exato como uma aproximação relatada, não como um limite confirmado.

Isso é só prompting chique? O argumento cético

A crítica pública mais substancial é a da Sibylline Software, "Claude Skills Considered Harmful", e vale a pena ler além do título, porque o autor depois voltou atrás em parte dela. O argumento central: as skills prendem seus fluxos de trabalho documentados ao runtime da própria Anthropic de um jeito que torna migrar para outro lugar ou auditar o comportamento mais difícil do que seria com um arquivo simples, e, citando diretamente, "você não tem visibilidade sobre por que uma Skill foi disparada ou como ela influencia o raciocínio do modelo", concluindo que as Skills eram "uma micro-otimização projetada para prender clientes, disfarçada de inovação". A alternativa proposta era uma hierarquia simples e versionada de arquivos README.md que qualquer modelo pudesse ler, auditável por humanos e não presa ao runtime de um único fornecedor.

O texto traz seu próprio adendo, adicionado depois que a Anthropic abriu o formato: "Desde que este artigo foi escrito, a Anthropic tornou a especificação de skill aberta, e o Codex implementou suporte a elas. Ainda acho que as skills são supervalorizadas, mas elas não são ativamente prejudiciais." O argumento de aprisionamento a um fornecedor era a parte estrutural da crítica original, e foi substancialmente enfraquecido quando o formato SKILL.md virou um padrão aberto (agentskills.io) que outras ferramentas de agente, não só a Claude, começaram a implementar. O que sobrevive à retratação é o ponto mais restrito, e ainda válido, da seção acima: uma Skill sem código e sem acesso a ferramentas por trás é prompting carregado condicionalmente, não uma capacidade nova, e essa é uma limitação que o próprio enquadramento da Anthropic implicitamente reconhece em vez de contestar.

Skills reais que vale a pena conhecer, nomeadas

A Anthropic entrega quatro skills pré-construídas por padrão, geração de PDF, Word, Excel e PowerPoint, ou seja, saída em formato nativo de verdade, não Markdown formatado para parecer um documento. Além dessas, a skill-creator (a meta-skill para construir skills, que vale a pena instalar primeiro) e a frontend-design (prompting de qualidade de interface para tarefas de código) também são da própria Anthropic. A API também entrega uma skill de referência open-source que mantém o uso do SDK atualizado em oito linguagens.

A camada da comunidade é maior e mais específica do que as páginas de marketing sugerem. O repositório awesome-claude-skills da ComposioHQ, capturado em print acima com 74,5 mil estrelas e 8,6 mil forks hoje, um sinal real e verificável de quanta atenção de desenvolvedores esse ecossistema tem, lista skills nomeadas e atribuídas, incluindo um Changelog Generator que transforma commits do git em notas de lançamento voltadas ao usuário, um MCP Builder que monta servidores MCP em Python ou TypeScript a partir de uma descrição em linguagem simples, uma biblioteca de 59 skills chamada Brand Build Skills cobrindo todo o ciclo de vida de um site, do SEO à implantação, e o Sentry Automation, uma skill construída por um parceiro que gerencia issues, eventos, projetos, releases e alertas do Sentry diretamente pela Claude. Uma skill relacionada, mas separada, de outro parceiro, o Sentry Code Review, listada no próprio diretório de plugins do Sentry em vez de neste repositório, usa o servidor MCP do Sentry para analisar e corrigir automaticamente bugs em pull requests do GitHub usando dados reais de erro de produção.

Uma fonte mais seletiva é a do desenvolvedor Suraj Khaitan, "I Tried 100 Claude Skills", que pontuou cada skill testada numa rubrica de cinco eixos, sendo um deles a postura de segurança: se a skill faz chamadas de rede surpreendentes ou entrega binários opacos. A taxa de eliminação relatada por ele, no seu lote pessoal de cerca de 100 skills, não um número do setor como um todo, foi de cerca de 70% pontuando abaixo de 3 em 5 em mais de dois eixos. Suas escolhas favoritas: PDF ("a skill que me converteu", graças a um parser embutido que evita campos de formulário alucinados), DOCX/PPTX/XLSX, skill-creator, que ele recomenda instalar "antes de qualquer outra" skill, mcp-builder, e webapp-testing, uma skill de automação de navegador via Playwright para testar de ponta a ponta um app web.

O que quebra, e o alerta de segurança que todo mundo repete

A própria documentação da plataforma da Anthropic declara o risco sem rodeios, não como texto padrão: "Use Skills só de fontes confiáveis: as que você mesmo criou ou obteve da Anthropic... uma Skill maliciosa pode direcionar a Claude a invocar ferramentas ou executar código de formas que não correspondem ao propósito declarado da Skill." Ela sinaliza especificamente as skills que buscam URLs externas como de risco mais alto, já que o conteúdo buscado pode carregar instruções injetadas, e alerta que uma skill legítima pode se tornar arriscada depois se uma dependência externa da qual ela depende mudar por baixo dos panos. Os testes independentes de Khaitan ecoam a mesma conclusão de fora: ele recomenda auditar cada script empacotado antes de instalar, fixar versões de dependências, isolar a execução em sandbox, e tratar "selos de parceiro como marketing, não garantia", não um substituto para realmente ler o código.

Contas Enterprise recebem uma mitigação parcial: a Anthropic oferece varredura de conteúdo de skills, mas só para envios pelo claude.ai e pelo Cowork, não para skills enviadas pela API ou pelo Console. Uma skill personalizada enviada para todo o workspace pela API não passa por essa varredura de jeito nenhum.

• O custo de contexto se acumula com o volume. O próprio guia da Anthropic alerta que, além de cerca de 20 a 50 skills ativadas simultaneamente, a qualidade das respostas degrada na prática, e recomenda desativar skills que você não precisa no momento em vez de deixar tudo ligado.
• Disparo insuficiente e disparo em excesso são modos de falha nomeados, com correções prescritas. Uma skill que nunca dispara precisa de uma description mais afiada, com mais das frases que os usuários realmente digitam; uma skill que dispara demais precisa de gatilhos negativos explícitos ("NÃO use isto para...") adicionados ao mesmo campo.
• O conteúdo da skill não atualiza no meio da sessão. Edite um arquivo de skill depois que o Claude Code já o carregou na conversa atual, e você vai precisar invocá-lo de novo explicitamente para a mudança fazer efeito.
• Os nomes exatos de arquivo e os nomes reservados importam. O SKILL.md precisa ser escrito exatamente assim, com diferenciação de maiúsculas e minúsculas, ou o próprio guia de solução de problemas da Anthropic diz que você vai receber "Could not find SKILL.md in uploaded folder." Os nomes de skill precisam estar em kebab-case, sem espaços ou maiúsculas, e qualquer nome contendo "claude" ou "anthropic" é rejeitado de cara por ser reservado.

Quando não vale a pena se incomodar com Skills

• Se a tarefa é genuinamente pontual. Empacotar um prompt numa skill só compensa quando, de outra forma, você ficaria redigitando as mesmas instruções em várias conversas.
• Se o que você realmente precisa é capacidade nova, não prompting melhor organizado. Isso é trabalho de um servidor MCP, não de uma skill. Instalar uma skill não vai dar à Claude acesso a um sistema que ela já não conseguisse alcançar.
• Se você está no plano Free e quer uma skill personalizada. Pela discrepância de controle por plano acima, a suposição mais segura é que envios personalizados exigem Pro ou superior com execução de código ativada, mesmo que uma página da Anthropic sugira o contrário.
• Se você não pode ou não vai ler o script empacotado da skill antes de instalá-la. A própria orientação de segurança da Anthropic e todo testador independente que realmente auditou skills da comunidade concordam nesse ponto, sem exceção.

Perguntas frequentes

O que são as Claude Skills?

Uma Skill é uma pasta contendo um arquivo de instruções SKILL.md obrigatório, além de scripts opcionais, documentos de referência e templates. A Claude carrega o nome e a descrição da skill automaticamente em toda conversa, e só carrega as instruções completas quando um pedido corresponde a ela, um mecanismo chamado divulgação progressiva.

As Claude Skills custam extra, e de qual plano eu preciso?

As skills de documento pré-construídas da Anthropic (PDF, Word, Excel, PowerPoint) funcionam em todos os planos, inclusive no Free. Skills personalizadas que você constrói ou baixa exigem Pro, Max, Team ou Enterprise com execução de código ativada, segundo a documentação da plataforma para desenvolvedores da Anthropic, mesmo que o texto da central de ajuda para consumidores seja menos preciso nesse ponto.

Qual é a diferença entre uma Skill e um servidor MCP?

O MCP conecta a Claude a ferramentas e dados externos que ela não conseguiria alcançar de outra forma, uma capacidade genuinamente nova. Uma Skill empacota instruções sobre como usar capacidades que a Claude já tem, e não concede nenhuma capacidade nova por si só, a menos que empacote um script ou uma conexão MCP.

É seguro instalar Claude Skills a partir do GitHub?

Só de fontes que você confia o bastante para ter auditado. A própria documentação da Anthropic alerta que uma skill maliciosa pode direcionar a Claude a rodar código que não corresponde ao seu propósito declarado, especialmente skills que buscam URLs externas. Testadores independentes que experimentaram dezenas de skills da comunidade recomendam ler cada script empacotado antes de instalar, já que um número de estrelas no GitHub ou um selo de parceiro não é garantia de segurança.

Quantas Claude Skills eu posso ter instaladas ao mesmo tempo?

A própria orientação da Anthropic aponta cerca de 20 a 50 skills ativadas simultaneamente como um teto flexível antes de a qualidade das respostas degradar por causa da carga de contexto. Desative skills que você não está usando ativamente em vez de deixar tudo ligado.

As Claude Skills funcionam no ChatGPT ou no Gemini?

Não, as Skills são um produto específico da Claude, mas o formato SKILL.md subjacente é um padrão aberto (agentskills.io) que outras ferramentas de agente, incluindo alguns produtos que não são da Anthropic, começaram a adotar de forma independente.