orchestration-skill-creator

Orchestration Skill Creator

This meta-skill creates orchestration skills - skills that spawn subagents for multi-phase workflows.

Why This Pattern Works (The Big Deal)

The Problem: Claude has a fixed 200k context window. Complex tasks fill it up, quality degrades after 40%.

The Solution: Spawn subagents. Each phase gets fresh 200k context.

This is context multiplication, not just organization.

Each phase:

• Gets fresh context (no pollution from previous work)
• Returns only a summary (orchestrator stays clean)
• Has dedicated model selection (expensive only where needed)
• Can be retried independently (errors don't cascade)

What You'll Get

A complete orchestration skill with:

{skill-name}/
├── SKILL.md                    # Orchestrator (coordinates, doesn't DO)
├── agents/
│   ├── phase-1-{name}.md       # Subagent prompts with frontmatter
│   ├── phase-2-{name}.md       # Note: phase-N (with hyphen)
│   └── phase-N-{name}.md
├── references/
│   ├── 00-{general}.md         # Patterns all agents read
│   ├── 01-{phase1-specific}.md # Phase-specific reference
│   └── output-templates.md     # JSON contracts
├── scripts/
│   ├── init-project.sh         # Setup automation
│   └── verify-output.sh        # Validation automation
└── reports/                    # Output: {project}/{timestamp}/

Undocumented but Works: The agents/ folder pattern is NOT in Anthropic docs. It works because:

• Skills are folders with SKILL.md (no restriction on contents)
• Task tool accepts any prompt (including from files)
• Claude can read files → pass to Task → subagent executes

Workflow

Phase 1: Interview

Ask these questions using AskUserQuestion tool. Gather all answers before generating.

Q1: Skill Name

"What should this orchestration skill be called?"
Header: "Name"
Options:
- [Let user type - use Other]
Example: "content-pipeline", "document-analyzer", "meeting-prep"

Q2: Purpose

"In one sentence, what does this workflow do?"
Header: "Purpose"
Options:
- [Let user type - use Other]
Example: "Analyzes documents and produces structured summaries"

Q3: Trigger Phrases

"What phrases should trigger this skill?"
Header: "Triggers"
Options:
- [Let user type - use Other]
Example: "analyze document", "summarize this doc", "document analysis"

Q4: Number of Phases

"How many phases does this workflow have?"
Header: "Phases"
Options:
- "3 phases" - Simple workflow
- "4 phases" - Standard workflow
- "5 phases" - Comprehensive workflow
- "6+ phases" - Complex workflow (specify number)

Q5: Phase Details (repeat for each phase)

For each phase, ask:

"Phase {N}: What should this phase be called and what does it do?"
Header: "Phase {N}"
Options:
- [Let user describe - use Other]
Format expected: "{name}: {description}"
Example: "discovery: Find and collect relevant sources"

Q6: Model Selection per Phase

"Which phases need deep reasoning (Opus) vs speed (Sonnet) vs simple execution (Haiku)?"
Header: "Models"
Options:
- "All Sonnet" - Balanced for most workflows
- "All Opus" - Deep reasoning throughout (expensive)
- "Mixed" - Right model per phase (Recommended)

If Mixed, default assignment:

Default to Opus for any phase where quality matters. Cost is irrelevant with Claude Max.

Q7: Output Location

"Where should reports be saved?"
Header: "Output"
Options:
- "Inside skill folder" - ~/.claude/skills/{skill}/reports/ (Recommended)
- "User's home" - ~/Documents/{skill}-reports/
- "Current project" - ./{skill}-reports/

Phase 2: Generate Files

After gathering all answers, generate these files:

2.1: Create Directory Structure

SKILL_DIR=~/.claude/skills/{skill-name}
mkdir -p $SKILL_DIR/{agents,references,assets/templates,scripts,reports}

2.2: Generate SKILL.md

Use template from: references/skill-md-template.md

Fill in:

• {SKILL_NAME} - from Q1
• {DESCRIPTION} - from Q2, expanded with trigger info
• {TRIGGER_PHRASES} - from Q3
• {PHASE_COUNT} - from Q4
• {PHASE_LIST} - names from Q5
• {PHASE_FLOW} - generated diagram
• {OUTPUT_DIR} - from Q7

2.3: Generate Agent Files

For each phase, use template from: references/agent-template.md

Fill in:

• {PHASE_NUM} - 1, 2, 3...
• {PHASE_NAME} - from Q5
• {MODEL} - from Q6 (sonnet or opus)
• {TOOLS} - inferred from phase description:
  • Search/find → WebSearch, WebFetch
  • Analyze/read → Read, WebFetch
  • Synthesize/write → Write, Read
  • Verify → WebSearch, Read
  • All phases get Write for reports
• {TASK_DESCRIPTION} - from Q5
• {PREV_PHASE_READS} - phases 2+ read previous reports
• {REPORT_FILENAME} - 0{N}-{phase-name}.md

2.4: Generate References

orchestrator-flow.md: Generate flow diagram showing:

• Phase sequence
• Data passed between phases
• Session directory structure

json-response-format.md: Generate JSON contracts for each phase based on what they produce.

2.5: Generate Templates

session-init.json: JSON state template with all phases listed.

init-session.sh: Bash script to create timestamped session directories.

Phase 3: Verify & Present

After generating all files:

1. List created files:

Created orchestration skill: {skill-name}

Files generated:
- SKILL.md (orchestrator)
- agents/phase1-{name}.md
- agents/phase2-{name}.md
- ...
- references/orchestrator-flow.md
- references/json-response-format.md
- assets/templates/session-init.json
- scripts/init-session.sh

2. Show how to use it:

To use this skill, say:
"{trigger phrase} [your input]"

Example:
"{example trigger} {example input}"

3. Offer refinement:

Want me to adjust any phase or add more detail to the agent instructions?

Generation Rules

Agent Tool Assignment

Model Assignment (Mixed mode)

Quality principle: Default to Opus for any phase where output quality matters. Cost is irrelevant with Claude Max.

Report Naming Convention

0{phase_number}-{phase-name}.md

Examples: 01-discovery.md, 02-analysis.md, 03-synthesis.md

JSON Response Contract

Every agent returns:

{
  "status": "complete|partial|error",
  "report_path": "{session_dir}/0N-phase-name.md",
  "{phase_name}_summary": {
    // Phase-specific metrics
  }
}

File References

• references/skill-md-template.md - Template for orchestrator SKILL.md
• references/agent-template.md - Template for phase agents
• references/flow-template.md - Template for flow documentation
• references/json-template.md - Template for JSON contracts
• references/common-patterns.md - 10 workflow patterns + 6 structural archetypes
• references/script-templates.md - Bash script templates for automation
• assets/templates/session-init-template.json - Template for state file
• assets/templates/init-session-template.sh - Template for init script

Key Learnings Applied

This skill creator incorporates learnings from building fullstack-app-builder:

1. Context multiplication - Each phase gets fresh 200k, not shared degrading context
2. Progressive data flow - Later phases receive more previous context as needed
3. Model optimization - Opus for complex reasoning, Sonnet for code gen, Haiku for simple execution
4. Reference doc linking - Agents read ${SKILL_DIR}/references/ at runtime
5. Scripts for heavy lifting - Bash does repetitive work, Claude does thinking
6. TodoWrite ownership - ONLY orchestrator uses TodoWrite, agents return JSON
7. SKILL_DIR passing - Agents need path to find references and scripts