Agent Orchestrator

Visão Geral

Meta-habilidade que orquestra todos os agentes do ecossistema. Scan automático de skills, match por capacidades, coordenação de workflows multi-skill e gerenciamento de registro.

Quando Usar Esta Habilidade

• Quando o usuário pede um inventário local de skills ou um plano de coordenação para uma tarefa com várias capacidades.
• Quando é necessário comparar candidatos explicitamente, sem executar suas instruções nem iniciar agentes.

Não Usar Esta Habilidade 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-habilidade 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: Descoberta Solicitada e Plano Revisável

• Faz varredura somente no escopo solicitado; esta habilidade não deve interceptar todas as solicitações
• Novas skills são detectadas na próxima varredura explícita, dentro dos roots e do limite de profundidade
• Skills removidas são auto-excluídas do registro
• Execute a varredura explicitamente; o matcher não inicia uma varredura automaticamente

Workflow Obrigatório (Toda Solicitação)

Execute estes passos apenas quando a tarefa pede esta ferramenta. Scores são heurísticas locais, não prova de segurança, compatibilidade ou autorização. Um plano não executa skills; delegação, mensagens e publicação exigem autorização do usuário. Os scripts localizam arquivos a partir da própria instalação, mas os comandos abaixo pressupõem que o diretório pai de agent-orchestrator seja o diretório atual. De outro local, use o caminho absoluto do script.

Passo 1: Auto-Discovery (Varredura)

python agent-orchestrator/scripts/scan_registry.py

Usa cache de hashes SHA-256 para reprocessar arquivos alterados. O tempo depende do tamanho da árvore; não há garantia de 100ms. Retorna JSON com resumo de todos os skills encontrados.

Passo 2: Match de Skills

python agent-orchestrator/scripts/match_skills.py "<solicitacao do usuario>"

Retorna JSON com skills ranqueadas por relevância. Interpretar o resultado:

Passo 3: Orquestração (Se Match >= 2)

python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<solicitacao>"

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 "<solicitacao>"

Registro de Skills

Antes de executar, defina AGENT_ORCHESTRATOR_DATA_DIR como caminho absoluto de um diretório privado autorizado fora da instalação da skill. Registro, hashes e atribuições de projeto ficam nesse diretório. Não use um diretório compartilhado ou uma árvore com links simbólicos; inspecione o conteúdo antes de reutilizar.

export AGENT_ORCHESTRATOR_DATA_DIR="<diretorio-absoluto-autorizado>"

Execute a varredura explicitamente antes do matcher. Falha de leitura, JSON inválido ou registro ausente não significa que nenhuma skill existe. Caminhos distintos permanecem no inventário mesmo com nomes iguais; seleção por nome ambíguo deve parar. O limite de profundidade do scanner torna o inventário parcial.

Locais de Busca

O scanner procura SKILL.md em:

1. .claude/skills/*/ (skills registradas no Claude Code)
2. */ (skills standalone no top-level)
3. */*\ (skills em subpastas, até profundidade 3)

Metadados Por Skill

Cada entrada no registro contém:

…