Agent Orchestrator

Meta-agent skill for orchestrating complex tasks through autonomous sub-agents. Decomposes macro tasks into subtasks, spawns specialized sub-agents with dynamically generated SKILL.md files, coordinates file-based communication, consolidates results, and dissolves agents upon completion. MANDATORY TRIGGERS: orchestrate, multi-agent, decompose task, spawn agents, sub-agents, parallel agents, agent coordination, task breakdown, meta-agent, agent factory, delegate tasks

Security Scan

The skill's high-level purpose (orchestrating sub-agents) is plausible, but the instructions allow creating fully autonomous agents with powerful capabilities, reference missing helper scripts, and include file-protocol rules (e.g., an ignored private workspace) that could be used to hide or exfiltrate data — proceed with caution and additional controls.

Purpose & Capability

The skill claims to be a meta-orchestrator which legitimately needs to create and coordinate sub-agents. However, SKILL.md references helper scripts (python3 scripts/create_agent.py and scripts/dissolve_agents.py) that are not included in the package and no install or dependency is declared. The templates grant sub-agents broad capabilities (WebFetch, Bash, Read) without describing required constraints — this is disproportionate without explicit guardrails.

Instruction Scope

The runtime instructions instruct generating SKILL.md for sub-agents, writing inbox/outbox/status files, and spawning agents via the platform Task(...) call. Sub-agent templates explicitly allow reading local files, running Bash, and fetching the web. The communication protocol states the agent's workspace is 'private' and 'orchestrator ignores' it, which creates an avenue for hiding outputs or exfiltration. The orchestrator's guidance to 'prefer broader, autonomous tasks' and 'minimal monitoring' widens the agent's discretion.

Install Mechanism

This is instruction-only (no install spec), which limits on-disk payload risk. However, referenced scripts (create_agent.py, dissolve_agents.py) are absent from the bundle, an inconsistency that must be resolved before use — either those scripts exist elsewhere on the host or the instructions won't work as written.

Credentials

The skill requests no environment variables or credentials (proportionate). Nevertheless, the templates allow sub-agents to read local files and run shell commands; that capability could be used to access secrets on disk or environment variables if the orchestrator or host environment exposes them. The skill does not declare or constrain that risk.

Persistence & Privilege

always:false (good) and autonomous invocation is the platform default. But the orchestrator spawns new agents dynamically with 'general-purpose' type and minimal monitoring patterns; combined with private agent workspaces that the orchestrator 'ignores', this gives spawned agents the practical ability to persist or hide data. No explicit lifecycle/permission constraints for spawned agents are provided.

What to consider before installing

Before installing or using this skill, consider the following: 1) Source and provenance: the skill has unknown source and no homepage — prefer skills from known, auditable authors. 2) Missing helper scripts: SKILL.md references scripts/create_agent.py and scripts/dissolve_agents.py that are not included — verify where these live and audit them. 3) Least privilege: require narrow capabilities for spawned agents (disable Bash/WebFetch if not needed) and restrict sub-agent tools to only what's necessary. 4) Inspect generated SKILL.md at creation time: ensure templates cannot be modified to perform unintended actions. 5) Do not expose sensitive files or credentials: avoid copying secrets into agent inboxes; treat all inbox content as potentially leaked by autonomous agents. 6) Monitoring & human-in-loop: enable stricter monitoring, require human approval before spawning many agents, and limit parallelism. 7) Audit workspaces: change the 'orchestrator ignores workspace' rule — ensure the orchestrator can inspect per-agent workspaces or add integrity checks to detect hidden outputs. 8) Test in a sandbox: run the orchestrator in an isolated environment with limited network and filesystem access first. If you need help designing safe guardrails (ACLs, runtime constraints, logging), get those defined before deploying.

Orchestrate complex tasks by decomposing them into subtasks, spawning autonomous sub-agents, and consolidating their work.

Core Workflow

Phase 1: Task Decomposition

Analyze the macro task and break it into independent, parallelizable subtasks:

1. Identify the end goal and success criteria
2. List all major components/deliverables required
3. Determine dependencies between components
4. Group independent work into parallel subtasks
5. Create a dependency graph for sequential work

