Brainforge Knowledge

skill-orchestrator-best-practices

5 min read

Skill orchestrators — what they are, how they work, how to add one

Audience: Anyone authoring or refactoring Cursor/Codex/OpenCode skills in brainforge-platform.
Companion: .cursor/rules/bugbot-derived-patterns.mdc (checklist), .cursor/rules/skill-and-playbook-discovery.mdc (discovery gate), .opencode/skill-routing.md (intent table).

What is a skill orchestrator?

A skill orchestrator is a single first-party skill (<domain>-orchestrator/SKILL.md) that replaces several narrowly named skills by exposing multiple --mode <name> workflows behind one entry point.

Examples:

  • linear-orchestrator — Platform ship loop, project updates, roadmap structure, labels, SOW alignment, status sync, structure hygiene (formerly many linear-* skills).
  • partner-orchestrator — Partner Slack ops, HubSpot, broadcasts, event ops, tiering, etc.
  • audit-orchestrator — Escalation triage, ops triage, SOW vs delivered, Operating.app audits.

Why use them

  • One description and one place to maintain shared prerequisites (MCP ids, approval gates, vault paths).
  • Clearer routing: users say “Linear stuff” or “partner broadcast” without memorizing ten skill names.
  • Fits auto-invoke: when a Cursor rule maps exactly one orchestrator and one mode, the agent can jump straight to --mode … (see below).

Related pattern (not always named *orchestrator)

  • partnership-daily-loop — Multiple modes (activity-signals, eod-payload, marketing-hub) with the same consolidation goals.

How orchestrators are wired (four layers)

1. Skill implementation — .cursor/skills/<name>/SKILL.md

Canonical tree is .cursor/skills/ (.agents/skills/ symlinks to it).

Each orchestrator SKILL.md should include:

  • Rich YAML description — Third person; list modes and trigger phrases so implicit invocation works (matches Codex/Cursor discovery).
  • allowed-tools — Every tool the skill actually uses (Read, Write, StrReplace, Glob, Grep, Shell, call_mcp_tool, …). Missing entries are a recurring review-bot finding.
  • department and workflow — Required for inclusion in .cursor/skills/SKILL_INDEX.md. Use YAML lists when cross-cutting.
  • Mode resolution — Document in order:
    1. Honor explicit --mode (or equivalent user wording).
    2. Infer mode from phrases / tables.
    3. STOP AND ASK when multiple modes fit; never guess destructive or bulk-write modes.
  • Per-mode sections — Preconditions, defaults, steps, and confirmation gates before external writes.
  • Mutating vs read-only — Audit-only paths must not imply writes; one explicit confirmation before destructive/bulk changes.

Keep SKILL.md under ~500 lines where possible; push long annexes to references/ and link one level deep.

2. Cursor routing rule — .cursor/rules/<name>-orchestrator.mdc

Many orchestrators have a matching alwaysApply: false rule with:

  • Short when to use bullet list (user phrases).
  • Instruction to open .cursor/skills/<name>-orchestrator/SKILL.md.
  • Auto-invoke table: phrase → --mode <mode> when unambiguous; if ambiguous, invoke the skill without --mode and let STOP AND ASK run.

This pairs with .cursor/rules/skill-and-playbook-discovery.mdc: exactly one rule match + clear mode → agent may invoke immediately with --mode; otherwise list matches and wait.

3. OpenCode routing table — .opencode/skill-routing.md

Keeps a human-readable intent → skill → modes table for headless/OpenCode flows. Update it when adding an orchestrator or a new mode.

4. Optional: thin shims / aliases

When consolidating legacy skills, leave a small SKILL.md that sets alias_of / says “invoke <orchestrator> --mode X” so old names still resolve (see existing partner-* shims). Prefer one orchestrator body as source of truth.

Orchestrator-first decision (before creating a skill)

From .cursor/rules/bugbot-derived-patterns.mdc:

  1. Read .cursor/skills/SKILL_INDEX.md and scan existing mode-driven orchestrators (see .opencode/skill-routing.md for the current table).
  2. If the workflow fits the same domain, tools, and approval pattern as an existing orchestrator, add a new mode (new section + triggers + routing updates) instead of a new top-level skill directory.
  3. Create a standalone skill only when no orchestrator fits, tools/flow diverge strongly, or you need a high-traffic shortcut that should not share a description with unrelated modes.

Full rationale and steps: this document; quick checklist: bugbot patterns.

How to add a new mode to an existing orchestrator

  1. Edit .cursor/skills/<orchestrator>/SKILL.md — Add triggers to the description frontmatter; add Mode resolution rules; add a Mode: mode-name section (steps, gates, MCP notes).
  2. Edit .cursor/rules/<orchestrator>.mdc — Add user phrases and auto-invoke mapping for the new mode when unambiguous.
  3. Edit .opencode/skill-routing.md — Add or extend the row for intents/modes.
  4. Run npm run skills:index if department / workflow / description changed in ways that affect discovery.
  5. If legacy skill name should keep working, add or update a shim SKILL.md pointing at the new mode.

How to introduce a new orchestrator

Use when several same-domain workflows share MCPs, vault paths, and governance but no existing orchestrator covers them.

  1. Name — <domain>-orchestrator (consistent suffix helps grep and rules).
  2. Create .cursor/skills/<domain>-orchestrator/SKILL.md with frontmatter + mode skeleton (start with 2+ modes or a clear roadmap to a second mode).
  3. Create .cursor/rules/<domain>-orchestrator.mdc describing triggers and auto-invoke mapping.
  4. Register in .opencode/skill-routing.md.
  5. Register discovery — Ensure department / workflow are set; run npm run skills:index.
  6. Cross-link — Add a bullet to AGENTS.md skill routing line only if this changes global routing counts or introduces a major entry point (optional; prefer skill-routing.md + rule).

Prefer consolidating legacy standalone skills into the new orchestrator with shims rather than deleting names abruptly.

Verification checklist

  • allowed-tools matches real tool usage across all modes.
  • STOP AND ASK documented for ambiguous intents; no silent picks for write modes.
  • Linear / HubSpot / Slack (etc.) — correct MCP server id from .cursor/mcp.json; read tool descriptors before calling (no invented fields).
  • PR / ship loop — Mutating platform work still follows .cursor/rules/agent-ship-loop.mdc where applicable.
  • .opencode/skill-routing.md and orchestrator .mdc rule updated in the same PR as the SKILL.md change when modes change.

References

  • .cursor/rules/skill-and-playbook-discovery.mdc — discovery gate and auto-invoke behavior.
  • .cursor/rules/bugbot-derived-patterns.mdc — skill frontmatter and orchestrator-first checklist.
  • .opencode/skill-routing.md — orchestrator ↔ mode intent table.
  • Example orchestrator: .cursor/skills/linear-orchestrator/SKILL.md + .cursor/rules/linear-orchestrator.mdc.
  • Skill authoring (generic structure): upstream skill-creator in the anthropic-skills submodule (reachable via the skill-creator symlink under .cursor/skills/). Cursor’s built-in create-skill includes a Brainforge callout pointing at this file when the workspace is this monorepo. .cursor/skills/README.md summarizes orchestrators for day-to-day invocation.

Graph View