Maestro

Meta-orquestrador de skills para agentes de IA

Descubra skills locais, monte um grafo editável e execute com subagentes —
sem adivinhar qual skill chamar.

npx maestro-skills setup

Documentação do CLI · skills.sh · Issues

Visão geral

O Maestro responde à pergunta:

Para esta tarefa, quais skills devo usar, em que ordem, e preciso instalar algo novo?

Ele não implementa o trabalho — orquestra: busca skills instaladas, propõe um grafo de dependências, espera sua confirmação e só então dispara subagentes com os SKILL.md corretos.

Inspirado em ideias de task-skill-router.

Início rápido

1. Instalar (interativo)

npx maestro-skills setup

O setup detecta agentes, pergunta onde instalar (global ou --project), copia a skill e gera o manifest.

# Exemplos
npx maestro-skills setup --codex --cursor -y
npx maestro-skills setup --project
npx @rodovalhofs/maestro setup          # bin curto (scoped)

2. Usar no agente

$maestro criar dashboard de vendas com React
$maestro vamos colocar skeleton-loader na UI
$maestro corrigir CI quebrado no PR #42

3. Regenerar índice (após instalar novas skills)

py -3 ~/.cursor/skills/maestro/scripts/build_manifest.py --project-root .

Manifest: ~/.maestro/skills-manifest.json

Como funciona

  Seu prompt
      │
      ▼
  search_skills.py ──► match forte? ──► grafo único → ok → subagentes
      │
      └─ discover.triggered
              │
              ▼
          npx skills find → Grafo 1 → ok → install → Grafo 2 → ok → execução

Gatilhos do ramo Discover

Máximo de 2 concept gaps por prompt.

O que faz / o que não faz

Outras formas de instalar

npx skills add rodovalhofs/maestro --skill maestro -g -a cursor -a codex -y

git clone https://github.com/rodovalhofs/maestro.git
Copy-Item -Recurse -Force maestro\skills\maestro $env:USERPROFILE\.codex\skills\maestro

git clone https://github.com/rodovalhofs/maestro.git
cp -r maestro/skills/maestro ~/.codex/skills/maestro

Depois rode build_manifest.py (ver acima).

CLI de debug

# Buscar skills (recomendado — funciona no PowerShell)
npx maestro-skills search "dashboard react" --json

# Rotear sub-tarefas
npx maestro-skills route --task "design UI" --task "fix CI" --json

# Regenerar manifest
npx maestro-skills manifest --project-root .

# Runbooks do usuário
npx maestro-skills runbook list
npx maestro-skills runbook init-allowlist

PowerShell fallback: & "$env:USERPROFILE\.cursor\skills\maestro\scripts\invoke.ps1" search "..." --json

Campos úteis no JSON: results, routing, discover, runbook (por skill), weak_match, metadata_boost e metadata_matches.

A busca normaliza maiúsculas e diacríticos, portanto consultas como código e codigo são equivalentes. Correspondências completas de nomes e tags compostas recebem um boost limitado por skill; tags repetidas não acumulam score.

Domínios (--domain): web · data-viz · analytics · design · creative · devops-git · video-media · integrations · security · meta · general

Repositório

maestro/
├── packages/maestro-skills/   ← CLI npm (npx maestro-skills)
├── skills/maestro/            ← skill + scripts Python
├── tests/                     ← motor de busca
├── docs/                      ← CLI + fluxo GitHub
└── templates/                 ← Issue/PR para outros repos

Pré-requisitos

Desenvolvimento

py -3 -m unittest discover -s tests -v
cd packages/maestro-skills && npm test

Contribuir · Segurança · Licença

• CONTRIBUTING.md — Issues e PRs bem-vindos
• SECURITY.md — revise pacotes de npx skills find antes de instalar
• MIT — Copyright (c) 2026 Yuri Rodovalho