Claude Skills: O guia de 32 páginas da Anthropic, decodificado
Há oito meses venho escrevendo as mesmas instruções para o Claude. Toda segunda-feira de manhã, o mesmo prompt de planejamento de sprint. Toda ligação com clientes, o mesmo template de notas de reunião. Todo deploy, a mesma checklist colada na janela de chat como uma espécie de Dia da Marmota digital.
Então a Anthropic lançou um guia de 32 páginas sobre algo chamado Claude Skills — e em uma única tarde, apaguei todos os prompts que tinha salvos.
Não arquivados. Apagados. Porque uma vez que você entende o que os Skills realmente são, voltar a copiar e colar prompts parece voltar a escrever cartas depois de descobrir o e-mail. O conceito é enganosamente simples: você ensina algo ao Claude uma vez, dentro de uma pasta com um arquivo markdown e alguns scripts opcionais, e ele simplesmente sabe como fazer aquilo dali em diante. Sem reexplicar. Sem "aqui está meu guia de estilo novamente." Sem "lembre-se, usamos Tailwind, não Bootstrap."
Um arquivo SKILL.md. Um pouco de YAML no topo. Pronto.
Mas — e é isso que quero aprofundar — o guia em si é tanto brilhante quanto frustrante. Brilhante porque o framework que ele apresenta é genuinamente poderoso. Frustrante porque os detalhes de implementação mais importantes estão enterrados sob camadas de documentação polida, e algumas das lições mais difíceis de aprender sobre como fazer os Skills realmente funcionarem são mencionadas de passagem ou nem são mencionadas.
Passei três dias lendo o guia, construindo Skills, quebrando Skills e reconstruindo-os. O que segue é tudo que eu gostaria que alguém tivesse me dito antes de começar — as partes que a Anthropic acertou, as partes que passaram batido, e os cinco padrões que realmente importam quando você tira a linguagem de marketing.
O conceito que faz tudo se encaixar
Este é o modelo mental que finalmente fez o Claude Skills fazer sentido para mim, e não é o que a Anthropic apresenta primeiro.
Você provavelmente já conhece o MCP — o Model Context Protocol que permite ao Claude se conectar com ferramentas externas como Notion, Linear, Figma, GitHub, Slack, e basicamente qualquer coisa com uma API. MCP é sobre acesso. Ele dá ao Claude as chaves das suas ferramentas. Abrir a porta, entrar, olhar ao redor.
Skills são diferentes. Skills são sobre julgamento.
Pense desta forma. Você contrata um novo desenvolvedor e dá a ele acesso de administrador a todo o seu stack — sua ferramenta de gestão de projetos, seu pipeline de CI/CD, seu sistema de design, seus canais de comunicação. Ele tecnicamente pode mexer em tudo. Mas não conhece as convenções do seu time. Não sabe que o cálculo de velocidade do sprint exclui bugs de menos de dois story points. Não sabe que as entregas de design sempre passam por um fluxo específico de Figma-para-Linear com anotações de acessibilidade obrigatórias. Não sabe que os anúncios de deploy seguem um formato particular em um canal específico do Slack.
Acesso sem julgamento cria caos. MCP dá acesso ao Claude. Skills dão julgamento ao Claude.
Essa distinção é o guia inteiro em uma única frase. Todo o resto — o frontmatter YAML, a estrutura de pastas, os cinco padrões, os conselhos de depuração — são detalhes de implementação pendurados nessa ideia central.
Uma vez que isso fez clique para mim, parei de pensar nos Skills como "prompts sofisticados" e comecei a pensar neles como conhecimento institucional capturado em código. E essa reformulação mudou como construí cada um deles.
A questão prática, claro, é como você captura esse conhecimento em um formato que o Claude possa usar. O guia dedica muitas páginas a isso, e parte é genuinamente útil. Mas há um atalho que ninguém te conta, e vou chegar nele depois de passarmos pela mecânica.
O que realmente está na pasta — E o que cada parte faz
Um Claude Skill vive em uma pasta. No mínimo, essa pasta contém um arquivo: SKILL.md. Só isso. Um arquivo markdown, e você tem um Skill funcional.
No topo desse arquivo markdown fica o frontmatter YAML — o bloco de metadados entre traços triplos que diz ao Claude o que este Skill é, o que ele faz e, criticamente, quando ativá-lo. O resto do arquivo contém as instruções reais: como realizar a tarefa, quais padrões seguir, quais ferramentas usar e quais armadilhas evitar.
Opcionalmente, você pode adicionar scripts, documentos de referência e templates à pasta. Um PDF de guia de estilo. Um script bash que executa linting. Um schema JSON para as respostas da sua API. O Claude vai referenciá-los ao executar o Skill.
Aqui está um exemplo mínimo — um Skill que gera relatórios de status semanais para meus projetos:
---
name: weekly-status-report
description: >
Generates a formatted weekly status report by pulling data
from Linear and GitHub. Trigger when user asks for a status
report, weekly update, or progress summary.
---
## Gerador de Relatórios de Status Semanais
### O que este Skill faz
Produz um relatório de status semanal conciso cobrindo trabalho concluído,
itens em andamento, bloqueadores e prioridades da próxima semana.
### Fontes de dados
1. Buscar issues concluídas no Linear para o sprint atual
2. Buscar PRs mergeados no GitHub dos últimos 7 dias
3. Buscar bloqueadores abertos marcados com a label "blocked" no Linear
### Formato do relatório
- **Resumo** (2-3 frases, maiores conquistas e riscos)
- **Concluído** (lista com marcadores com referências a tickets)
- **Em andamento** (lista com marcadores com estimativas de percentual)
- **Bloqueadores** (lista com marcadores com responsável e idade em dias)
- **Próxima semana** (top 3 prioridades)
### Regras de estilo
- Sem jargão — isso vai para stakeholders, não engenheiros
- Iniciar cada seção com o item de maior impacto
- Bloqueadores devem incluir quem é responsável pela resolução
- Manter o tamanho total abaixo de 500 palavras
Este é um Skill completo. Quando peço ao Claude "me dê a atualização de status desta semana", ele reconhece o trigger do campo de descrição, carrega o Skill, se conecta ao Linear e GitHub via MCP, e produz um relatório seguindo meu formato e regras de estilo exatos.
Sem engenharia de prompts. Sem lembrar onde salvei o template. O conhecimento vive no Skill, e o Claude sabe quando recorrer a ele.
Mas aqui está a parte que o guia enterra em uma barra lateral que merece estar na página um: o campo de descrição no seu frontmatter YAML é a linha mais importante que você vai escrever. Erre nisso e nada mais importa.
As duas linhas que definem o sucesso ou fracasso do seu Skill
Perdi quatro horas com isso. Quatro horas construindo um Skill perfeitamente detalhado que o Claude nunca ativou. As instruções eram claras. O formato era preciso. Os documentos de referência eram abrangentes. E toda vez que pedia ao Claude para fazer o que o Skill foi projetado para fazer, ele simplesmente... usava seu conhecimento geral. Ignorava o Skill completamente.
O problema era meu campo de descrição.
Minha descrição original dizia: "Helps with code review processes." Seis palavras. Vagas. Passivas. O Claude não tinha ideia de quando ativá-lo porque "helps with code review processes" poderia significar literalmente qualquer coisa.
Reescrevi: "Performs structured code review on pull requests. Trigger when user shares a PR link, asks for code review, requests a PR review, or pastes a diff. Checks for security vulnerabilities, performance issues, naming conventions per team standards, and test coverage gaps."
Começou a funcionar imediatamente. Toda vez.
O padrão que descobri por tentativa e erro — e o guia insinua isso mas não diz com clareza suficiente — é que sua descrição precisa de três coisas:
1. O que faz (verbo ativo, resultado específico): "Generates weekly reports" não "Helps with reporting."
2. Quando ativar (frases de ativação explícitas): "Trigger when user asks for X, Y, or Z." Liste as palavras e frases reais que um humano usaria. Não seja esperto. Seja literal.
3. O que cobre (limites do escopo): "Checks for A, B, C, and D." Isso diz ao Claude o que está dentro do domínio do Skill e, por implicação, o que não está.
O campo name também importa — use kebab-case, sem espaços, e seja descritivo. weekly-status-report supera report-v2 supera wsr. O Claude usa o nome como um sinal adicional para correspondência, então nomes descritivos melhoram a precisão de ativação.
Voltei e reescrevi as descrições de todos os sete Skills que havia construído. Seis deles começaram a ativar corretamente imediatamente. O sétimo precisou de mais uma rodada de refinamento — descobri que minhas frases de ativação se sobrepunham com outro Skill, e o Claude estava ficando confuso sobre qual carregar.
O que me leva a um problema que o guia não aborda de forma alguma: o que acontece quando Skills entram em conflito. Mais sobre isso em um minuto. Primeiro, os três casos de uso para os quais a Anthropic projetou este sistema — porque entender os casos de uso pretendidos muda como você pensa em construir Skills.
Três casos de uso — E o que a Anthropic subestima
O guia divide Claude Skills em três aplicações principais. Cada uma resolve um problema genuinamente diferente, e confundi-los é um erro que cometi no início.
Caso de uso 1: Criação de documentos
Esta é a aplicação mais direta. Você tem um tipo específico de documento — uma apresentação, uma especificação técnica, uma proposta para cliente, um brief de design — que precisa seguir padrões consistentes toda vez. Fontes, estrutura, tom, seções obrigatórias, frases proibidas. Em vez de colar um guia de estilo em cada conversa, você codifica uma vez em um Skill.
Construí um para propostas de clientes que inclui nossos níveis de preços, linguagem padrão de escopo, avisos legais obrigatórios e regras de formatação. O que costumava levar 20 minutos de elaboração de prompts por proposta agora leva uma frase: "Escreva uma proposta para [cliente] cobrindo [escopo]." O Skill cuida de todo o resto.
Caso de uso 2: Automação de fluxos de trabalho
É aqui que os Skills começam a devolver tempo de verdade. Processos de múltiplas etapas que precisam acontecer da mesma forma toda vez — planejamento de sprints, checklists de deploy, sequências de onboarding, procedimentos de resposta a incidentes.
Meu Skill de planejamento de sprint é o que mais me orgulho. Ele se conecta ao Linear para buscar o status atual do projeto, analisa nossa velocidade nos últimos três sprints, identifica itens que ficam sendo adiados, sugere prioridades baseadas na proximidade de prazos e cadeias de dependência, e cria os tickets de sprint reais com pontos estimados. Um processo que costumava consumir 90 minutos da minha segunda-feira de manhã agora acontece em cerca de quatro minutos, comigo revisando e aprovando o resultado em vez de gerá-lo do zero.
A chave para Skills de fluxo de trabalho: você precisa ser explícito sobre a ordem das operações e a lógica de decisão em cada etapa. "Analisar a velocidade" é vago demais. "Calcular a média de story points concluídos por sprint nos últimos 3 sprints, excluindo sprints com menos de 8 dias. Se a velocidade estiver caindo por 2+ sprints consecutivos, sinalizar isso no resultado do planejamento com a queda percentual" — é disso que o Claude precisa.
Caso de uso 3: Aprimoramento de MCP
Este é o caso de uso que mais empolga a Anthropic, e honestamente, é o que acho que eles subestimam o potencial. O aprimoramento de MCP significa sobrepor expertise de domínio ao acesso a ferramentas. Seu Skill não apenas usa o Figma — ele conhece seu sistema de design, suas convenções de nomenclatura de componentes, seus requisitos de acessibilidade e o fluxo específico para entregar designs para a engenharia.
Construí um Skill de entrega de design para desenvolvimento que busca os últimos designs do Figma, extrai as especificações dos componentes, mapeia-os para nossa biblioteca existente de componentes React, identifica lacunas onde novos componentes são necessários, cria tickets no Linear para o trabalho de engenharia com critérios de aceitação extraídos das especificações de design, e posta um resumo no nosso canal de desenvolvimento no Slack.
Seis ferramentas diferentes. Um Skill. Uma frase de ativação: "Processe os novos designs."
Isto é o que a Anthropic subestima sobre este caso de uso: o valor composto. Toda vez que um especialista de domínio no seu time revisa o resultado do Skill e diz "na verdade, também precisamos verificar X antes da entrega", você adiciona essa verificação ao arquivo SKILL.md. Ao longo de semanas e meses, o Skill acumula conhecimento institucional que de outra forma viveria apenas nas cabeças das pessoas. Ele se torna um documento vivo de como seu time realmente trabalha — não como as ferramentas foram projetadas para funcionar, mas como suas pessoas usam essas ferramentas no seu contexto específico.
Isso não é automação. É memória organizacional com capacidade de execução. E não acho que a maioria dos times tenha compreendido o quão poderoso isso é.
Agora — os cinco padrões que realmente estruturam como você constrói essas coisas.
Cinco padrões que cobrem 90% dos Skills do mundo real
O guia apresenta cinco "padrões comprovados" para estruturar Skills. Depois de construir onze Skills em três projetos, eu diria que esses padrões são genuínos — não são categorias de marketing. Cada um resolve um problema estruturalmente diferente, e tentar forçar um Skill no padrão errado cria bugs sutis difíceis de diagnosticar.
Padrão 1: Fluxo de trabalho sequencial
Os passos acontecem em uma ordem fixa. O passo 2 depende do resultado do passo 1. O passo 3 depende do passo 2. Sem ramificações, sem condicionais — apenas um pipeline confiável.
Ideal para: procedimentos de deploy, checklists de conformidade, sequências de onboarding, scripts de migração de dados.
O detalhe chave que o guia acerta: numere seus passos explicitamente e inclua critérios de validação entre passos. "Antes de prosseguir para o passo 3, verificar que o passo 2 produziu [resultado específico]. Se não, repetir o passo 2 com [abordagem alternativa]."
Padrão 2: Coordenação Multi-MCP
O fluxo de trabalho abrange múltiplos serviços externos. Figma para Linear para Slack. GitHub para Jira para Confluence. O Skill orquestra o fluxo de dados entre ferramentas que não se comunicam nativamente.
Ideal para: fluxos de trabalho entre ferramentas, entregas de design, gestão de releases, notificações entre equipes.
Meu maior aprendizado aqui: inclua instruções explícitas de transformação de dados entre as chamadas de ferramentas. O formato que o Figma exporta especificações de componentes não é o formato que o Linear aceita para descrições de tickets. Seu Skill precisa especificar exatamente como reformatar os dados à medida que se movem entre ferramentas.
Padrão 3: Refinamento iterativo
Gerar resultado, validar contra critérios, melhorar, validar novamente. O Skill inclui seu próprio ciclo de qualidade em vez de produzir um resultado de passagem única.
Ideal para: geração de relatórios, criação de conteúdo, revisão de código onde você quer cobertura abrangente, qualquer resultado que se beneficie de autocrítica.
Uso esse padrão para meu Skill de propostas para clientes. Primeiro rascunho, depois uma passagem de revisão verificando jargão e ambiguidade, depois uma passagem final de formatação. A diferença de qualidade entre passagem única e iterativa é substancial — facilmente vale os 30 segundos extras de tempo de processamento.
Padrão 4: Seleção consciente do contexto
Mesmo objetivo, diferentes caminhos de execução baseados no contexto. Faz upload de um PNG e usa um fluxo. Faz upload de um SVG e usa outro. Arquivo pequeno é processado inline; arquivo grande é fragmentado.
Ideal para: processamento de arquivos, geração de conteúdo em diferentes formatos, scripts de deploy que variam por ambiente.
Este padrão é mais complicado do que parece. Seu SKILL.md precisa de lógica de ramificação clara: "Se a entrada for [tipo A], seguir os passos 1-4. Se a entrada for [tipo B], seguir os passos 5-8." Condições de ramificação ambíguas levam o Claude a escolher o caminho errado e produzir um resultado correto para o cenário errado — o que é mais difícil de detectar do que um erro óbvio.
Padrão 5: Inteligência de domínio
O Skill incorpora expertise profunda em um domínio específico — regras de conformidade financeira, protocolos de segurança, padrões de codificação médica, critérios de revisão legal. O valor não está no fluxo de trabalho; está no conhecimento em si.
Ideal para: verificação de conformidade, auditorias de segurança, processos de revisão especializados, qualquer tarefa onde "conhecer as regras" é a parte difícil.
Este é o padrão onde os documentos de referência na sua pasta de Skill se justificam. Um arquivo SKILL.md apontando para uma checklist de conformidade de segurança de 50 páginas pode tornar o Claude um auditor de primeira passagem genuinamente útil. Não um substituto para expertise humana — mas um primeiro revisor incansável que nunca esquece de verificar o item 47 da página 12.
Certo, esse é o framework. Agora deixe-me poupar as horas que desperdicei em erros sobre os quais o guia não avisa.
Quatro erros que cometi para que você não precise cometer
Erro 1: Descrições vagas que nunca ativam.
Já cobri isso, mas vale repetir porque é o modo de falha número um. Se seu Skill nunca ativa, a descrição é quase sempre o problema. Escreva frases de ativação que correspondam às palavras exatas que um humano usaria. "Run my deployment checklist" não "assist with deployment processes."
Erro 2: Instruções enterradas em paredes de texto.
Meus primeiros Skills eram romances. Páginas de contexto, informações de fundo, casos extremos, filosofia sobre por que fazemos as coisas de certa maneira. O Claude os analisava, mas a relação sinal-ruído era terrível. Instruções importantes se diluíam com texto explicativo.
O que funciona melhor: priorize as instruções críticas no início. Coloque as regras inegociáveis nas primeiras 20 linhas. Use cabeçalhos agressivamente. Reserve o contexto de fundo para um documento de referência separado na pasta que o Claude possa consultar quando necessário mas não precise processar em cada invocação.
Erro 3: Falta de tratamento de erros para chamadas MCP.
Este me pegou feio. Meu Skill de planejamento de sprint funcionava lindamente — até que a API do Linear retornou um erro de rate limit numa segunda-feira de manhã, e o Skill simplesmente... parou. Sem fallback. Sem retry. Sem degradação graciosa. Apenas um Claude confuso dizendo que não conseguia completar a solicitação.
Seu Skill precisa antecipar falhas de ferramentas. Adicione instruções explícitas: "Se a chamada à API do Linear falhar, esperar 10 segundos e tentar novamente uma vez. Se falhar de novo, prosseguir com dados em cache da última execução bem-sucedida e notar que os dados podem estar desatualizados." Isso é engenharia de resiliência básica, mas é fácil esquecer quando você está focado no caminho feliz.
Erro 4: Tentar fazer demais em um único Skill.
Construí um Skill chamado "project-manager" que tentava lidar com planejamento de sprint, relatórios de status, geração de retrospectivas, refinamento de backlog e atualizações para stakeholders. Eram 400 linhas de instruções cobrindo cinco fluxos de trabalho distintos.
Era terrível. O Claude ativava o Skill certo mas seguia o fluxo de trabalho errado dentro dele. Frases de ativação para diferentes sub-tarefas se sobrepunham. As instruções para planejamento de sprint contradiziam algumas das convenções usadas na geração de retrospectivas.
Dividi em cinco Skills separados. Cada um ficou mais simples, mais confiável e mais fácil de manter. A sobrecarga de ter cinco pastas em vez de uma é negligível. A melhoria em precisão e consistência foi dramática.
O princípio subjacente: um Skill, um trabalho. Se você está escrevendo "também" ou "adicionalmente" no seu SKILL.md, provavelmente precisa de um segundo Skill.
A ideia que muda como você pensa sobre IA no trabalho
O guia termina com um pensamento que quase passei batido, mas é na verdade a ideia mais importante em todas as 32 páginas.
A maioria das pessoas usa a IA como um assistente de propósito geral. Cada conversa começa do zero. Você explica seu contexto, suas preferências, seus padrões, suas ferramentas, seus fluxos de trabalho — e então recebe uma resposta moldada por toda essa explicação. Amanhã, faz de novo. E de novo. E de novo.
Claude Skills inverte esse modelo. Em vez de trazer o contexto para a IA em cada conversa, você incorpora o contexto dentro do ambiente da IA permanentemente. A IA começa cada conversa relevante já conhecendo seus padrões, já conectada às suas ferramentas, já compreendendo seus fluxos de trabalho.
Isso não é um truque de produtividade. É uma mudança arquitetônica em como humanos e IA colaboram.
Quando olho para os onze Skills que construí nos últimos três dias, estou olhando para uma versão comprimida de como meu time trabalha. Nossos padrões de revisão de código. Nosso processo de deploy. Nosso estilo de comunicação com clientes. Nossa metodologia de planejamento de sprints. Nosso fluxo de entrega de design. Tudo codificado, executável e melhorando cada vez que alguém do time adiciona uma linha a um arquivo SKILL.md.
As organizações que descobrirem isso cedo — que começarem a construir bibliotecas de Skills capturando suas melhores práticas e conhecimento institucional — vão ter uma vantagem composta que cresce a cada mês. Não porque a IA é mais inteligente. Porque a IA os conhece melhor.
Comecei este post falando sobre apagar meus prompts salvos. Esse foi o sintoma. A mudança real é mais profunda. Parei de pensar no Claude como uma ferramenta que eu instruo e comecei a pensar nele como um membro do time que eu integro. A pasta de Skills é o manual de integração. E assim como integrar um humano, o investimento inicial de escrever instruções claras se paga todo dia que aquela pessoa — ou aquele Skill — aparece e faz o trabalho sem precisar ser dito duas vezes.
A Anthropic construiu o framework. As 32 páginas apresentam a mecânica. Mas o valor não está no framework — está no que você coloca dentro dele.
Então aqui vai minha pergunta: qual é o fluxo de trabalho que você repete toda semana e que poderia ensinar ao Claude uma vez e nunca mais explicar? Comece por aí. Uma pasta. Um SKILL.md. Uma descrição que realmente ative.
Todo o resto se constrói a partir daquele primeiro Skill que funciona.
Vamos trabalhar juntos
Procurando construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Adoraria ajudar.
- Fiverr (builds personalizados e integrações): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (soluções empresariais): ramlit.com
- ColorPark (design e branding): colorpark.io
- xCyberSecurity (serviços de segurança): xcybersecurity.io
