Communitygithub.com

aetox-skills/create-agent

Habilidade de design de agentes com foco em escopo — pergunte o escopo claramente antes de criar o agente.

O que é create-agent?

Esta skill capacita um agente de IA (como Claude Code, Cursor, Codex) a projetar outros agentes de IA com uma disciplina rigorosa de 'escopo primeiro'. Em vez de começar a escrever prompts ou código, o agente conduz uma entrevista de escopo estruturada, cuja profundidade depende da complexidade do novo agente. O resultado é um **Agent Spec** validado — um blueprint de 8 dimensões (Arquétipo, Personalidade, Capacidades, E/S, Ecossistema, Memória, Ciclo de Vida, Risco/Métricas) que outro agente ou humano pode usar para construir o agente corretamente. A skill é agnóstica de plataforma, funcionando com qualquer framework ou ferramenta, e impõe regras rígidas como 'escopo antes da construção', profundidade mínima suficiente (padrão Rápido), e inferência de contexto antes de perguntar. Ela também inclui um sistema de arquétipos e camadas de profundidade para adaptar a entrevista ao tipo e risco do agente.

Funciona com✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Criar Agente

Propósito

Projetar agentes de IA com uma disciplina de escopo primeiro. Antes de escrever qualquer prompt, configuração ou vinculação de ferramenta, você deve passar por uma entrevista de escopo estruturada. A profundidade da entrevista depende da complexidade do agente sendo projetado.

Esta não é uma habilidade de escrever prompts. É uma habilidade de validação de escopo. A saída é um Agent Spec validado — um blueprint que outra IA ou humano pode usar para construir o agente corretamente.

Cada spec de agente define 8 dimensões:

Arquétipo → Personalidade → Capacidades → E/S → Ecossistema → Memória → Ciclo de Vida → Risco/Métricas

Regras de Ferro

  1. Escopo antes da construção — Nenhum código, nenhum prompt, nenhuma configuração de ferramenta até que o escopo seja validado. Zero exceções.

    Autoridade de Correção: Usado apenas para rascunho/suposição de spec — corrija suposições no spec que o usuário errou (dep ausente, contradição, risco de segurança) imediatamente, sem precisar perguntar. Apenas informe o que ajustou e por quê. Não edite arquivos, configurações, ferramentas ou workflows reais sem obter aprovação. Peça aprovação antes se a solução correta exigir mudar de ferramenta ou alterar um workflow existente — mas se o senso comum pode corrigir o spec, faça isso.

  2. Profundidade mínima suficiente — Padrão: Rápido. Promova para Padrão/Profundo/ Crítico apenas quando sinais explícitos aparecerem. Não comece no Padrão.

  3. Inferir primeiro, perguntar depois — Antes de fazer uma pergunta, tente inferir a resposta a partir do contexto, codebase, agentes existentes e o que o usuário já disse. Pergunte apenas sobre o que permanece genuinamente incerto.

  4. Codebase primeiro — Se a resposta para uma pergunta existe em configurações, docs ou agentes existentes — vá encontrá-la. Não pergunte. Exceção Greenfield: Se não existir codebase (sem index.md, AGENTS.md, opencode.jsonc ou agentes existentes), pule a varredura do codebase e vá diretamente para a entrevista.

  5. Minimize idas e vindas — Infira o spec → apresente rascunho → deixe o usuário marcar. Pergunte um de cada vez apenas para lacunas genuínas que o rascunho não consegue resolver. Nunca despeje 10 perguntas de uma vez.

  6. Recomende, não seja aberto — Toda pergunta deve incluir uma resposta recomendada. Dê algo para reagir.

  7. Spec deve ser aprovado — Nunca construa até que o Agent Spec seja explicitamente aprovado. Para a camada Rápida, a confirmação do usuário do spec inferido conta como aprovação. Documente como Status: Aprovado via Rápido.

  8. Pare no sinal — Quando o usuário disser "chega" ou "pare" — pare. Não discuta, não insista por mais.

  9. Produza um Agent Spec — Toda sessão produz um spec validado, mesmo na camada Rápida.


Sistema de Arquétipos de Agente

Agentes seguem padrões baseados em seu arquétipo. Use esta tabela para escolher o arquétipo certo e entender em quais domínios de entrevista focar ou pular.

Catálogo de Arquétipos

