Agent Orchestrator

Overview

Meta-skill que orquestra todos os agentes do ecossistema. Scan automatico de skills, match por capacidades, coordenacao de workflows multi-skill e registry management.

When to Use This Skill

When you need specialized assistance with this domain

Do Not Use This Skill When

The task is unrelated to agent orchestrator
A simpler, more specific tool can handle the request
The user needs general-purpose assistance without domain expertise

How It Works

Meta-skill que funciona como camada central de decisao e coordenacao para todo o ecossistema de skills. Faz varredura automatica, identifica agentes relevantes e orquestra multiplos skills para tarefas complexas.

Principio: Zero Intervencao Manual

SEMPRE faz varredura antes de processar qualquer solicitacao
Novas skills sao auto-detectadas e incluidas ao criar SKILL.md em qualquer subpasta
Skills removidas sao auto-excluidas do registry
Nenhum comando manual e necessario para registrar novas skills

Workflow Obrigatorio (Toda Solicitacao)

Execute estes passos ANTES de processar qualquer request do usuario. Os scripts usam paths relativos automaticamente - funciona de qualquer diretorio.

Passo 1: Auto-Discovery (Varredura)

python agent-orchestrator/scripts/scan_registry.py

Ultra-rapido (<100ms) via cache de hashes MD5. So 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 "<solicitacao do usuario>"

Retorna JSON com skills ranqueadas por relevancia. Interpretar o resultado:

Resultado	Acao
`matched: 0`	Nenhum skill relevante. Operar normalmente sem skills.
`matched: 1`	Um skill relevante. Carregar seu SKILL.md e seguir.
`matched: 2+`	Multiplos skills. Executar Passo 3 (orquestracao).

Passo 3: Orquestracao (Se Matched >= 2)

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

Retorna plano de execucao com padrao, ordem dos steps e data flow entre skills.

Passo Rapido (Atalho)

Para queries simples, os passos 1+2 podem ser combinados em sequencia:

python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<solicitacao>"

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, ate profundidade 3)

Metadata Por Skill

Cada entrada no registry contem:

Campo	Descricao
name	Nome da skill (do frontmatter YAML)
description	Descricao completa (triggers inclusos)
location	Caminho absoluto do diretorio
skill_md	Caminho absoluto do SKILL.md
registered	Se esta em .claude/skills/ (true/false)
capabilities	Tags de capacidade (auto-extraidas + explicitas)
triggers	Keywords de ativacao extraidas da description
language	Linguagem principal (python/nodejs/bash/none)
status	active / incomplete / missing

Comandos Do Registry


## Scan Rapido (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 solicitacao, o matcher pontua skills usando:

Criterio	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
Sobreposicao de palavras	+1	Palavras da query na description
Boost de projeto	+20	Skill atribuida ao projeto ativo

Threshold minimo: 5 pontos. Skills abaixo disso sao ignoradas.

Match Com Projeto

python agent-orchestrator/scripts/match_skills.py --project meu-projeto "query aqui"

Skills atribuidas ao projeto recebem +20 de boost automatico.

Padroes De Orquestracao

Quando multiplos skills sao relevantes, o orchestrator classifica o padrao:

1. Pipeline Sequencial

Skills formam uma cadeia onde o output de uma alimenta a proxima.

Quando: Mix de skills "produtoras" (data-extraction, government-data) e "consumidoras" (messaging, social-media).

Exemplo: web-scraper coleta precos -> whatsapp-cloud-api envia alerta

user_query -> web-scraper -> whatsapp-cloud-api -> result

2. Execucao Paralela

Skills trabalham independentemente em aspectos diferentes da solicitacao.

Quando: Todas as skills tem o mesmo papel (todas produtoras ou todas consumidoras).

Exemplo: instagram publica post + whatsapp envia notificacao (ambos recebem o mesmo conteudo)

user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result

3. Primario + Suporte

Uma skill principal lidera; outras fornecem dados de apoio.

Quando: Uma skill tem score muito superior as demais (>= 2x).

Exemplo: whatsapp-cloud-api envia mensagem (primario) + 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 relevancia e contexto persistente.

Arquivo De Projetos

agent-orchestrator/data/projects.json

Operacoes

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": "Descricao 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 atribuidas.

Adicionando Novas Skills

Para adicionar uma nova skill ao ecossistema:

Criar uma pasta em qualquer lugar sob skills root:
Criar um SKILL.md com frontmatter YAML:

---
name: minha-nova-skill
description: "Descricao com keywords de ativacao..."
---

## Documentacao Da Skill

Pronto! O auto-discovery detecta automaticamente na proxima solicitacao.

Opcionalmente, para discovery nativo do Claude Code: 4. Copiar o SKILL.md para .claude/skills/<nome>/SKILL.md

Tags De Capacidade Explicitas (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	Diretorio 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
instagram	social-media, api-integration	partial

Esta tabela e atualizada automaticamente via scan_registry.py --status.

Best Practices

Provide clear, specific context about your project and requirements
Review all suggestions before applying them to production code
Combine with other complementary skills for comprehensive analysis

Common Pitfalls

Using this skill for tasks outside its domain expertise
Applying recommendations without understanding your specific context
Not providing enough project context for accurate analysis

Related Skills

multi-advisor - Complementary skill for enhanced analysis
task-intelligence - Complementary skill for enhanced analysis

agent-orchestrator