Orquestrador de Agentes
Visão Geral
Meta-skill que orquestra todos os agentes do ecossistema. Scan automático de skills, match por capacidades, coordenação de workflows multi-skill e gerenciamento de registry.
Quando Usar Esta Skill
- Quando você precisa de assistência especializada neste domínio
Não Use Esta Skill Quando
- A tarefa não está relacionada ao orquestrador de agentes
- Uma ferramenta mais simples e específica pode lidar com a solicitação
- O usuário precisa de assistência de propósito geral sem conhecimento de domínio
Como Funciona
Meta-skill que funciona como camada central de decisão e coordenação para todo o ecossistema de skills. Faz varredura automática, identifica agentes relevantes e orquestra múltiplos skills para tarefas complexas.
Princípio: Zero Intervenção Manual
- SEMPRE faz varredura antes de processar qualquer solicitação
- Novas skills são auto-detectadas e incluídas ao criar SKILL.md em qualquer subpasta
- Skills removidas são auto-excluídas do registry
- Nenhum comando manual é necessário para registrar novas skills
Fluxo de Trabalho Obrigatório (Toda Solicitação)
Execute estes passos ANTES de processar qualquer request do usuário. Os scripts usam paths relativos automaticamente - funciona de qualquer diretório.
Passo 1: Auto-Discovery (Varredura)
python agent-orchestrator/scripts/scan_registry.py
Ultra-rápido (<100ms) via cache de hashes MD5. Só re-processa arquivos alterados. Retorna JSON com resumo de todos os skills encontrados.
Passo 2: Match de Skills
python agent-orchestrator/scripts/match_skills.py "<solicitação do usuário>"
Retorna JSON com skills ranqueadas por relevância. Interpretar o resultado:
| Resultado | Ação |
|---|---|
matched: 0 | Nenhum skill relevante. Operar normalmente sem skills. |
matched: 1 | Um skill relevante. Carregar seu SKILL.md e seguir. |
matched: 2+ | Múltiplos skills. Executar Passo 3 (orquestração). |
Passo 3: Orquestração (Se Matched >= 2)
python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<solicitação>"
Retorna plano de execução com padrão, ordem dos steps e data flow entre skills.
Passo Rápido (Atalho)
Para queries simples, os passos 1+2 podem ser combinados em sequência:
python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<solicitação>"
Skill Registry
O registry vive em:
agent-orchestrator/data/registry.json
Locais de Busca
O scanner procura SKILL.md em:
.claude/skills/*/(skills registradas no Claude Code)*/(skills standalone no top-level)*/*\(skills em subpastas, até profundidade 3)
Metadados por Skill
Cada entrada no registry contém:
| Campo | Descrição |
|---|---|
| name | Nome da skill (do frontmatter YAML) |
| description | Descrição completa (triggers inclusos) |
| location | Caminho absoluto do diretório |
| skill_md | Caminho absoluto do SKILL.md |
| registered | Se está em .claude/skills/ (true/false) |
| capabilities | Tags de capacidade (auto-extraídas + explícitas) |
| triggers | Keywords de ativação extraídas da description |
| language | Linguagem principal (python/nodejs/bash/none) |
| status | active / incomplete / missing |
Comandos do Registry
## Scan Rápido (Usa Cache de Hashes)
python agent-orchestrator/scripts/scan_registry.py
## Tabela de Status Detalhada
python agent-orchestrator/scripts/scan_registry.py --status
## Re-Scan Completo (Ignora Cache)
python agent-orchestrator/scripts/scan_registry.py --force
Algoritmo de Matching
Para cada solicitação, o matcher pontua skills usando:
| Critério | Pontos | Exemplo |
|---|---|---|
| Nome do skill na query | +15 | "use web-scraper" -> web-scraper |
| Keyword trigger exata | +10 | "scrape" -> web-scraper |
| Categoria de capacidade | +5 | data-extraction -> web-scraper |
| Sobreposição de palavras | +1 | Palavras da query na description |
| Boost de projeto | +20 | Skill atribuída ao projeto ativo |
Threshold mínimo: 5 pontos. Skills abaixo disso são ignoradas.
Match com Projeto
python agent-orchestrator/scripts/match_skills.py --project meu-projeto "query aqui"
Skills atribuídas ao projeto recebem +20 de boost automático.
Padrões de Orquestração
Quando múltiplos skills são relevantes, o orchestrator classifica o padrão:
1. Pipeline Sequencial
Skills formam uma cadeia onde o output de uma alimenta a próxima.
Quando: Mix de skills "produtoras" (data-extraction, government-data) e "consumidoras" (messaging, social-media).
Exemplo: web-scraper coleta preços -> whatsapp-cloud-api envia alerta
user_query -> web-scraper -> whatsapp-cloud-api -> result
2. Execução Paralela
Skills trabalham independentemente em aspectos diferentes da solicitação.
Quando: Todas as skills têm o mesmo papel (todas produtoras ou todas consumidoras).
Exemplo: instagram publica post + whatsapp envia notificação (ambos recebem o mesmo conteúdo)
user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result
3. Primário + Suporte
Uma skill principal lidera; outras fornecem dados de apoio.
Quando: Uma skill tem score muito superior às demais (>= 2x).
Exemplo: whatsapp-cloud-api envia mensagem (primário) + web-scraper fornece dados (suporte)
user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result
Detalhes em References/Orchestration-Patterns.Md
Gerenciamento de Projetos
Atribuir skills a projetos permite boost de relevância e contexto persistente.
Arquivo de Projetos
agent-orchestrator/data/projects.json
Operações
Criar projeto: Adicionar entrada ao projects.json:
{
"name": "nome-do-projeto",
"created_at": "2026-02-25T12:00:00",
"skills": ["web-scraper", "whatsapp-cloud-api"],
"description": "Descrição do projeto"
}
Adicionar skill a projeto: Atualizar o array skills do projeto.
Remover skill de projeto: Remover do array skills.
Consultar skills do projeto: Ler o projects.json e listar skills atribuídas.
Adicionando Novas Skills
Para adicionar uma nova skill ao ecossistema:
- Criar uma pasta em qualquer lugar sob
skills root: - Criar um
SKILL.mdcom frontmatter YAML:
---
name: minha-nova-skill
description: "Descrição com keywords de ativação..."
---
## Documentação da Skill
- Pronto! O auto-discovery detecta automaticamente na próxima solicitação.
Opcionalmente, para discovery nativo do Claude Code:
4. Copiar o SKILL.md para .claude/skills/<nome>/SKILL.md
Tags de Capacidade Explícitas (Opcional)
Adicionar ao frontmatter para matching mais preciso:
capabilities: [data-extraction, web-automation]
Ver Status de Todos os Skills
python agent-orchestrator/scripts/scan_registry.py --status
Interpretar Status
| Status | Significado |
|---|---|
| active | SKILL.md com name + description presentes |
| incomplete | SKILL.md existe mas falta name ou description |
| missing | Diretório existe mas sem SKILL.md |
Skills Atuais do Ecossistema
| Skill | Capacidades | Status |
|---|---|---|
| web-scraper | data-extraction, web-automation | active |
| junta-leiloeiros | government-data, data-extraction | active |
| whatsapp-cloud-api | messaging, api-integration | active |
| social-media, api-integration | partial |
Esta tabela é atualizada automaticamente via scan_registry.py --status.
Melhores Práticas
- Forneça contexto claro e específico sobre seu projeto e requisitos
- Revise todas as sugestões antes de aplicá-las ao código em produção
- Combine com outras skills complementares para análises abrangentes
Armadilhas Comuns
- Usar esta skill para tarefas fora do seu domínio de especialização
- Aplicar recomendações sem entender seu contexto específico
- Não fornecer contexto suficiente do projeto para uma análise precisa
Skills Relacionadas
multi-advisor- Skill complementar para análise aprimoradatask-intelligence- Skill complementar para análise aprimorada
Limitações
- Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate o resultado como substituto para validação específica do ambiente, testes ou revisão de especialistas.
- Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.