#ArquétipoPropósito PrincipalPersonalidade PadrãoFerramentas TípicasCamada Sugerida
🛠️SistemaAutomatizar, configurar, manterPrático, conciso, diretoCLI, sistema de arquivos, Docker, gitRápido → Padrão
🎨CriativoDesign, visual, movimentoExpressivo, detalhistaTailwind, GSAP, APIs de imagemRápido → Padrão
💻DesenvolvedorCódigo, arquitetura, depuraçãoTécnico, preciso, minuciosoMCPs, linters, executores de testeRápido → Profundo
📝EscribaDocumentar, escrever, organizarClaro, estruturado, pacienteObsidian, markdown, pesquisaRápido
🔬EspecialistaDomínio único e profundoAutoritário, meticulosoCLI/MCP específico de domínioRápido → Profundo
🎯OrquestradorCoordenar, delegar, gerenciarSistemático, orientado a processosLista de agentes, protocolo de handoffRápido → Crítico
🔍PesquisadorPesquisar, analisar, sintetizarCurioso, analítico, minuciosoExa, Firecrawl, ferramentas webRápido
🎮JogoComportamento específico de jogoLúdico, adaptávelAPI de jogo, framework de botRápido → Profundo

Lista de Minimização de Arquétipo

Não é "pular", mas informar qual domínio deve ser curto ou pulável se óbvio.

Existem 3 níveis:

  • Aprofundado — Pergunte tudo
  • Breve — Faça apenas 1-2 perguntas e resuma
  • Pular se óbvio — Não pergunte se o senso comum pode determinar (ex: Escriba → Memória = apenas sessão)
ArquétipoBrevePular se óbvioAprofundado
SistemaIdentidade, E/SMemóriaCapacidades, Ecossistema
CriativoRisco/Métricas, Ciclo de VidaMemóriaIdentidade, E/S, Personalidade
DesenvolvedorCiclo de VidaIdentidadeCapacidades, Ecossistema, E/S
EscribaEcossistemaRisco/Métricas, MemóriaIdentidade, E/S
EspecialistaE/S, Ciclo de Vida—Capacidades, Risco/Métricas
Orquestrador——Todos os domínios
PesquisadorCiclo de Vida, PersonalidadeMemóriaCapacidades, E/S, Identidade
JogoEcossistemaRisco/MétricasCapacidades, E/S, Personalidade

Desenvolvedor + Identidade: Breve não é Pular — a identidade (frontmatter) ainda deve existir porque determina quando o agente é chamado. Apenas mantenha curto (1-2 frases).

Seleção de Arquétipo

Ao entrevistar, recomende um arquétipo com base no propósito do agente. Se vários arquétipos se encaixam, escolha o dominante e anote os secundários.

Exemplo: "Isso parece um arquétipo Desenvolvedor com alguma sobreposição de Especialista.
         Pela lista de minimização: Ciclo de Vida = breve, Identidade = breve (frontmatter
         apenas), foque aprofundado em Capacidades + Ecossistema."

Sistema de Camadas de Profundidade

Nem todo agente precisa da mesma profundidade. Esta skill define 4 camadas. Padrão: Rápido. Comece leve, escale apenas quando sinais exigirem.

Camada 1 — Rápido       (inferir → confirmar → construir, pergunte mais se incerto)
                         │                          ← PADRÃO
Camada 2 — Padrão       (Apresentar rascunho → usuário marca → aprovar)
                         │
Camada 3 — Profundo     (Padrão + Mapa de Ecossistema + Rastreio de Dependências)
                         │
Camada 4 — Crítico      (Profundo + Modelo de Risco + Modelo de Custo + Portões de Segurança)

Seleção de Camada

SinalRápidoPadrãoProfundoCrítico
Agente é novo ou modificado (1-2 caps), escopo claro✅———
Agente existente, pequena alteração✅———
Novo agente, propósito único, sem dependências—✅——
Novo agente, 1-2 integrações externas—✅✅—
Agente em ecossistema multi-agente——✅✅
Lida com pagamento / autenticação / PII———✅
Implantado em produção———✅
Alto custo de token por chamada———✅
Implicações de segurança ou conformidade———✅
Arquétipo = Orquestrador———✅
Arquétipo = Especialista——✅—

Padrão: Rápido. Promova apenas quando sinais explícitos estiverem presentes.

Regra de escalada: Se durante uma entrevista de camada inferior você descobrir sinais que justificam uma camada superior, promova explicitamente:

Nota de promoção:
  Gatilho: [o que você encontrou]
  Evidência: [onde encontrou]
  Risco de permanecer: [por que a camada inferior é insegura]

Camada 1 — Rápido

Para agentes simples e pequenas alterações. Infira o spec do contexto, confirme com o usuário, construa. Sem entrevista completa, sem portão de aprovação separado.

Não pense demais nesta camada. Se incerto, ainda comece aqui — a complexidade surgirá durante a inferência. Promova se sinais aparecerem.

Critérios de Entrada

  • Agente é novo (1-2 capacidades) ou existente com pequena modificação.
  • Nenhuma integração externa além do que já existe.
  • Nenhuma coordenação multi-agente.
  • Nenhum risco de segurança, custo ou conformidade.
  • Requisitos são claros o suficiente para que uma entrevista de 8 domínios pareceria engenharia excessiva.

Processo

1. Inferir spec do contexto    ← Leia do que o usuário disse + codebase + agentes existentes
2. Apresentar mini-spec        ← Use formato fixo abaixo
3. Usuário marca               ← "Diga onde alterar"
   Se a marcação for trivial (1-2 palavras, pequena correção de formato)
     → Pode construir
   Se a marcação for estrutural (adicionar cap, mudar ferramenta, alterar limite)
     → apresente mini-spec revisado → usuário confirma → Construa
4. Construir

Formato do Mini-Spec (Fixo)

## Quick Spec: [Nome]

Função: [Uma frase — "O que faz, para quem, para obter o quê"]
Capacidades:
  - [ação 1]
  - [ação 2]
Limites:
  - [o que não pode fazer]
Autoridade: [Somente leitura / Sugerir / Modificar no escopo / Executar / Autônomo]
Ferramentas: [ferramenta / MCP / nenhuma necessária]
Aprovação: [Confirmado via Rápido / Revisado e Confirmado]

Use o arquivo templates/quick-spec.md como template real. Não encurte ou pule estes campos — se um campo for óbvio, escreva "—" (não pergunte ao usuário). Se modificar agente existente → use o mesmo formato, mas mostre apenas os campos alterados.

Exemplo

Usuário: "Quero um agente que resuma meus e-mails"

Inferir:
  Arquétipo: Escriba
  Capacidade: ler e-mail → resumo em tópicos
  Ferramentas: Gmail MCP (já existente)
  Ecossistema: está com o steward

Apresentar mini-spec:
  ## Quick Spec: resumidor-email

  Função: Ler Gmail → resumir em tópicos para o Mike toda manhã
  Capacidades:
    - Ler e-mails do Gmail MCP → resumir em tópicos
    - Separar por remetente / assunto
  Limites:
    - Não responder e-mails, não excluir e-mails
  Autoridade: Somente leitura
  Ferramentas: Gmail MCP (já existente)
  Aprovação: —

  "Português/Inglês? Todos os e-mails ou apenas de tópicos específicos?"

Usuário: "Português, todos, sem log"
  (marcação trivial — Enviar para Construir)

Construir.
  ## Quick Spec: resumidor-email
  ...
  Autoridade: Somente leitura
  Aprovação: Confirmado via Rápido

Camada 2 — Padrão

Para novos agentes e mudanças significativas. Promova para Padrão quando Rápido for insuficiente (integrações complexas, impacto no ecossistema ou escopo pouco claro).

Processo

1. Portão de Intenção       → Reformule, identifique arquétipo, usuário + objetivo + restrição
2. Varredura do Codebase    → Leia index.md, opencode.jsonc, AGENTS.md, agentes existentes
                           (se não houver → greenfield: pule, vá direto para apresentar rascunho)
3. Correspondência de Arquétipo → Selecione arquétipo, aplique lista de minimização
4. Apresentar Rascunho      → Infira spec completo do contexto conhecido → apresente rascunho de 1 página
                           Pergunte apenas sobre incertezas (não uma de cada vez)
5. Usuário Marca            → Usuário edita / adiciona / remove do rascunho
6. Iterar (se necessário)   → Se houver lacuna → apresente rascunho revisado
7. Propor Spec              → Agent Spec completo (veja templates/agent-spec.md)
8. Portão de Aprovação      → Usuário aprova antes de construir

Entrevista de Escopo (8 Domínios)

Para camada Rápida: pule tudo — infira + confirme desde o início

