recoupable__skills/docs/capability-plugins.md

Pattern: the capability (department / team) plugin

Build-time reference for plugin authors. This doc is not shipped with any install and a SKILL.md must never link to it — embody the guidance as behavior instead.

This is the default plugin shape, and the companion to the workflow-bundle pattern (see workflow-plugins.md). A capability plugin is a cluster of related skills owned by one team or department, each skill independently useful, with no mandatory order and no single shared artifact.

Think "a toolbox a team reaches into" — not "a pipeline you run start-to-finish." The user picks the one skill that answers their question right now.

---

When to use this pattern (and when not to)

Use a capability plugin when all of these hold:

• The skills serve one audience / team (the install unit is "the marketing team," "the A&R team," "operations").
• Each skill is independently valuable — a user reaches for one without needing the others.
• There is no required sequence and no shared workspace the skills jointly build up.
• New skills get added over time as the team's needs grow.

Prefer a workflow-bundle plugin instead when the skills are stages of one named, recurring process that accumulates into a single artifact (a release, a deal, a tour). When in doubt: "Would a user run these in a fixed order to produce one deliverable?" — yes → workflow bundle; no → capability plugin.

A repo will typically have several capability plugins (one per team) plus, optionally, one or more workflow bundles alongside them.

---

The organizing principle: audience, not topic or mechanism

Pick the plugin boundary by who installs and owns it — the team/department — not by:

• Topic (don't make a "playlists" plugin — playlists show up in research, marketing, and ops).
• Mechanism (don't make an "automations" or "reports" plugin — "it runs on a schedule" is not a team).
• Lifecycle stage (that's the workflow-bundle's job).

Litmus test: "Whose toolbox is this?" If the answer is a team ("the marketing team," "A&R"), it's a capability plugin and the team name is the plugin name. If the answer is "everyone," it's the general/essentials plugin. If the answer is "whoever's running process X," it's a workflow bundle.

The one allowed exception is a general plugin (e.g. *-essentials) for the handful of skills every team needs (house voice, shared standards). Keep that bar high — team-specific skills do not belong there.

---

Anatomy

Ingredient	Required?	Notes
A set of focused skills	✅	One job per skill; each independently useful
A router / entry-point skill	✅ (strongly)	One skill that resolves a fuzzy request and points to the right focused skill
Clear, modality-aware names	✅	The name says what it does and how (see "Naming" below)
Cross-routes between overlapping skills	✅	Every pair on the same topic must say "use me for X, use the other for Y"
Per-skill references / scripts	optional	Co-located and self-contained; shared files are vendored
A plugin README	✅	A skills table + "which one do I use?" guidance for the team

Unlike a workflow bundle, a capability plugin has no shared workspace contract, no mandatory orchestrator that runs everything end-to-end, and no single "open this first" artifact. Each skill stands alone.

---

The router skill (the one piece people skip and shouldn't)

A capability plugin can sprawl into a dozen skills a user can't tell apart. The fix is a router: one entry-point skill whose job is to resolve "I want to do something in this area" into the right focused skill.

A good router:

• Asks only the question(s) that change which skill applies.
• Names the focused skills and what each is for.
• Hands off — it routes, it doesn't try to do every job itself.
• Says so plainly when no skill fits yet (rather than faking one).

This is the capability-plugin equivalent of the workflow bundle's orchestrator — but it routes to independent skills rather than driving a fixed pipeline.

---

Disambiguation is the whole game (avoiding overlap confusion)

Because capability plugins group by team, the same topic often appears on multiple skills, and the same topic can appear across multiple plugins. The risk: a user asks "help with playlists" and three skills plausibly match. Two tools prevent this:

1. Scope tokens — what the skill operates on

Mark the object in the name with the narrowest true scope:

• *-artist-* — one artist
• *-song-* — one song/track
• *-catalog-* — a catalog of releases
• *-account-* — an account/brand/label
• (no token) — capability-general

The same capability can exist at multiple scopes (artist vs. song vs. catalog analysis) — the token is what tells them apart.

2. Modality — how the skill works

Three modalities recur, and the name should signal which:

Modality	What it is	Tell-tale suffixes
Playbook	A "how to plan/think" guide; no live data	-planner, -campaign, -growth
Research (on-demand)	Ask now, pull live data, answer	-research, -analysis, -intelligence, -brief
Monitor (scheduled)	Runs on a cadence, saves an artifact, alerts	-monitor, -watch, -check, -tracker, -report, -dashboard, -digest

The same topic frequently has both an on-demand and a scheduled twin (analyze-now vs. watch-weekly). When it does, the two must cross-route and each must state its modality in the first sentence of its description ("Ask now…" vs. "Runs weekly and emails…"). That pairing is the cleanest way to make a B/C duplicate read as intentional rather than redundant.

A capability plugin may legitimately hold both an on-demand analysis and its scheduled-monitor twin. Just make it intentional and documented — not accidental.

---

Naming rules (recap)

• kebab-case, lowercase, prefixed with the brand.
• Name for the capability, not the team and not a helper verb. (The plugin carries the team name; the skill carries the capability.)
• The skim test: from the name alone, would a user know what it does?
• Scope token + modality suffix together make the name self-explaining ({brand}-artist-competitor-watch = a scheduled monitor of one artist's competitors).

---

Build blueprint

1. Name the team — that's the plugin ({brand}-{team}).
2. Inventory the skills that team owns. For each, confirm it's independently useful (if it's meaningless outside a single process, it belongs in a workflow bundle instead).
3. Add a router skill as the entry point.
4. Name each skill with a scope token + modality suffix; run the skim test.
5. Cross-route every same-topic pair (and any topic that also lives in another plugin).
6. Write the README with a skills table and a short "which one do I use?" map.
7. Keep each skill self-contained; vendor any shared reference/script.

---

Quality bar

• A user can scan the skills table and know which one to pick without reading bodies.
• No two skills are ambiguous for the same request; where topics overlap, the descriptions cross-route.
• The router resolves "I want to do something in this area" to a single skill.
• Nothing team-specific has leaked into the general/essentials plugin.
• Every skill earns its place by doing real work, not restating another skill.

If skills in the plugin can only be used in a fixed order to build one deliverable, you don't have a capability plugin — you have a workflow bundle. Use that pattern instead (workflow-bundle-plugins.md).