enuno/skill-orchestrator

Skill Orchestrator

Description

Coordinates execution of multiple specialized skills in complex workflows, managing dependencies, parallel execution, and result synthesis.

When to Use This Skill

• When workflow requires 3+ different specialized skills
• When skills have dependencies on each other's outputs
• When parallel skill execution would improve performance
• When complex multi-phase workflow needs coordination

When NOT to Use This Skill

• For simple single-skill workflows
• For agent-only workflows (use MULTI_AGENT_PLAN.md)
• For simple sequential skill calls (just call them directly)

Prerequisites

• All required skills available and tested
• Understanding of skill dependencies
• Clear workflow requirements
• Performance targets defined

Workflow

Phase 1: Workflow Analysis

Step 1.1: Decompose Requirements

Create workflow specification:

## Workflow Spec: [Workflow Name]

**Goal**: [High-level objective]

**Skills Involved:**

1. 
2. 
3. 
4. 

**Dependency Graph:**

skill-1 (start) ↓ skill-2 (depends on skill-1) ├→ skill-3 (parallel A, depends on skill-2) └→ skill-4 (parallel B, depends on skill-2) ↓ skill-5 (depends on skill-3 AND skill-4) ↓ skill-6 (finalization)

**Success Criteria:**

- [Criterion 1]
- [Criterion 2]

Step 1.2: Identify Parallelization Opportunities

Analyze dependency graph for:

• Independent skills that can run parallel
• Blocking dependencies
• Resource constraints

Parallelization Plan:

**Parallel Groups:**

- Group 1: [skill-3, skill-4] (both depend only on skill-2)
- Group 2: [skill-7, skill-8] (independent of each other)

**Sequential Constraints:**

- skill-5 MUST wait for Group 1 completion
- skill-6 MUST wait for skill-5

Phase 2: Execution Planning

Step 2.1: Create Execution Plan

## Execution Plan

### Phase 1: Initialization

**Skills**: [skill-1](%5BPurpose%5D)
**Estimated Duration**: [X min]
**Output**: [Description]

### Phase 2: Parallel Processing

**Skills**: [skill-3, skill-4] (parallel)
**Dependencies**: Phase 1 complete
**Estimated Duration**: max([skill-3 duration], [skill-4 duration])
**Outputs**:

- skill-3: [output]
- skill-4: [output]


### Phase 3: Synthesis

**Skills**: [skill-5]
**Dependencies**: Phase 2 complete
**Inputs**: Outputs from skill-3 AND skill-4
**Estimated Duration**: [Y min]
**Output**: [Description]

### Phase 4: Finalization

**Skills**: [skill-6]
**Dependencies**: Phase 3 complete
**Estimated Duration**: [Z min]
**Output**: [Final deliverable]

**Total Estimated Duration**: [X + max(skill-3,skill-4) + Y + Z] min

Step 2.2: Resource Allocation

## Resource Budget

**Token Budget**: [Total tokens]

- skill-1: [tokens]
- skill-2: [tokens]
- ...
- Orchestration overhead: [tokens]

**Time Budget**: [Total time]

- Sequential time: [sum of sequential]
- Parallelization savings: [time saved]
- Net time: [actual estimated time]

**External Resources:**

- MCP Server calls: [count]
- Agent invocations: [count]

Phase 3: Orchestrated Execution

Step 3.1: Execute Sequential Skills

For each sequential skill:

### Execute: [skill-name]

1. **Prepare Input:**