Para Padrão+:

  1. Infira rascunho do spec do contexto existente → apresente rascunho de uma página ao usuário
  2. Usuário lê e marca (edita/adiciona/remove)
  3. Use a lista de verificação abaixo para verificar se algo foi esquecido — pergunte apenas o que o rascunho não cobre
  4. Aplique a Lista de Minimização de Arquétipo — breve / pular se óbvio / aprofundado de acordo com o arquétipo

Não pergunte item por item da lista de verificação — apresente rascunho primeiro, pergunte apenas lacunas

Domínio 1: Identidade e Propósito

  • Nome — como o agente se chama? (proponha se sem nome)

  • Arquétipo — qual arquétipo do catálogo?

  • Função — uma frase clara: "Este agente [faz X] para [usuário Y] para que [Z]."

  • Persona —

    CampoO quêExemplo
    Tomformal / casual / técnico / lúdico / autoritário / acolhedor"técnico, mas acessível"
    Frase de exemploFala real do agente"Deixe-me verificar a configuração... Encontrei. O problema está na linha 42."

    Sempre recomende uma persona.

    "Sugiro um tom técnico, mas acessível —
     preciso nos fatos, relaxado na conversa."
    
  • Contexto conhecido — o que ele precisa saber antes de trabalhar?

  • Trabalho mais restrito — qual é a menor definição útil de sua função?

Domínio 2: Capacidades e Limites

  • Capacidades — ações principais, ranqueadas por prioridade. Cada capacidade inclui:

    • Descrição (1 frase)
    • Gatilho (como essa capacidade é invocada?)
    • Saída esperada (como é o sucesso?)
    • Modo de falha (o que acontece se não funcionar?)
  • Limites — lista explícita do que ele nunca deve fazer. Formate cada um como uma Regra Crítica com cenário:

    Regra: Nunca modificar arquivos fora do diretório do projeto.
    Cenário: Usuário pede "corrigir minhas configurações da área de trabalho" — agente tem acesso ao sistema de arquivos.
    Consequência: Recusar educadamente, explicar limite de escopo.
    
  • Mapeamento de Ferramentas — para cada capacidade, determine quais ferramentas são necessárias. Faça isso após capacidades e limites estarem claros.

    Capacidade: "Pesquisar documentação"
    ↓
    Pesquisar codebase por ferramentas existentes → encontrou Exa MCP (pesquisa web)
    ↓
    Propor: "Recuperação de conhecimento via Exa MCP (já configurado).
              Se Exa estiver indisponível, fallback para pesquisa web via Firecrawl."
    

    Regra: Proponha uma ferramenta específica se já existir uma no codebase. Apenas proponha uma categoria quando nenhuma ferramenta existente se encaixar. Mas: Se a ferramenta existente não corresponder à necessidade (ex: precisa de pesquisa local em docs, mas só tem Exa para pesquisa web) — não force o encaixe. Marque como ajuste parcial ou lacuna e proponha a categoria mais adequada.

    ✅ "Usa Exa MCP para pesquisa web — já configurado"
    ✅ "Exa MCP existe para pesquisa web, mas pesquisa em log de trabalho deve usar
        Obsidian + grep — é um ajuste parcial para pesquisa externa"
    ✅ "Nenhum vector DB existente encontrado. Precisa de uma ferramenta de busca semântica
        como Chroma ou Qdrant."
    ❌ "Precisa de uma ferramenta de recuperação de conhecimento" (vago — Exa existe, use-a)
    ❌ "Usa Exa MCP para tudo" (forçar encaixe — Exa não é adequado para pesquisa local)
    

    Categorias de ferramentas (referência para lacunas):

    Recuperação de conhecimento → pesquisa, vector DBs, armazenamento de documentos, web scraping
    Execução de código         → sandboxes, interpretadores, compiladores, linters
    Comunicação                → e-mail, mensagens, notificações, webhooks
    Operações de sistema       → E/S de arquivos, gerenciamento de processos, rede, registro
    Processamento de dados     → ETL, transformação, validação, armazenamento
    Visual/criativo            → geração de imagens, mecanismos de layout, animação
    Monitoramento              → logs, métricas, rastreamento, alertas
    IA/LLM                     → APIs de modelo, embeddings, pipelines RAG, vector DBs
    Testes                     → executores de teste, cobertura, mocking, navegadores E2E
    
  • Habilidades — quais habilidades o agente deve ter?

...

[truncado para tradução]

Habilidades Relacionadas