architecture: define plugin-first distribution and retirement criteria for legacy adapters #34

Parent: #33

Goal

Define when Agent Plugins 1.0 becomes the primary package/distribution contract and which existing compatibility surfaces can eventually be retired without losing users, discovery, or runtime capabilities.

This is not about removing Agent Skills: an Agent Plugin uses skills/*/SKILL.md as a standard component, so the portable skill remains part of the plugin package. The question is which parallel distribution adapters remain necessary.

Decision to make

Target model:

Agent Plugin package                 <- primary installable capability
├── plugin.json
├── skills/*/SKILL.md                <- canonical portable behavior
├── mcp.json                         <- optional reusable MCP composition
└── <client-extension>/              <- only when needed

External discovery / compatibility adapters
├── skills.sh                         <- keep while it adds discovery/install reach
├── Codex adapter                     <- retire when native Agent Plugins path has parity
├── Claude adapter                    <- same
├── Cursor adapter                    <- same
└── Gemini adapter                    <- same

Why

Agent Plugins can reduce duplicated packaging and let a capability carry skills + MCP configuration under one versioned package. However, Agent Plugins 1.0 does not standardize marketplaces/distribution and clients may adopt component types incrementally, so deleting current adapters solely because plugin.json exists would be premature.

Tasks

• Define primary package vs canonical behavior terminology: plugin package may become primary while SKILL.md remains the canonical skill behavior.
• Inventory every current distribution surface and what unique value it provides: discovery, install, updates, runtime, auth, marketplace visibility.
• Define parity gates before retiring any adapter:
  • installation works;
  • skill discovery works;
  • runtime behavior is verified;
  • plugin updates/versioning work;
  • MCP/auth behavior (when relevant) works;
  • equivalent discovery/marketplace reach exists or loss is explicitly accepted.
• Define a specific retirement policy for skills.sh.json rather than treating it like a host manifest.
• Prefer retiring host-specific generated manifests before retiring skills.sh if clients support Agent Plugins natively.
• Add deprecation warnings/generation flags before deleting any surface.
• Record the decision as an ADR and compatibility matrix.

Recommended policy for skills.sh

Keep skills.sh as a discovery/install adapter for now. It should be removable only when Agent Plugin-native discovery/install provides equivalent practical reach or when skills.sh itself consumes Agent Plugins natively.

Removing skills.sh.json today provides little architectural benefit because it is generated/validated metadata, while it would sacrifice an existing discovery channel.

Acceptance criteria

• We can state which artifact is primary without introducing two sources of runtime truth.
• Every legacy adapter has an explicit keep, deprecate, or retire status backed by evidence.
• skills.sh has separate retirement criteria based on discovery/install reach, not merely manifest compatibility.
• No adapter is removed before a tested replacement path exists.

Depends on the github-build-or-reuse pilot: ghspain/github-build-or-reuse#28 / PR ghspain/github-build-or-reuse#29.