Noções Básicas de Design e Empacotamento de Skills

10 exemplos para você começar com Design e Empacotamento de Skills - 7 básicos e 3 intermediários.

Pré-requisitos

• Uma tarefa repetida que você já pede ao Claude para fazer da mesma forma mais de uma vez - este é o material bruto, não uma página em branco.
• Um local para salvar uma pasta: um arquivo SKILL.md mais, opcionalmente, alguns arquivos de suporte ao lado dele.
• Nenhum software especial além de um editor de texto - SKILL.md é um arquivo Markdown simples com um bloco YAML frontmatter no topo.

Exemplos Básicos

1. O Mínimo Viável de SKILL.md

Toda Skill precisa de exatamente duas coisas em seu frontmatter: um name e uma description.

---
name: pr-review-checklist
description: >-
  Reviews a pull request diff against a fixed checklist. Use when the user
  asks for a PR review, code review, or to check a diff before merging.
---

• name é um identificador curto em kebab-case para a pasta e o arquivo da Skill.
• description é o que Claude compara com uma nova tarefa para decidir se esta Skill se aplica - está fazendo mais trabalho do que qualquer outro campo.
• Tudo abaixo do frontmatter é o corpo da instrução que Claude segue assim que decide usar a Skill.
• Uma Skill com apenas esses dois campos mais um corpo é um pacote completo e válido.

2. Declarando o Que a Skill Faz

A primeira metade de uma boa descrição nomeia a tarefa em termos concretos.

description: >-
  Summarizes a customer support transcript into a structured ticket:
  issue, steps taken, and resolution status.

• Nomeie o resultado real, não uma categoria vaga - "ticket estruturado" é melhor que "ajuda com suporte".
• Evite descrever a Skill em termos que apenas seu autor reconheceria; escreva como um colega descreveria a tarefa.
• Esta metade responde "o que isso faz", o que é necessário, mas não suficiente por si só.
• Mantenha em uma ou duas frases - uma descrição é metadados, não documentação.

3. Declarando Quando a Skill Deve Ser Acionada

A segunda metade nomeia as situações que devem ativar a Skill.

description: >-
  Summarizes a customer support transcript into a structured ticket. Use
  when the user pastes a support conversation or asks for a ticket summary.

• "Use quando..." é um padrão confiável e explícito para a metade de acionamento de uma descrição.
• Nomeie os sinais concretos que uma tarefa real mostraria - uma transcrição colada, uma frase de solicitação específica - não uma categoria abstrata.
• Uma descrição que apenas diz o que a Skill faz, sem dizer quando, é a razão mais comum para uma Skill passar despercebida.
• Teste a metade de acionamento perguntando: esta redação também corresponderia a uma tarefa para a qual a Skill NÃO se destina?

Relacionado: Escrevendo uma Descrição de Skill Eficaz Que Claude Acionará - um mergulho completo neste campo exato.

4. Escrevendo o Primeiro Passo Numerado

As instruções pertencem ao corpo como passos ordenados, não como um único parágrafo longo.

## Instructions
 
1. Read the full transcript provided by the user.
2. Identify the customer's core issue in one sentence.
3. List the troubleshooting steps already attempted, in order.

• A numeração força você a decidir a ordem real das operações, que a prosa solta permite que você pule.
• Cada passo deve ser realizável por si só, sem precisar reler o parágrafo inteiro para saber o que fazer a seguir.
• Passos curtos e específicos são mais fáceis para Claude seguir da mesma maneira todas as vezes do que um único parágrafo denso.
• Esboce os passos em linguagem simples primeiro; você pode refinar a redação assim que a ordem estiver correta.

5. Finalizando a Lista de Passos

Uma lista de passos útil termina com uma saída concreta, não um resumo vago.

4. Note the current resolution status: open, pending, or resolved.
5. Output the four fields above as a short structured summary.

• O último passo deve descrever exatamente o que é produzido, para que não haja ambiguidade sobre quando a Skill está "pronta".
• Evite passos finais em aberto como "finalize apropriadamente" - eles convidam a resultados inconsistentes entre as execuções.
• Uma lista de passos com um final claro também é mais fácil de testar: você sabe como é uma execução correta.
• Uma lista de cinco passos é um tamanho razoável para uma primeira Skill; tarefas mais longas podem ter mais, mas cada uma ainda deve ser uma ação única e concreta.

6. Escolhendo um Nível (tarefa básica vs. avançada)

Nem toda Skill precisa de mecanismos extras - a maioria começa simples.

---
name: weekly-status-draft
description: >-
  Drafts a weekly status update from raw meeting notes or bullet points.
  Use when the user asks for a status update, recap, or standup summary.
