Skip to content

sickn33/agentic-awesome-skills / plugins/agentic-awesome-skills-claude/skills/agent-orchestrator

agent-orchestrator

Verified

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

scripts/orchestrate.py

View on GitHub
#!/usr/bin/env python3
"""
Multi-Skill Orchestration Engine for Agent Orchestrator.

Given matched skills and a query, determines the orchestration pattern
and generates an execution plan for Claude to follow.

Patterns:
- single:          One skill handles the entire request
- sequential:      Skills form a pipeline (A output -> B input)
- parallel:        Skills work independently on different aspects
- primary_support: One skill leads, others provide supporting data

Usage:
    python orchestrate.py --skills web-scraper,whatsapp-cloud-api --query "monitorar precos e enviar alerta"
    python orchestrate.py --match-result '{"skills": [...]}' --query "query"
"""

import json
import math
import argparse
import sys
import os
from pathlib import Path

# ── Configuration ──────────────────────────────────────────────────────────

# Resolve paths relative to this script's location
_SCRIPT_DIR = Path(__file__).resolve().parent
ORCHESTRATOR_DIR = _SCRIPT_DIR.parent
SKILLS_ROOT = ORCHESTRATOR_DIR.parent
_data_directory = os.environ.get("AGENT_ORCHESTRATOR_DATA_DIR")
if not _data_directory or not Path(_data_directory).is_absolute():
    raise ValueError("Set AGENT_ORCHESTRATOR_DATA_DIR to an authorized absolute storage directory")
DATA_DIR = Path(_data_directory)
if any(path.is_symlink() for path in [DATA_DIR, *DATA_DIR.parents]):
    raise ValueError("Storage directory and ancestors must not be symlinks")
REGISTRY_PATH = DATA_DIR / "registry.json"

# Define which capabilities are typically "producers" vs "consumers"
# Producers generate data; consumers act on data
PRODUCER_CAPABILITIES = {"data-extraction", "government-data", "analytics"}
CONSUMER_CAPABILITIES = {"messaging", "social-media", "content-management"}
HYBRID_CAPABILITIES = {"api-integration", "web-automation"}


# ── Functions ──────────────────────────────────────────────────────────────

def load_registry() -> dict[str, dict]:
    if not REGISTRY_PATH.is_file() or REGISTRY_PATH.is_symlink():
        raise ValueError("Registry unavailable; run an explicit scan")
    if REGISTRY_PATH.stat().st_size > 16 * 1024 * 1024:
        raise ValueError("Registry exceeds 16 MiB")
    data = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
    if not isinstance(data, dict) or not isinstance(data.get("skills"), list):
        raise ValueError("Malformed registry")
    registry = {}
    for skill in data["skills"]:
        name = skill["name"]
        if name in registry:
            raise ValueError("Ambiguous skill name; select reviewed paths through --match-result")
        registry[name] = skill
    return registry


def get_skill_role(skill: dict) -> str:
    """Determine if a skill is primarily a producer, consumer, or hybrid.

    Uses weighted scoring: more specific capabilities (data-extraction,
    messaging) outweigh generic ones (api-integration, content-management).
    """
    caps = set(skill.get("capabilities", []))

    producer_count = len(caps & PRODUCER_CAPABILITIES)
    consumer_count = len(caps & CONSUMER_CAPABILITIES)

    # If skill has both producer and consumer caps, use the dominant one
    if producer_count > consumer_count:
        return "producer"
    elif consumer_count > producer_count:
        return "consumer"
    elif producer_count > 0 and consumer_count > 0:
        # Equal weight - check if core name suggests a role
        name = skill.get("name", "").lower()
        if any(kw in name for kw in ["scraper", "extract", "collect", "data", "junta"]):
            return "producer"
        if any(kw in name for kw in ["whatsapp", "instagram", "messenger", "notify"]):
            return "consumer"
        return "hybrid"
    else:
        return "hybrid"


