[svg153]

Summary

Makes Agent Plugins 1.0 a first-class additive distribution surface while preserving the existing Agent Skills / skills.sh contract.

The central invariant is unchanged:

skills/github-build-or-reuse/SKILL.md

is the single canonical runtime skill for both Agent Plugins discovery and skills.sh consumers.

What changes

• adds an ADR for Agent Plugins + skills.sh coexistence;
• adds scripts/validate-agent-plugin.py;
• requires Agent Plugins-discovered skills to exactly match skills.sh.json registrations;
• keeps the existing npx skills@latest add . --list CI smoke test;
• documents compatibility evidence levels instead of claiming manifest compatibility means runtime parity;
• keeps the no bespoke GitHub MCP implementation decision for this capability unless a real capability gap is demonstrated;
• clarifies that Agent Plugins can still compose existing third-party MCP servers through mcp.json — “no custom MCP” does not mean “no MCP composition”;
• updates README installation guidance so Agent Plugins is explicitly additive, not a replacement for skills.sh during this pilot;
• prepares packaging release v1.2.2 and regenerates affected manifests.

MCP clarification

Agent Plugins 1.0 discovers MCP configuration from root mcp.json. That file can configure an existing remote MCP (streamable-http) or existing executable (stdio); the MCP server does not need to be implemented inside this repository.

For GitHub Build or Reuse, the current design remains no mandatory mcp.json because the skill intentionally works with host-native GitHub APIs/connectors, the official GitHub MCP Server, authenticated gh, or web fallback. Making one of those optional access paths mandatory would reduce portability without adding capability.

Reusable MCP composition is being generalized separately in:

• svg153/skills#35 — catalog support for optional mcp.json;
• svg153/skills#36 — planning plugin pilot using existing GitHub + Jira/Atlassian MCP servers.

skills.sh regression guard

This PR intentionally preserves all stable inputs used by the existing skills.sh path:

• repository: ghspain/github-build-or-reuse;
• skill name: github-build-or-reuse;
• path: skills/github-build-or-reuse/SKILL.md;
• skills.sh.json registration.

CI now fails if the Agent Plugins skill set diverges from skills.sh.json, and continues to verify local discovery through npx skills.

External skills.sh ranking/index availability is not under repository control, so it remains observed rather than becoming a brittle PR-blocking dependency.

The longer-term question of making Agent Plugins primary and retiring adapters is tracked in svg153/skills#34; skills.sh should be retired only if equivalent discovery/install reach is demonstrated.

Validation

Expected PR checks cover:

python scripts/validate.py
python scripts/validate-agent-plugin.py
python scripts/generate-distribution.py --check
python scripts/generate_demo.py --check
npx -y skills@latest add . --list

Traceability

Refs #28
Parent initiative: svg153/skills#33
Follow-ups: svg153/skills#34, svg153/skills#35, svg153/skills#36
Origin: review of “Build Once, Run Everywhere: Agent Plugins Guide” and Agent Plugins 1.0.

Runtime verification on additional concrete agent hosts remains tracked in #28; this PR deliberately does not overstate unverified host compatibility.