SamuelChien/mega-skills-collection

Desenvolvimento de Agentes para Plugins do Claude Code

Visão Geral

Agentes são subprocessos autônomos que lidam com tarefas complexas e de múltiplas etapas de forma independente. Compreender a estrutura do agente, as condições de acionamento e o design do prompt de sistema permite criar capacidades autônomas poderosas.

Conceitos-chave:

• Agentes são PARA trabalho autônomo, comandos são PARA ações iniciadas pelo usuário
• Formato de arquivo Markdown com frontmatter YAML
• Acionamento via campo de descrição com exemplos
• O prompt de sistema define o comportamento do agente
• Personalização de modelo e cor

Estrutura do Arquivo do Agente

Formato Completo

---
name: identificador-do-agente
description: Use este agente quando [condições de acionamento]. Exemplos:

<example>
Context: [Descrição da situação]
user: "[Solicitação do usuário]"
assistant: "[Como o assistente deve responder e usar este agente]"
<commentary>
[Por que este agente deve ser acionado]
</commentary>
</example>

<example>
[Exemplo adicional...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

Você é [descrição do papel do agente]...

**Suas Responsabilidades Principais:**
1. [Responsabilidade 1]
2. [Responsabilidade 2]

**Processo de Análise:**
[Fluxo de trabalho passo a passo]

**Formato de Saída:**
[O que retornar]

Campos do Frontmatter

name (obrigatório)

Identificador do agente usado para namespacing e invocação.

Formato: apenas letras minúsculas, números e hífens Comprimento: 3-50 caracteres Padrão: Deve começar e terminar com alfanumérico

Exemplos bons:

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Exemplos ruins:

• helper (muito genérico)
• -agent- (começa/termina com hífen)
• my_agent (underscores não são permitidos)
• ag (muito curto, < 3 caracteres)

description (obrigatório)

Define quando Claude deve acionar este agente. Este é o campo mais crítico.

Deve incluir:

1. Condições de acionamento ("Use este agente quando...")
2. Múltiplos blocos <example> mostrando o uso
3. Contexto, solicitação do usuário e resposta do assistente em cada exemplo
4. <commentary> explicando por que o agente é acionado

Formato:

Use este agente quando [condições]. Exemplos:

<example>
Context: [Descrição do cenário]
user: "[O que o usuário diz]"
assistant: "[Como Claude deve responder]"
<commentary>
[Por que este agente é apropriado]
</commentary>
</example>

[Mais exemplos...]

Melhores práticas:

• Inclua 2-4 exemplos concretos
• Mostre acionamento proativo e reativo
• Cubra diferentes formulações da mesma intenção
• Explique o raciocínio no commentary
• Seja específico sobre quando NÃO usar o agente

model (obrigatório)

Qual modelo o agente deve usar.

Opções:

• inherit - Usar o mesmo modelo do pai (recomendado)
• sonnet - Claude Sonnet (equilibrado)
• opus - Claude Opus (mais capaz, caro)
• haiku - Claude Haiku (rápido, barato)

Recomendação: Use inherit a menos que o agente precise de capacidades específicas do modelo.

color (obrigatório)

Identificador visual para o agente na interface.

Opções: blue, cyan, green, yellow, magenta, red

Diretrizes:

• Escolha cores distintas para diferentes agentes no mesmo plugin
• Use cores consistentes para tipos de agentes semelhantes
• Azul/ciano: Análise, revisão
• Verde: Tarefas orientadas a sucesso
• Amarelo: Cautela, validação
• Vermelho: Crítico, segurança
• Magenta: Criativo, geração

tools (opcional)

Restringir o agente a ferramentas específicas.

Formato: Array de nomes de ferramentas

tools: ["Read", "Write", "Grep", "Bash"]

Padrão: Se omitido, o agente tem acesso a todas as ferramentas

Melhor prática: Limitar as ferramentas ao mínimo necessário (princípio do menor privilégio)

Conjuntos de ferramentas comuns:

• Análise somente leitura: ["Read", "Grep", "Glob"]
• Geração de código: ["Read", "Write", "Grep"]
• Testes: ["Read", "Bash", "Grep"]
• Acesso total: Omitir o campo ou usar ["*"]

Design do Prompt de Sistema

O corpo do markdown se torna o prompt de sistema do agente. Escreva na segunda pessoa, dirigindo-se diretamente ao agente.

Estrutura

Modelo padrão:

Você é [função] especializado em [domínio].

**Suas Responsabilidades Principais:**
1. [Responsabilidade primária]
2. [Responsabilidade secundária]
3. [Responsabilidades adicionais...]

**Processo de Análise:**
1. [Passo um]
2. [Passo dois]
3. [Passo três]
[...]

**Padrões de Qualidade:**
- [Padrão 1]
- [Padrão 2]

**Formato de Saída:**
Forneça os resultados neste formato:
- [O que incluir]
- [Como estruturar]

**Casos Extremos:**
Lide com estas situações:
- [Caso extremo 1]: [Como lidar]
- [Caso extremo 2]: [Como lidar]

Melhores Práticas

✅ FAÇA:

• Escreva na segunda pessoa ("Você é...", "Você irá...")
• Seja específico sobre as responsabilidades
• Forneça um processo passo a passo
• Defina o formato de saída
• Inclua padrões de qualidade
• Aborde casos extremos
• Mantenha abaixo de 10.000 caracteres

❌ NÃO FAÇA:

• Escreva na primeira pessoa ("Eu sou...", "Eu irei...")
• Seja vago ou genérico
• Omita etapas do processo
• Deixe o formato de saída indefinido
• Pule as orientações de qualidade
• Ignore os casos de erro

Criando Agentes

Método 1: Geração Assistida por IA

Use este padrão de prompt (extraído do Claude Code):

Crie uma configuração de agente baseada nesta solicitação: "[SUA DESCRIÇÃO]"

Requisitos:
1. Extraia a intenção principal e responsabilidades
2. Projete uma persona especialista para o domínio
3. Crie um prompt de sistema abrangente com:
   - Limites comportamentais claros
   - Metodologias específicas
   - Tratamento de casos extremos
   - Formato de saída
4. Crie um identificador (minúsculas, hífens, 3-50 caracteres)
5. Escreva a descrição com condições de acionamento
6. Inclua 2-3 blocos <example> mostrando quando usar

Retorne JSON com:
{
  "identifier": "nome-do-agente",
  "whenToUse": "Use este agente quando... Exemplos: <example>...</example>",
  "systemPrompt": "Você é..."
}

Em seguida, converta para o formato de arquivo de agente com frontmatter.

Consulte examples/agent-creation-prompt.md para o modelo completo.

Método 2: Criação Manual

1. Escolha um identificador para o agente (3-50 caracteres, minúsculas, hífens)
2. Escreva a descrição com exemplos
3. Selecione o modelo (geralmente inherit)
4. Escolha uma cor para identificação visual
5. Defina as ferramentas (se for restringir o acesso)
6. Escreva o prompt de sistema com a estrutura acima
7. Salve como agents/nome-do-agente.md

Regras de Validação

Validação do Identificador

✅ Válido: code-reviewer, test-gen, api-analyzer-v2
❌ Inválido: ag (muito curto), -start (começa com hífen), my_agent (underscore)

Regras:

• 3-50 caracteres
• Apenas letras minúsculas, números e hífens
• Deve começar e terminar com alfanumérico
• Sem underscores, espaços ou caracteres especiais

Validação da Descrição

Comprimento: 10-5.000 caracteres Deve incluir: Condições de acionamento e exemplos Ideal: 200-1.000 caracteres com 2-4 exemplos

Validação do Prompt de Sistema

Comprimento: 20-10.000 caracteres Ideal: 500-3.000 caracteres Estrutura: Responsabilidades claras, processo, formato de saída

Organização de Agentes

Diretório de Agentes do Plugin

nome-do-plugin/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

Todos os arquivos .md em agents/ são descobertos automaticamente.

Namespacing

Agentes têm namespace automático:

• Plugin único: nome-do-agente
• Com subdiretórios: plugin:subdir:nome-do-agente

Testando Agentes

Teste de Acionamento

Crie cenários de teste para verificar se o agente é acionado corretamente:

1. Escreva o agente com exemplos de acionamento específicos
2. Use formulações semelhantes aos exemplos no teste
3. Verifique se Claude carrega o agente
4. Confirme que o agente fornece a funcionalidade esperada

Teste do Prompt de Sistema

Garanta que o prompt de sistema está completo:

1. Atribua ao agente uma tarefa típica
2. Verifique se ele segue as etapas do processo
3. Confirme que o formato de saída está correto
4. Teste os casos extremos mencionados no prompt
5. Verifique se os padrões de qualidade são atendidos

Referência Rápida

Agente Mínimo

---
name: agente-simples
description: Use este agente quando... Exemplos: <example>...</example>
model: inherit
color: blue
---

Você é um agente que [faz X].

Processo:
1. [Passo 1]
2. [Passo 2]

Saída: [O que fornecer]

Resumo dos Campos do Frontmatter

Campo	Obrigatório	Formato	Exemplo
name	Sim	minusculas-com-hifens	code-reviewer
description	Sim	Texto + exemplos	Use quando... ...
model	Sim	inherit/sonnet/opus/haiku	inherit
color	Sim	Nome da cor	blue
tools	Não	Array de nomes de ferramentas	["Read", "Grep"]

Melhores Práticas

FAÇA:

• ✅ Inclua 2-4 exemplos concretos na descrição
• ✅ Escreva condições de acionamento específicas
• ✅ Use inherit para modelo, a menos que haja necessidade específica
• ✅ Escolha ferramentas apropriadas (menor privilégio)
• ✅ Escreva prompts de sistema claros e estruturados
• ✅ Teste o acionamento do agente completamente

NÃO FAÇA:

• ❌ Use descrições genéricas sem exemplos
• ❌ Omita condições de acionamento
• ❌ Dê a mesma cor para todos os agentes
• ❌ Conceda acesso desnecessário a ferramentas
• ❌ Escreva prompts de sistema vagos
• ❌ Pule os testes

Recursos Adicionais

Arquivos de Referência

Para orientação detalhada, consulte:

• references/system-prompt-design.md - Padrões completos de prompt de sistema
• references/triggering-examples.md - Formatos de exemplo e melhores práticas
• references/agent-creation-system-prompt.md - O prompt exato do Claude Code

Arquivos de Exemplo

Exemplos funcionais em examples/:

• agent-creation-prompt.md - Modelo de geração de agente assistida por IA
• complete-agent-examples.md - Exemplos completos de agentes para diferentes casos de uso

Scripts Utilitários

Ferramentas de desenvolvimento em scripts/:

• validate-agent.sh - Validar estrutura do arquivo do agente
• test-agent-trigger.sh - Testar se o agente é acionado corretamente

Fluxo de Trabalho de Implementação

Para criar um agente para um plugin:

1. Defina o propósito do agente e as condições de acionamento
2. Escolha o método de criação (assistido por IA ou manual)
3. Crie o arquivo agents/nome-do-agente.md
4. Escreva o frontmatter com todos os campos obrigatórios
5. Escreva o prompt de sistema seguindo as melhores práticas
6. Inclua 2-4 exemplos de acionamento na descrição
7. Valide com scripts/validate-agent.sh
8. Teste o acionamento com cenários reais
9. Documente o agente no README do plugin

Concentre-se em condições de acionamento claras e prompts de sistema abrangentes para operação autônoma.