---
## Instructions
1. Read the raw notes or bullet points provided.
2. Group items into: shipped, in progress, blocked.
3. Draft three to five sentences per group.

• Uma Skill com apenas frontmatter e uma lista numerada curta é um pacote completo - você não precisa de allowed-tools ou arquivos empacotados para começar.
• Adicione complexidade apenas quando a tarefa realmente exigir, não por padrão.
• Esta é a forma que a maioria das primeiras Skills deve ter: dois campos de frontmatter e um punhado de passos.
• Você sempre pode adicionar escopo ou recursos empacotados mais tarde sem reescrever o que já funciona.

7. Salvando o Pacote Como uma Pasta

Uma Skill vive em sua própria pasta, nomeada para corresponder ao seu campo name.

pr-review-checklist/
  SKILL.md

• O nome da pasta e o campo name devem corresponder, para que o pacote seja fácil de identificar rapidamente.
• Uma Skill de arquivo único - apenas SKILL.md em sua própria pasta - é um pacote normal e completo, não um incompleto.
• Nada mais é necessário até que uma tarefa realmente precise de arquivos de referência empacotados, scripts ou escopo de ferramentas.
• Este é o ponto em que "ideia" se tornou "pacote" - a pasta está completa e pronta para ser testada contra uma tarefa real.

Exemplos Intermediários

8. Testando o Acionador Antes de Confiar na Saída

Antes de confiar em uma nova Skill, verifique se ela é ativada nas tarefas corretas e permanece silenciosa nas incorretas.

Teste 1 (deve acionar):
  "Aqui está a transcrição da chamada com o cliente, você pode
  resumi-la em um ticket?"
 
Teste 2 (NÃO deve acionar):
  "Você pode resumir este artigo de notícias para mim?"

• Execute pelo menos uma tarefa que você espera que ative a Skill e uma que você espera que não ative, e confirme que Claude toma a decisão correta em ambos os casos.
• Uma Skill que produz um ótimo resultado uma vez invocada está apenas meio concluída se também disparar em tarefas não relacionadas, ou nunca disparar.
• Se o Teste 2 acionar acidentalmente a Skill, a descrição é muito ampla e precisa de uma linguagem de acionamento mais clara e específica.
• Se o Teste 1 falhar em acionar, a descrição provavelmente não declara o "quando" com clareza suficiente, mesmo que o "o quê" esteja correto.

Relacionado: Erros Comuns Que Tornam Uma Skill Difícil de Encontrar ou Usar Pelo Claude - uma lista mais completa de falhas de acionamento para verificar.

9. Revisando uma Descrição Após um Acionamento Perdido

Quando uma Skill não dispara em uma tarefa que deveria, a correção está quase sempre na descrição, não nas instruções.

# Before: too abstract to match real phrasing
description: >-
  Helps with support tickets.
 
# After: concrete outputs and concrete trigger language
description: >-
  Summarizes a customer support transcript into a structured ticket with
  issue, steps taken, and resolution status. Use when the user pastes a
  support conversation or asks to turn a conversation into a ticket.

• Compare a redação exata da solicitação perdida com a descrição - a lacuna geralmente aponta diretamente para a correção.
• Ampliar uma descrição ligeiramente é muitas vezes mais seguro do que reescrevê-la do zero, pois as partes que funcionam permanecem intactas.
• Mantenha um pequeno registro de acionamentos perdidos ou falsos enquanto você refina uma nova Skill - os padrões aparecem mais rápido do que correções pontuais.
• Uma descrição nunca está realmente "pronta" na primeira vez; espere pelo menos uma revisão após o uso real.

10. Combinando Duas Tarefas Relacionadas em Uma Skill

Quando duas tarefas compartilham a maioria de seus passos, uma Skill com um ramificação geralmente é melhor do que dois pacotes separados.

## Instructions
1. Read the provided notes.
2. If the notes are from a single meeting, draft a status update
   (see step 3a).
3a. Group into shipped, in progress, blocked; draft 3-5 sentences per group.
3b. If the notes span a full week across multiple meetings, draft a
    weekly digest instead: one paragraph per project, ordered by priority.

• Uma única Skill com ramificação é mais fácil de descobrir e manter do que duas Skills com descrições quase idênticas competindo pelo mesmo acionador.
• As ramificações devem ser baseadas em algo concretamente detectável na entrada, como "reunião única" vs. "abrange uma semana", não em um julgamento subjetivo.
• Se as ramificações divergem genuinamente na maioria de seus passos em vez de apenas no final, isso é um sinal de que elas devem ser Skills separadas.
• Este padrão escala: uma Skill bem organizada pode conter algumas ramificações intimamente relacionadas sem se tornar pouco clara sobre quando cada uma se aplica.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.