Capability Broker

The acquisition arm of the Bridge learning loop. The other arms look backward and refine what exists (task-close-postmortem, bridge-audit, bridge-curator); this one looks forward and gains a new capability — a tool or a skill — when the user hits something the Bridge can't do yet.

It proposes, it never auto-acts. Every install, every outward step, every persistent write is propose-then-confirm. Same human-gate-at-every-layer posture as rules/learning-autonomy.md — this skill is bound by that rule, not an exception to it.

Read this file only when triggered. Full procedures live in references/ (progressive disclosure) — load the one you need, not all four.

When this skill runs

The flow (one screen)

1. Guard — confirm it's a true gap, not a false one. → references/gap-detection.md
2. Offer — one question, four routes. Never silently fail or silently one-off.
3. Route:
   • [r] research + provision a tool → references/research-playbook.md → decision tree
   • [s] scaffold a skill → decision tree → hand to skill-creator
   • [o] one-off → do it now, ledger note only
   • [d] decline → ledger note, cooldown
   • decision tree (provision vs skill vs both) → references/provision-vs-skill.md
4. Capture — write the learning so it compounds. → references/learning-capture.md

1. Guard — true gap vs false gap

Before offering, run the cheap guard (full steps in references/gap-detection.md). Five outcomes:

• T1 true gap — no skill, no wired tool, not native → offer (step 2).
• T2 dormant skill — a skill plausibly covers it but didn't fire → load it; if it mis-triggered, log a trigger-correction (existing loop). Stop — not this skill's job.
• T3 native — Claude can already do it with built-in tools → just do it.
• T4 one-off — real but single-use → do it ad-hoc, ledger note.
• T5 declined/policy — declined this session or must-not-do → silent / refuse.

The skill sweep (grep skills/*/SKILL.md for the capability's keywords) is the critical guard: err toward "a skill might cover this → load it, don't offer."

2. Offer

On T1, surface exactly one offer — never more than one per gap:

🧩 Capability gap: <one line — what you asked for that I can't do yet>.
   I can make this stick, or just do it once. Your call:

   [r] Research + provision a tool   — find the right CLI/MCP/service, install & wire it
   [s] Scaffold a dedicated skill    — build a reusable Bridge skill for it
   [o] One-off, don't persist        — do it this once, no new capability
   [d] Not now / decline             — drop it (won't re-offer this session)

The offer is non-destructive. Everything after it is gated (step 3).

3. Route — gates

• Research is read-only (web + local inspection). Nothing installed, nothing sent outward beyond search queries. → references/research-playbook.md.
• Provision needs a per-action [y] for each install / wire / auth step. Credential creation and other outward/irreversible steps stay behind the Bridge's existing hard gates — this skill routes to them, never bypasses them.
• Scaffold writes only under skills/<new>/, only after [s] (or research→tree→skill), and hands authoring to the skill-creator skill.
• The provision-vs-skill call (infrastructure vs procedure vs both) is in references/provision-vs-skill.md. BOTH = provision the tool first, then the skill that wraps it.

4. Capture — make it compound

Every outcome writes a learning (full shapes in references/learning-capture.md):

• A proposal in work/_learning/proposals/ with source.type: capability-gap, an evidence chain, a target (the new skill / tool / account file), and a scope (core if generic → open-bridge roadmap candidate via /bridge-sync; user/org if instance-specific).
• A ledger row in work/_learning/capability-gaps.md (append-only) with the disposition and a recurrence counter — a one-off gap seen ≥ N times escalates to a "persist now" proposal.
• The artifact (the scaffolded skill / wired tool) is the durable gain.
• Optionally a memory (a non-obvious tool-choice decision or auth gotcha) via the existing proposal target.type: memory path — human-approved.

Acceptance of any proposal stays with /bridge-learn. This skill writes pending proposals only; it does not accept its own.

Configuration

bridge-config.yaml.learning.capability_broker (default-on, like feature-discovery — works before the block exists):

learning:
  capability_broker:
    enabled: true                  # false = never offer
    research: { max_sources: 4, default_paid: true }
    recurrence_escalate_after: 2   # one-off seen N+ times → persist proposal
    decline_cooldown_sessions: 1

What this skill deliberately does NOT do

• ❌ Install, wire, authenticate, or send anything outward without a per-action [y]. The offer is the only un-gated step.
• ❌ Edit any other Bridge file directly — capability lands via skill-creator (skills) or the provisioning route (tools), and is reviewed via /bridge-learn.
• ❌ Re-implement skill scaffolding (that's skill-creator), deep research (that's deep-research), or feature suggestions for features that already exist (that's feature-discovery).
• ❌ Offer when a skill already covers the need (false gap → load it).
• ❌ Accept its own proposals or auto-promote to upstreams.

Related

• rules/learning-autonomy.md — the gate doctrine this skill is bound by
• protocols/standing-orders/capability-gap-offer.md — the always-on detector
• protocols/standing-orders/feature-discovery.md — complementary (existing-feature) surface
• skills/task-close-postmortem/, skills/bridge-audit/, skills/bridge-curator/ — the retrospective proposal generators
• skills/bridge-learn/ — the review surface that closes the loop
• work/_learning/README.md — the aggregation layer this writes into
• work/_learning/capability-gaps.md — the recurrence ledger
• skill-creator (plugin), deep-research, checkup — the executors