Decomposition Principles:

• Each subtask should be completable in isolation
• Minimize inter-agent dependencies
• Prefer broader, autonomous tasks over narrow, interdependent ones
• Include clear success criteria for each subtask

Phase 2: Agent Generation

For each subtask, create a sub-agent workspace:

python3 scripts/create_agent.py <agent-name> --workspace <path>

This creates:

<workspace>/<agent-name>/
├── SKILL.md          # Generated skill file for the agent
├── inbox/            # Receives input files and instructions
├── outbox/           # Delivers completed work
├── workspace/        # Agent's working area
└── status.json       # Agent state tracking

Generate SKILL.md dynamically with:

• Agent's specific role and objective
• Tools and capabilities needed
• Input/output specifications
• Success criteria
• Communication protocol

See references/sub-agent-templates.md for pre-built templates.

Phase 3: Agent Dispatch

Initialize each agent by:

1. Writing task instructions to inbox/instructions.md
2. Copying required input files to inbox/
3. Setting status.json to {"state": "pending", "started": null}
4. Spawning the agent using the Task tool:

# Spawn agent with its generated skill
Task(
    description=f"{agent_name}: {brief_description}",
    prompt=f"""
    Read the skill at {agent_path}/SKILL.md and follow its instructions.
    Your workspace is {agent_path}/workspace/
    Read your task from {agent_path}/inbox/instructions.md
    Write all outputs to {agent_path}/outbox/
    Update {agent_path}/status.json when complete.
    """,
    subagent_type="general-purpose"
)

Phase 4: Monitoring (Checkpoint-based)

For fully autonomous agents, minimal monitoring is needed:

# Check agent completion
def check_agent_status(agent_path):
    status = read_json(f"{agent_path}/status.json")
    return status.get("state") == "completed"

Periodically check status.json for each agent. Agents update this file upon completion.

Phase 5: Consolidation

Once all agents complete:

1. Collect outputs from each agent's outbox/
2. Validate deliverables against success criteria
3. Merge/integrate outputs as needed
4. Resolve conflicts if multiple agents touched shared concerns
5. Generate summary of all work completed

# Consolidation pattern
for agent in agents:
    outputs = glob(f"{agent.path}/outbox/*")
    validate_outputs(outputs, agent.success_criteria)
    consolidated_results.extend(outputs)

Phase 6: Dissolution & Summary

After consolidation:

1. Archive agent workspaces (optional)
2. Clean up temporary files
3. Generate final summary:
   • What was accomplished per agent
   • Any issues encountered
   • Final deliverables location
   • Time/resource metrics

python3 scripts/dissolve_agents.py --workspace <path> --archive

File-Based Communication Protocol

See references/communication-protocol.md for detailed specs.

Quick Reference:

• inbox/ - Read-only for agent, written by orchestrator
• outbox/ - Write-only for agent, read by orchestrator
• status.json - Agent updates state: pending → running → completed | failed

Example: Research Report Task

Macro Task: "Create a comprehensive market analysis report"

Decomposition:
├── Agent: data-collector
│   └── Gather market data, competitor info, trends
├── Agent: analyst
│   └── Analyze collected data, identify patterns
├── Agent: writer
│   └── Draft report sections from analysis
└── Agent: reviewer
    └── Review, edit, and finalize report

Dependency: data-collector → analyst → writer → reviewer

Sub-Agent Templates

Pre-built templates for common agent types in references/sub-agent-templates.md:

• Research Agent - Web search, data gathering
• Code Agent - Implementation, testing
• Analysis Agent - Data processing, pattern finding
• Writer Agent - Content creation, documentation
• Review Agent - Quality assurance, editing
• Integration Agent - Merging outputs, conflict resolution

Best Practices

1. Start small - Begin with 2-3 agents, scale as patterns emerge
2. Clear boundaries - Each agent owns specific deliverables
3. Explicit handoffs - Use structured files for agent communication
4. Fail gracefully - Agents report failures; orchestrator handles recovery
5. Log everything - Status files track progress for debugging