Using Orchestrator

Using-Orchestrator (Auto-Skill Dispatch)

Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see skills/_shared/instruction-file-resolution.md. Wherever this skill mentions CLAUDE.md, the alias rule applies.

Internal dispatch meta-skill. Never invoked directly by the user. Called by entry-point skills once after the bootstrap gate opens, before their Phase 1, when auto-skill-dispatch: true is set in Session Config.

When This Skill Runs

This skill is opt-in and off by default. Check the Session Config flag before any action:

# CLAUDE.md (or AGENTS.md on Codex CLI) — Session Config default
auto-skill-dispatch: false

When the flag is false (or absent), this skill MUST return immediately without reading any messages, without logging, and without side effects. The calling skill continues to its own Phase 1 as if this skill was never invoked.

When the flag is true, proceed with the dispatch algorithm below.

Default Behavior

When auto-skill-dispatch: false: do nothing. Return silently. This is the shipped default. Zero behavior change for all existing call sites.

How Dispatch Works

1. Read the user's first message from the current conversation context. "First message" is the earliest human turn in the session — the message that triggered the skill chain.

2. Run the phrase map (see section below) against the message text. Apply case-insensitive matching. Compute a confidence score for each candidate skill (see "Confidence Scoring").

3. Select the dispatch target:

   • If zero skills score ≥ 0.85: no dispatch. Return silently — the calling skill handles routing normally.
   • If exactly one skill scores ≥ 0.85: dispatch immediately via Skill tool to that target's entry point. Do not ask the user.
   • If two or more skills score ≥ 0.85 AND the delta between the top two scores is < 0.15: disambiguate via AskUserQuestion (see "AUQ Disambiguation" below) before dispatching. Never silently pick one — see Anti-Patterns.

4. Dispatch is a single Skill tool invocation to the target skill's SKILL.md. Pass the original user message as context. Do not re-interpret or rewrite the message.

AUQ Disambiguation

When two or more candidates score ≥ 0.85 with delta < 0.15, call AskUserQuestion per .claude/rules/ask-via-tool.md (AUQ-003):

AskUserQuestion({
  questions: [{
    question: "Your message matches multiple workflows. Which one did you mean?",
    header: "Skill Dispatch",
    multiSelect: false,
    options: [
      { label: "<top-skill display name> (Recommended)", description: "<one-line description of what it does>" },
      { label: "<second-skill display name>", description: "<one-line description>" }
    ]
  }]
})

List candidates in descending confidence order. Mark the highest-confidence match (Recommended). Wait for the user's selection before dispatching.

Phrase Map

Case-insensitive. Partial matches score lower than exact matches (see Confidence Scoring).

Confidence Scoring

Each candidate skill is scored against the user's first message using this scale:

Dispatch threshold: 0.85. Only scores ≥ 0.85 trigger auto-dispatch or AUQ.

Disambiguation delta: when the top two candidate scores differ by < 0.15, use AUQ before dispatching. When the delta is ≥ 0.15, dispatch to the top-scoring skill without asking.

Scores below 0.85 are silently discarded. The calling skill handles routing via its own Phase 1 logic.

Anti-Patterns

• Never silently dispatch on an ambiguous match. When delta < 0.15 between top two candidates, AUQ is mandatory. Picking the "more likely" one without asking is a bug.
• Never bypass AUQ when delta < 0.15. The rule from .claude/rules/ask-via-tool.md applies: every routing decision the user should control goes through the tool.
• Never dispatch on scores < 0.85. A partial match at 0.60 is not a dispatch signal — it is noise. Let the calling skill handle the message normally.
• Never rewrite the user's message before passing it to the dispatched skill. Preserve the original text so the target skill can apply its own parsing.
• Never run when auto-skill-dispatch: false. Check the flag first, every time. There is no "probably fine to run anyway" path.

Source: hashgraph-online/awesome-codex-plugins → plugins/Kanevry/session-orchestrator/skills/using-orchestrator/SKILL.md