```json
{
  "parameter1": "value from previous skill or requirement",
  "parameter2": "value",
  "context": {
    // Context from previous steps
  }
}

2. Invoke Skill: "Use [skill-name] skill with the input above"
3. Capture Output:

{
  "execution_id": "[skill-exec-id]",
  "status": "success | failure",
  "output": {
    // Skill output
  },
  "metadata": {
    "duration": "[X min]",
    "tokens_used": "[Y]"
  }
}

4. Validate Output:
   • [ ] Status = success
   • [ ] Output format matches expected
   • [ ] Quality criteria met
5. Store for Next Phase: Save output to orchestration context:

{
  "workflow_context": {
    "[skill-name]_output": {
      // Output data
    }
  }
}

#### Step 3.2: Execute Parallel Skills

For parallel skill groups:

Execute Parallel Group: [group-name]

Skills in Group: [skill-A, skill-B, skill-C]

Launch All:

1. Prepare inputs for each skill
2. Invoke all skills concurrently:
   • "Use skill-A with input-A"
   • "Use skill-B with input-B"
   • "Use skill-C with input-C"

Track Completion:

{
  "parallel_group_status": {
    "skill-A": "running",
    "skill-B": "running",
    "skill-C": "running"
  }
}

Wait for All Completions: Monitor each skill until all complete

Collect Results:

{
  "parallel_group_results": {
    "skill-A": {
      "status": "success",
      "output": {},
      "duration": "X min"
    },
    "skill-B": {
      "status": "success",
      "output": {},
      "duration": "Y min"
    },
    "skill-C": {
      "status": "success",
      "output": {},
      "duration": "Z min"
    }
  },
  "group_duration": "max(X,Y,Z) min"
}

Validate All Outputs:

• [ ] All skills completed successfully
• [ ] All outputs valid
• [ ] Ready for next phase

#### Step 3.3: Handle Errors and Recovery

Error Handling

IF any skill fails:

1. Assess Impact:
   • Critical skill? (blocks entire workflow)
   • Optional skill? (can proceed without)
2. Attempt Recovery:

IF retryable error:
    Retry skill (max 2 retries)
    IF retry succeeds:
        Continue workflow
    ELSE:
        Proceed to Step 3

3. Decide Path Forward:

IF critical skill failed:
    - Use fallback approach if available
    - Request human intervention
    - Abort workflow with detailed error report

IF optional skill failed:
    - Log warning
    - Continue with partial results
    - Note limitation in final output

4. Document Failure:

{
  "workflow_errors": [
    {
      "skill": "skill-name",
      "phase": "phase-N",
      "error": "error message",
      "recovery_attempted": true,
      "recovery_successful": false,
      "impact": "critical | degraded | minimal"
    }
  ]
}

### Phase 4: Result Synthesis

#### Step 4.1: Aggregate Outputs

Synthesize Results

Collect all skill outputs:

{
  "workflow_results": {
    "skill-1": { "output": {} },
    "skill-2": { "output": {} },
    "skill-3": { "output": {} },
    "skill-4": { "output": {} },
    "skill-5": { "output": {} }
  }
}

Synthesize into final deliverable:

1. Extract key components from each skill
2. Combine according to workflow spec
3. Resolve any conflicts or overlaps
4. Format per requirements

#### Step 4.2: Quality Validation

Validate Final Output

Run validation checks:

Completeness:

• [ ] All required components present
• [ ] No missing data from any skill

Consistency:

• [ ] Outputs from different skills align
• [ ] No contradictions
• [ ] Unified format

Quality:

• [ ] Meets acceptance criteria
• [ ] Performance within targets
• [ ] No errors or warnings

IF validation fails:

• Identify which skill output is problematic
• Re-run that skill with adjustments
• Re-synthesize
• Re-validate

### Phase 5: Reporting and Handoff

Orchestration Summary Report

Workflow: [Workflow Name] Execution ID: [unique-id] Timestamp: [ISO 8601] Total Duration: [X min] Total Tokens: [Y tokens]

Execution Trace:

| Phase | Skills | Status | Duration | Tokens | | :-- | :-- | :-- | :-- | :-- | | 1 | skill-1 | ✅ Success | X min | Y tokens | | 2 | skill-3, skill-4 | ✅ Success | Z min | W tokens | | 3 | skill-5 | ✅ Success | A min | B tokens | | 4 | skill-6 | ✅ Success | C min | D tokens |

Parallelization Savings: [Time saved by parallel execution]

Quality Metrics:

• Success Rate: [100%]
• Average Quality Score: [95%]
• Performance: [Within targets]

Outputs:

• Primary Deliverable: [Location/description]
• Supporting Artifacts: [List]

Issues Encountered:

• Issue 1: [How resolved]
• Issue 2: [How resolved]

Recommendations:

• [Recommendation for future runs]
• [Optimization opportunity]

## Examples

### Example 1: Multi-Skill Content Generation Workflow

**Workflow**: Generate technical blog post with code examples, diagrams, and SEO optimization

**Skills Involved:**
1. `research-skill`: Gather technical information
2. `code-example-generator`: Create code snippets
3. `diagram-generator`: Create architecture diagrams
4. `content-writer`: Write blog post content
5. `seo-optimizer`: Optimize for search engines
6. `proofreader`: Final quality check

**Execution:**

Phase 1: Research (Sequential)

Execute: research-skill Input: "Gather information on microservices architecture patterns" Output: research-notes.md (3500 words of research)

Phase 2: Parallel Content Creation

Execute in parallel:

• code-example-generator (uses research output) Output: code-examples/ (5 code snippets)
• diagram-generator (uses research output) Output: diagrams/ (3 architecture diagrams)

Wait for both to complete Duration: max(code gen: 8min, diagrams: 12min) = 12min

Phase 3: Content Writing (Sequential)

Execute: content-writer Inputs:

• research-notes.md
• code-examples/
• diagrams/ Output: blog-draft.md (2000 word article)

Phase 4: Parallel Optimization (Parallel)

Execute in parallel:

• seo-optimizer (optimize blog-draft.md) Output: blog-seo-optimized.md
• proofreader (review blog-draft.md) Output: proofreading-notes.md

Wait for both Duration: max(SEO: 5min, proof: 7min) = 7min

Phase 5: Finalization (Sequential)

Synthesize:

• Merge SEO optimizations
• Apply proofreading corrections
• Generate metadata

Final Output: published-blog-post.md

• 2000 words
• 5 code examples
• 3 diagrams
• SEO optimized
• Proofread

Total Duration:

• Sequential: research(10) + writing(15) + synthesis(3) = 28min
• Parallel savings: Would be 40min without parallelization
• Actual: 28 + max(12,7) = 40min vs 55min = 15min saved

### Example 2: Code Review Orchestration

**Workflow**: Comprehensive PR review using multiple specialized skills

**Skills:**
1. `pr-analyzer`: Extract PR metadata
2. `security-scanner`: Security vulnerability scan
3. `performance-profiler`: Performance analysis
4. `test-coverage-checker`: Test coverage validation
5. `code-quality-checker`: Code quality metrics
6. `review-synthesizer`: Compile final review

**Orchestration:**

Phase 1: Analysis

skill-1 (pr-analyzer) Output: PR metadata, changed files, commit history

Phase 2: Parallel Checks (All independent)

Parallel execution: ├─ skill-2 (security-scanner) ├─ skill-3 (performance-profiler) ├─ skill-4 (test-coverage-checker) └─ skill-5 (code-quality-checker)

All use PR metadata from Phase 1 Wait for all 4 to complete

Phase 3: Synthesis

skill-6 (review-synthesizer) Inputs: All 4 reports from Phase 2 Output: Comprehensive review document

Result:

PR Review Summary

Security: ⚠️ 1 medium vulnerability found

• CVE-2024-XXXX in dependency X
• Recommendation: Upgrade to v2.3.1

Performance: ✅ No issues

• No N+1 queries
• Response times within targets

Test Coverage: ✅ 94%

• Exceeds 90% requirement
• All critical paths covered

Code Quality: ✅ High

• Complexity within limits
• No code smells
• Follows style guide

Overall: APPROVED WITH COMMENTS Merge after addressing security finding

## Quality Standards

- All skill invocations must include unique execution_id
- Parallel skills must be truly independent (no hidden dependencies)
- Token budget must account for orchestration overhead (+20%)
- Error recovery must be implemented for each skill
- Final synthesis must resolve conflicts between skill outputs

## Common Pitfalls

### Pitfall 1: Hidden Dependencies in "Parallel" Skills
**Issue**: Skills marked as parallel actually depend on each other
**Example**: skill-A modifies file that skill-B reads
**Solution**: Carefully analyze data dependencies before parallelizing

### Pitfall 2: No Timeout for Long-Running Skills
**Issue**: Workflow hangs waiting for stuck skill
**Solution**: Implement timeout for each skill with fallback

Execute with Timeout

timeout = 15 minutes start_time = now()

invoke skill-X

while skill-X not complete: if (now() - start_time) > timeout: log error attempt graceful degradation break

### Pitfall 3: Poor Error Aggregation
**Issue**: One skill failure causes unclear error
**Solution**: Aggregate errors with context

{ "workflow_status": "partial_failure", "successful_skills": ["skill-1", "skill-3", "skill-5"], "failed_skills": [ { "skill": "skill-4", "error": "API timeout", "impact": "missing performance analysis in final report", "workaround": "manual performance review recommended" } ], "final_output": "available with noted limitations" }

## Version History
- 1.0.0 (2025-11-22): Initial release