📌 Como o agente usa a description
O agente compara o contexto da conversa com a description de cada skill instalada. Se há match semântico, a skill é ativada automaticamente.
O mecanismo de decisão
Para escrever descriptions que funcionam, você precisa pensar como o agente: qual situação na conversa dispararia esta instrução?
💡 Conceitos-chave
matching semântico · ativação contextual · similaridade · intent detection · descrição como seletor
📝 Instruções claras e acionáveis
Instruções eficazes usam verbos imperativos (Use, Verifique, Evite), são específicas (não genéricas) e têm exemplos de entrada e saída quando possível.
Do vago ao específico
Instruções vagas (seja profissional, escreva bom código) são inúteis. Instruções específicas (use TypeScript strict mode, adicione JSDoc em todas as funções públicas) são acionáveis.
💡 Conceitos-chave
verbos imperativos · especificidade · exemplos · entrada/saída · critérios mensuráveis
🎯 Seção When to Use
A seção When to Use lista cenários concretos em que a skill deve ser ativada. Funciona como reforço da description — mais detalhado, com exemplos reais de quando usar.
Gatilhos explícitos
Mesmo que o agente use a description para ativar, a seção When to Use ajuda o agente a confirmar que está no contexto certo antes de aplicar as instruções.
💡 Conceitos-chave
cenários de ativação · triggers · exemplos concretos · confirmação de contexto · uso correto
📋 Seção Steps
A seção Steps contém passos numerados que o agente executa na ordem indicada. Ideal para processos: code review, geração de componentes, deploy checklist.
Instruções sequenciais
Steps bem escritos são como uma receita: o agente os segue passo a passo. Use números quando a ordem importa; use bullets quando os itens são independentes.
💡 Conceitos-chave
passos numerados · sequência · dependência entre passos · checklist · procedimentos
⚠️ Erros comuns ao escrever skills
Os 5 erros mais comuns: description vaga, instruções contraditórias, skill muito grande (>100 linhas), sem seção When to Use, usar jargão que o agente não reconhece.
Antipatterns para evitar
Erros frequentes resultam em skills nunca ativadas, aplicadas no momento errado ou que confundem mais do que ajudam. Conhecer os antipatterns poupa muito retrabalho.
💡 Conceitos-chave
description vaga · skill monolítica · jargão opaco · contradição · sem contexto de uso
🔍 find-skills como modelo de referência
A skill find-skills do repositório vercel-labs/agent-skills é o exemplo mais bem escrito do ecossistema. Description precisa, When to Use com triggers naturais, Steps acionáveis.
Aprendendo com o melhor exemplo
Estudar e copiar a estrutura da find-skills como ponto de partida garante que suas skills seguem as melhores práticas da especificação oficial.
💡 Conceitos-chave
modelo oficial · estrutura ideal · triggers naturais · boas práticas · referência
✅ Resumo do Módulo
Próximo:
3.2 — Estrutura de Repositório de Skills