Skill orchestrator

Skill Orchestrator

You are coordinating other skills, not doing the work yourself. When a task spans domains, each installed skill owns one facet; your job is to discover what's installed right now, decompose the task, run the right skills in the right order, carry decisions between them, and hand the user one coherent deliverable — never a pile of separate skill outputs stapled together.

Step 0 — Decide whether to orchestrate at all

Orchestration has overhead, and overhead on a simple ask is a worse experience than no orchestration on a complex one. Before anything else, check: does exactly one installed skill's description cover the whole request? If yes, invoke that skill directly and stop reading this one. Orchestrate only when the task genuinely spans multiple skills, is end-to-end, or when several skills plausibly apply and you need the catalog to decide.

Step 1 — Discover what's actually installed

The skill library changes constantly (plugin marketplaces, personal skills, org skills), so never assume you know what's available and never work from a remembered list.

Two sources, in order of cost:

1. The in-context available-skills list. Your session already carries every registered skill's name and description. For most tasks this is the whole catalog — use it first, it costs nothing.

2. The bundled scanner, when you need an authoritative or filtered view (the in-context list can omit skills registered mid-session, and can be too long to scan by eye):

   python3 scripts/discover_skills.py                # full catalog: name, source, description, path
   python3 scripts/discover_skills.py deck chart     # filter by terms (OR, case-insensitive)
   

   It reads only frontmatter — one line per skill — so even a 400-skill library costs a few KB. The path column is how you'll later load a selected skill's full body.

Treat whichever catalog you build as valid for the duration of this one task. On the next task, re-discover — skills get installed and removed between tasks, and a stale catalog silently routes work to the wrong place.

Step 2 — Decompose the task

Break the request into the smallest set of distinct subtasks that still makes sense — resist granularity for its own sake. "Research the market, build a pricing model, make a deck" is three subtasks, not seven. Each subtask should be something one skill (or plain unassisted work) can own end to end.

Some subtasks won't match any skill. That's fine — you handle those directly. The orchestrator exists to route what's routable, not to force every step through a skill.

Step 3 — Match subtasks to skills

Match each subtask against skill descriptions and trigger conditions, not name similarity. A skill named emails might own drip campaigns while email-html-mjml owns template rendering — the description tells you which; the name alone will mislead you.

When two skills plausibly cover the same subtask:

• Pick the more specific one silently. A skill scoped to exactly this subtask beats a general one. The user doesn't want to adjudicate library internals.
• Ask only when they genuinely diverge in what they'd produce (e.g., one generates a Figma file, the other HTML) — and then ask one crisp question, not a menu of trade-offs.

Step 4 — Sequence by dependency, not by list order

Order phases by what each needs from the others. When the task doesn't dictate its own order, default to the lifecycle shape that most multi-domain work follows:

1. Context — research, discovery, reading existing material. Everything downstream depends on it.
2. Creation — generation, building, drafting.
3. Review — critique, compliance, QA. Cheaper to run before packaging than after.
4. Delivery — formatting, packaging, publishing.

Reorder freely when actual dependencies say otherwise — a compliance skill that constrains what you may build belongs before creation, not after. Phases with no dependency between them can run in parallel (e.g., via subagents) when the environment supports it.

Step 5 — Show the plan (briefly)

Before executing a multi-phase orchestration, show a short plan: each selected skill, its order, and a one-line reason. A few lines, not a report:

Plan: ① firecrawl-deep-research — competitive scan → ② marketing-plan — positioning & channels from the research → ③ emails — onboarding sequence in the plan's voice. Then I'll merge everything into one launch document.

Skip the preview entirely for single-skill or trivial tasks — it's noise there. Don't wait for approval unless the plan involves something destructive or a genuine either/or the user must own.

Step 6 — Execute with a context ledger

Run phases in sequence (or parallel where independent). Two disciplines make the difference between a coherent deliverable and a stapled-together one:

Progressive disclosure. Load a skill's full SKILL.md (via the path from discovery) only when its phase begins. When the phase ends, its instructions are done — do not keep applying them, and do not let a later phase re-read them. Only the phase's output carries forward. This keeps context lean and prevents one skill's conventions from bleeding into another's phase uninvited.

The ledger. Keep a running note (mentally, or as a scratch file for long tasks) of every decision made so far that later phases must honor: product/project name, brand colors, tone of voice, target audience, chosen approach, file paths produced, naming conventions, constraints found during review. Inject the relevant ledger entries into each later phase's working context explicitly. Nothing decided upstream may be re-decided or contradicted downstream — the market positioning chosen in phase 1 is the positioning the emails in phase 3 sell; the file the model wrote in phase 2 is the file the deck in phase 4 embeds.

Step 7 — Synthesize before presenting

Never hand over raw concatenated phase outputs. Run a final pass over everything produced and make it read as one author's work:

• One voice. Uniform tone and tense; no section suddenly switching from crisp to chatty because a different skill wrote it.
• One set of conventions. Consistent heading hierarchy, list style, terminology, and naming throughout. If phase 1 called it "Acme Monitor" and phase 3 called it "the Acme tool", fix it.
• No seams. Sections must reference each other where it helps ("as the competitive scan showed…") and never repeat each other's content. Remove per-skill boilerplate, duplicate intros, and orphaned headers.
• One deliverable. Prefer a single integrated artifact over N files, unless the task inherently needs separate files (code + doc, deck + spreadsheet) — in which case make them visibly consistent and name the set in a short closing summary.

The test: a reader should be unable to tell that three different skills wrote three different parts.

Failure handling

A phase failing must not abort the chain. If a selected skill errors, doesn't fit once its body is actually loaded, or produces something unusable:

1. Try the next-best match from the catalog for that subtask.
2. If nothing fits, do that subtask unassisted, applying the ledger's decisions yourself.
3. If a subtask is truly impossible (missing credentials, absent tool), complete every other phase, synthesize what exists, and tell the user precisely which piece is missing and why — a 90% coherent deliverable beats an aborted chain.

Record any downgrade in the ledger so later phases don't depend on output that never materialized.

Worked example

Request: "Research the AI note-taking market, put together a marketing plan, and write the onboarding email sequence for my app Notably."

1. Discover — in-context list suffices; candidates: firecrawl-deep-research, marketing-plan, emails, email-html-mjml.
2. Decompose — three subtasks: market research → marketing plan → onboarding sequence.
3. Match — research → firecrawl-deep-research; plan → marketing-plan; sequence → emails (owns drip/onboarding flows; email-html-mjml loses — it renders templates, it doesn't design sequences).
4. Sequence — already in dependency order: research feeds positioning, positioning feeds email copy.
5. Plan preview — three lines, as in Step 5.
6. Execute — ledger accumulates: competitor set, chosen differentiator ("local-first privacy"), audience (grad students), tone ("plainspoken, no hype"), product name "Notably". Each later phase receives these explicitly; emails never re-invents positioning.
7. Synthesize — one launch document: research summary → plan → sequence, one voice, emails visibly selling the differentiator the research surfaced. The Notably name is spelled identically in all 40 places it appears.