Skill marketplace: marketplace.json + plugin packaging for native Claude Code install

[rucka]

Story Statement

As a Claude Code user
I want marketplace.json + plugin packaging for pair's skills
So that /plugin marketplace add foomakers/pair installs the full skill catalog natively, with no CLI step required

Where: .claude-plugin/ at the repo root of foomakers/pair; consumed by Claude Code's native plugin/marketplace mechanism

Epic Context

Parent Epic: Skill marketplace + Quickstart + external KB scaffold #213
Status: Refined
Priority: P0 (Must-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given the foomakers/pair repo with .claude-plugin/marketplace.json present
   When a Claude Code user runs /plugin marketplace add foomakers/pair
   Then pair's skills install as a Claude Code plugin, without needing pair-cli

2. Given the marketplace manifest
   When it is inspected
   Then it lists every currently-shipped skill from packages/knowledge-hub/dataset/.skills/, using the same names/descriptions as the dataset source (no drift between the two)

3. Given a new skill is added to the KB, or an existing one is renamed/removed
   When the next release ships
   Then marketplace.json is updated by hand as part of that release's checklist — it is not auto-generated (decision: hand-maintained, simplicity over automation for a manifest that changes infrequently)

4. Given the CLI-based install path (pair install, org KB, external KB via --source/--url)
   When the marketplace channel is also available
   Then both channels coexist without conflict — a project uses exactly one of the two (D1), never both at once

Business Rules

• Dual channel (D1): marketplace.json in the pair repo for native Claude Code install, CLI remains the agnostic channel for other tools (Cursor, Windsurf, Copilot). Same source of truth: packages/knowledge-hub.
• No named role agents distributed (D23, R9.3) — the marketplace manifest lists skills only; subagents are anonymous context-isolation mechanics, never a distributed "agent" asset.
• Hand-maintained, not generated: the manifest is a release-checklist item, not a build artifact — avoids adding marketplace-manifest generation to the release pipeline for a file that changes only when the skill catalog itself changes.

Edge Cases and Error Handling

• Skill renamed/removed without a marketplace.json update: stale manifest entry points at a skill that no longer exists at that path — caught only by the release checklist, not automatically; flag as a known manual-process risk (see Notes).
• Claude Code plugin format changes upstream: this story's schema is a snapshot of Claude Code's plugin/marketplace format at implementation time — a Spike (see Technical Analysis) verifies the exact current schema before writing the manifest, since it's an external, evolving spec pair doesn't control.

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• .claude-plugin/marketplace.json (and any companion plugin.json) created, matching Claude Code's current plugin/marketplace schema
• Code review completed and approved
• Documentation updated — docs site (marketplace install path, alongside the existing CLI install docs)

Quality Assurance

• Manual test: /plugin marketplace add foomakers/pair actually installs the skills in a real Claude Code session
• Cross-check: every skill listed in the manifest exists in packages/knowledge-hub/dataset/.skills/ with a matching name

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 2 (S)
Confidence Level: Medium
Sizing Justification: hand-maintained manifest (no generation pipeline) keeps this small; uncertainty is entirely in the external Claude Code plugin schema, not in pair's own logic — hence a Spike, not extra story points

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none
Dependent Stories: none — independent of Quickstart (story #278) and the external KB scaffold (story #279); all three are parallel tracks under this epic

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: manual install test via a real Claude Code session (/plugin marketplace add foomakers/pair), followed by invoking at least one installed skill to confirm it actually runs
Test Data Requirements: none — tested directly against the real repo

Notes and Additional Context

Refinement Session Insights: Decision confirmed during refinement — marketplace.json is hand-maintained, not auto-generated from the skill catalog (simplicity over automation for a low-frequency-change manifest); this is a deliberate tradeoff, revisit if manifest drift becomes a recurring real problem.
Documentation Links: Requirements R9.1 · Spec G11 · Decisions D1, D23 · pair-requirements-triage.md G11 section

Technical Analysis

Implementation Approach

Technical Strategy: static, hand-authored .claude-plugin/ directory at the repo root (mirroring the real-world precedent already observed in other Claude Code plugin repos, e.g. mattpocock/skills' own .claude-plugin/plugin.json), listing pair's skills for native marketplace install. No new CLI code, no new build step — purely a repo-root content addition plus a release-checklist entry.
Key Components: .claude-plugin/marketplace.json (marketplace listing), .claude-plugin/plugin.json (plugin manifest, if Claude Code's schema requires both — confirm during the Spike)
Integration Points: none with pair-cli — this channel is entirely independent of the CLI install path (D1)

Technical Requirements

• Manifest content must stay in sync with packages/knowledge-hub/dataset/.skills/ at release time (hand-maintained, per a release-checklist item — not enforced by tooling)
• No named-agent assets in the manifest (D23) — skills only

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Claude Code's plugin/marketplace schema is external and may change	Medium	Medium	Spike verifies the current schema before implementation; re-verify at each major Claude Code release
Hand-maintained manifest drifts from the real skill catalog over time	Low	Medium	Add a release-checklist line item; revisit automation if drift is observed in practice

Spike Requirements

Required Spikes: verify Claude Code's current plugin/marketplace manifest schema (field names, required vs. optional, whether both plugin.json and marketplace.json are needed, or one suffices) directly against Claude Code's own documentation/examples before writing the manifest.
Estimated Spike Effort: 1-2 hours

Task Breakdown

Checklist

• T1 — Spike: confirm Claude Code's current plugin/marketplace manifest schema
• T2 — Author .claude-plugin/marketplace.json (+ plugin.json if required) listing pair's skill catalog
• T3 — Manual install verification + docs site update + release-checklist entry

Dependency Graph

T1 → T2 → T3

AC Coverage

Task	AC1	AC2	AC3	AC4
T1
T2	✓	✓		✓
T3	✓		✓