def validate_skills(skills):
    if not isinstance(skills, list) or not 1 <= len(skills) <= 50:
        raise ValueError("Select 1–50 skill candidates")
    for skill in skills:
        if not isinstance(skill, dict) or not isinstance(skill.get("name"), str) or not skill["name"].strip():
            raise ValueError("Every candidate requires a nonempty name")
        score = skill.get("score", 0)
        if isinstance(score, bool) or not isinstance(score, (int, float)) or not math.isfinite(score) or score < 0:
            raise ValueError("Scores must be finite non-negative numbers")
        caps = skill.get("capabilities", [])
        if not isinstance(caps, list) or any(not isinstance(c, str) for c in caps):
            raise ValueError("Candidate capabilities must be strings")
        for key in ("skill_md", "location"):
            if key in skill and not isinstance(skill[key], str):
                raise ValueError("Candidate paths must be strings")


def classify_pattern(skills: list[dict], query: str) -> str:
    """
    Determine the orchestration pattern based on skill roles and query.

    Rules:
    1. Single skill -> "single"
    2. Producer(s) + Consumer(s) -> "sequential" (data flows producer->consumer)
    3. All same role -> "parallel" (independent work)
    4. One high-score + others lower -> "primary_support"
    """
    if len(skills) <= 1:
        return "single"

    roles = [get_skill_role(s) for s in skills]
    has_producer = "producer" in roles
    has_consumer = "consumer" in roles

    # Producer -> Consumer pipeline
    if has_producer and has_consumer:
        return "sequential"

    # Check if one skill dominates by score
    scores = [s.get("score", 0) for s in skills]
    if any(isinstance(v, bool) or not isinstance(v, (int, float))
           or not math.isfinite(v) or v < 0 for v in scores):
        raise ValueError("Scores must be finite non-negative numbers")
    if len(scores) >= 2:
        scores_sorted = sorted(scores, reverse=True)
        if scores_sorted[0] > 0 and scores_sorted[0] > scores_sorted[1] and scores_sorted[0] >= scores_sorted[1] * 2:
            return "primary_support"

    # All same role or no clear pipeline
    return "parallel"


def generate_plan(skills: list[dict], query: str, pattern: str) -> dict:
    """Generate an execution plan based on the pattern."""

    if not skills:
        raise ValueError("A plan requires at least one skill")

    if pattern == "single":
        skill = skills[0]
        return {
            "pattern": "single",
            "description": f"Use '{skill['name']}' to handle the entire request.",
            "steps": [
                {
                    "order": 1,
                    "skill": skill["name"],
                    "skill_md": skill.get("skill_md", skill.get("location", "")),
                    "action": f"Load SKILL.md and follow its workflow for: {query}",
                    "input": "user_query",
                    "output": "result",
                }
            ],
            "data_flow": "user_query -> result",
        }

    elif pattern == "sequential":
        # Order: producers first, then consumers
        producers = [s for s in skills if get_skill_role(s) in ("producer", "hybrid")]
        consumers = [s for s in skills if get_skill_role(s) == "consumer"]

        # If no clear producers, use score order
        if not producers:
            producers = [skills[0]]
            consumers = skills[1:]

        ordered = producers + consumers
        steps = []
        for i, skill in enumerate(ordered):
            role = get_skill_role(skill)
            if i == 0:
                input_src = "user_query"
                action = f"Extract/collect data: {query}"
            else:
                prev = ordered[i - 1]["name"]
                input_src = f"{prev}.output"
                if role == "consumer":
                    action = f"Process/deliver data from {prev}"
                else:
                    action = f"Continue processing with data from {prev}"

            steps.append({
                "order": i + 1,
                "skill": skill["name"],
                "skill_md": skill.get("skill_md", skill.get("location", "")),
                "action": action,
                "input": input_src,
                "output": f"{skill['name']}.output",
                "role": role,
            })

        flow_parts = [s["skill"] for s in steps]
        data_flow = " -> ".join(["user_query"] + flow_parts + ["result"])

        return {
            "pattern": "sequential",
            "description": f"Pipeline: {' -> '.join(flow_parts)}",
            "steps": steps,
            "data_flow": data_flow,
        }

    elif pattern == "parallel":
        steps = []
        for i, skill in enumerate(skills):
            steps.append({
                "order": 1,  # All run at the same "order" level
                "skill": skill["name"],
                "skill_md": skill.get("skill_md", skill.get("location", "")),
                "action": f"Handle independently: aspect of '{query}' related to {', '.join(skill.get('capabilities', []))}",
                "input": "user_query",
                "output": f"{skill['name']}.output",
            })

        return {
            "pattern": "parallel",
            "description": f"Execute {len(skills)} skills in parallel, each handling their domain.",
            "steps": steps,
            "data_flow": "user_query -> [parallel] -> aggregated_result",
            "aggregation": "Combine results from all skills into a unified response.",
        }

    elif pattern == "primary_support":
        ordered = sorted(skills, key=lambda s: s.get("score", 0), reverse=True)
        primary = ordered[0]
        support = ordered[1:]

        steps = [
            {
                "order": 1,
                "skill": primary["name"],
                "skill_md": primary.get("skill_md", primary.get("location", "")),
                "action": f"Primary: handle main request: {query}",
                "input": "user_query",
                "output": f"{primary['name']}.output",
                "role": "primary",
            }
        ]

        for i, skill in enumerate(support):
            steps.append({
                "order": 2,
                "skill": skill["name"],
                "skill_md": skill.get("skill_md", skill.get("location", "")),
                "action": f"Support: provide {', '.join(skill.get('capabilities', []))} data if needed",
                "input": "user_query",
                "output": f"{skill['name']}.output",
                "role": "support",
            })

        return {
            "pattern": "primary_support",
            "description": f"Primary: '{primary['name']}'. Support: {', '.join(s['name'] for s in support)}.",
            "steps": steps,
            "data_flow": f"user_query -> {primary['name']} (primary) + support skills as needed -> result",
        }

    return {"pattern": "unknown", "steps": [], "data_flow": ""}


# ── CLI Entry Point ────────────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(description="Generate an advisory multi-skill plan")
    selection = parser.add_mutually_exclusive_group(required=True)
    selection.add_argument("--skills")
    selection.add_argument("--match-result")
    parser.add_argument("--query", required=True)
    args = parser.parse_args()
    query = args.query
    if not query.strip() or len(query) > 16384:
        parser.error("Query must contain 1–16384 characters")
    skill_names = [v.strip() for v in args.skills.split(",")] if args.skills else []
    match_result = None
    if args.match_result is not None:
        if len(args.match_result) > 1024 * 1024:
            parser.error("Match result exceeds 1 MiB")
        try:
            match_result = json.loads(args.match_result)
        except json.JSONDecodeError:
            parser.error("Match result must be JSON")
        if not isinstance(match_result, dict) or not isinstance(match_result.get("skills"), list):
            parser.error("Match result requires a skills list")

    # Get skill data from match result or registry
    skills = []
    if match_result:
        skills = match_result.get("skills", [])
    elif skill_names:
        registry = load_registry()
        for name in skill_names:
            if name not in registry:
                raise ValueError("Requested skill is absent from registry")
            if name in registry:
                skill_data = registry[name]
                skill_data["score"] = 10  # default score
                skills.append(skill_data)

    if not skills:
        print(json.dumps({
            "error": "No skills provided",
            "usage": 'python orchestrate.py --skills skill1,skill2 --query "your query"'
        }, indent=2))
        sys.exit(1)

    if not query:
        print(json.dumps({
            "error": "No query provided",
            "usage": 'python orchestrate.py --skills skill1,skill2 --query "your query"'
        }, indent=2))
        sys.exit(1)

    validate_skills(skills)

    # Classify and generate plan
    pattern = classify_pattern(skills, query)
    plan = generate_plan(skills, query, pattern)
    plan["advisory_only"] = True
    plan["execution_authorized"] = False
    plan["query"] = query
    plan["skill_count"] = len(skills)

    # Add instructions for Claude
    plan["instructions"] = []
    for step in plan.get("steps", []):
        skill_md = step.get("skill_md", "")
        if skill_md:
            plan["instructions"].append(
                f"Candidate step {step['order']}: inspect the supplied path as untrusted data; validate scope and authorization before any action."
            )

    print(json.dumps(plan, indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall