svg153 · Sep 5, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -10,7 +10,7 @@
       "name": "github-build-or-reuse",
       "source": "./",
       "description": "Search GitHub before you build, vet open-source alternatives, then decide USE, CONTRIBUTE, FORK, or BUILD.",
-      "version": "1.2.1"
+      "version": "1.2.2"
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "github-build-or-reuse",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Search GitHub before you build, vet open-source alternatives, then decide USE, CONTRIBUTE, FORK, or BUILD.",
   "author": {
     "name": "GitHub Community Spain",
@@ -14,6 +14,7 @@
     "open-source",
     "open-source-alternatives",
     "agent-skills",
+    "agent-plugins",
     "github-copilot",
     "codex",
     "claude-code",

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "github-build-or-reuse",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Search GitHub before you build, vet open-source alternatives, then decide USE, CONTRIBUTE, FORK, or BUILD.",
   "author": {
     "name": "GitHub Community Spain",
@@ -14,6 +14,7 @@
     "open-source",
     "open-source-alternatives",
     "agent-skills",
+    "agent-plugins",
     "github-copilot",
     "codex",
     "claude-code",

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -26,6 +26,9 @@ jobs:
       - name: Validate repository packaging
         run: python scripts/validate.py
 
+      - name: Validate Agent Plugin and skills.sh coexistence
+        run: python scripts/validate-agent-plugin.py
+
       - name: Validate generated cross-agent manifests
         run: python scripts/generate-distribution.py --check
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -5,15 +5,26 @@ This repository publishes one portable Agent Skill and platform packaging around
 ## Source of truth
 
 - Canonical runtime skill: `skills/github-build-or-reuse/`
-- OpenAI plugin manifest: `.codex-plugin/plugin.json`
-- Repo marketplace: `.agents/plugins/marketplace.json`
+- Portable Agent Plugins v1 manifest: `plugin.json`
+- skills.sh grouping metadata: `skills.sh.json`
+- Generated host adapters: `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/`, `.agents/plugins/`, `marketplace.json`, `gemini-extension.json`
 - Project docs: `docs/`
 - README demo evidence: `assets/demo.json`
 - Demo generator: `scripts/generate_demo.py`
+- Distribution generator: `scripts/generate-distribution.py`
 - Repository validation: `scripts/validate.py`
+- Agent Plugin / skills.sh contract validation: `scripts/validate-agent-plugin.py`
 
 Do not recreate a second root `SKILL.md` or duplicate the canonical skill into platform-specific directories.
 
+## Distribution invariants
+
+- Agent Plugins adoption complements Agent Skills and skills.sh; it does not replace them.
+- Preserve repository `ghspain/github-build-or-reuse`, skill name `github-build-or-reuse`, and path `skills/github-build-or-reuse/SKILL.md` unless a deliberate migration is explicitly planned.
+- `skills.sh.json` and Agent Plugins fixed discovery from `skills/*/SKILL.md` must expose the same canonical skill set.
+- Keep `plugin.json` portable: Agent Plugins v1 fields only. Host-specific metadata belongs in generated adapters/extensions, not invented top-level fields.
+- Do not claim runtime compatibility merely because a host manifest can be generated. Classify evidence as manifest-only, install/discovery verified, or runtime verified.
+
 ## Principles
 
 - Keep `SKILL.md` concise and imperative; put detailed evidence recipes and edge cases in local references/examples.
@@ -33,7 +44,9 @@ Run:
 
 ```bash
 python scripts/validate.py
+python scripts/validate-agent-plugin.py
+python scripts/generate-distribution.py --check
 python scripts/generate_demo.py --check
 ```
 
-CI additionally validates the canonical directory against the Agent Skills reference validator and checks that generated demo assets match their evidence source.
+CI additionally validates the canonical directory against the Agent Skills reference validator, verifies `npx skills` discovery, and checks that generated distribution/demo assets match their canonical sources.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,26 @@ All notable changes to this project will be documented here.
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-09-04
+
+### Added
+
+- Agent Plugins 1.0 / skills.sh coexistence validator that requires both distribution surfaces to expose the same canonical `github-build-or-reuse` skill.
+- ADR documenting Agent Plugins as a packaging layer over the existing Agent Skill rather than a migration away from Agent Skills or skills.sh.
+- Compatibility evidence matrix separating conformance/manifest compatibility, install/discovery verification and runtime verification.
+- `agent-plugins` discovery metadata across generated packaging surfaces.
+
+### Changed
+
+- CI now validates the portable Agent Plugin contract alongside the existing Agent Skills reference validation and `npx skills` discovery smoke test.
+- Repository guidance now treats the repository name, skill identity and `skills/github-build-or-reuse/SKILL.md` path as distribution invariants unless a deliberate migration is planned.
+- Standards documentation makes the no-custom-MCP decision explicit until a real capability gap is demonstrated.
+
+### Compatibility
+
+- The runtime decision model is unchanged from 1.2.1.
+- Existing skills.sh / `npx skills` discovery remains supported with the same repository, skill name, canonical path and `skills.sh.json` registration.
+
 ## [1.2.1] - 2026-09-03
 
 ### Added

diff --git a/README.md b/README.md
@@ -4,12 +4,13 @@
 
 **Don't reinvent the wheel with AI-generated code. Search GitHub first, vet the best open-source options, then decide whether to USE, CONTRIBUTE, FORK, or BUILD.**
 
-`github-build-or-reuse` is a portable **Agent Skill for GitHub Copilot, Codex, Claude Code, Cursor and other Agent Skills-compatible coding agents**. It turns “has somebody already built this?” into a repeatable engineering gate before substantial implementation.
+`github-build-or-reuse` is a portable **Agent Skill and Agent Plugins 1.0 package for GitHub Copilot, Codex, Claude Code, Cursor and other compatible coding agents**. It turns “has somebody already built this?” into a repeatable engineering gate before substantial implementation.
 
 [![Validate](https://github.com/ghspain/github-build-or-reuse/actions/workflows/validate.yml/badge.svg)](https://github.com/ghspain/github-build-or-reuse/actions/workflows/validate.yml)
 [![Release](https://img.shields.io/github/v/release/ghspain/github-build-or-reuse)](https://github.com/ghspain/github-build-or-reuse/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Agent Skill](https://img.shields.io/badge/Agent%20Skill-portable-1f6feb)](skills/github-build-or-reuse/SKILL.md)
+[![Agent Plugins 1.0](https://img.shields.io/badge/Agent%20Plugins-1.0-8250df)](plugin.json)
 [![skills.sh](https://skills.sh/b/ghspain/github-build-or-reuse)](https://skills.sh/ghspain/github-build-or-reuse/github-build-or-reuse)
 
 ## In 20 seconds
@@ -41,7 +42,9 @@ The `Render README demo` workflow reuses the official [`asciinema/agg`](https://
 
 ## Install
 
-### `npx skills` — easiest cross-agent path
+### `npx skills` / skills.sh — easiest cross-agent path
+
+This remains a first-class supported installation path. Agent Plugins adoption does **not** replace or relocate the canonical skill used by skills.sh.
 
 ```bash
 # Inspect before installing
@@ -54,6 +57,21 @@ npx skills@latest add ghspain/github-build-or-reuse --skill github-build-or-reus
 npx skills@latest add ghspain/github-build-or-reuse --skill github-build-or-reuse --agent codex --global
 ```
 
+### Agent Plugins 1.0
+
+The repository root is also a portable Agent Plugins 1.0 package:
+
+```text
+plugin.json
+skills/
+└── github-build-or-reuse/
+    └── SKILL.md
+```
+
+Agent Plugins discovers the **same** canonical skill from the fixed `skills/` directory that skills.sh uses. CI verifies that Agent Plugins discovery and `skills.sh.json` expose the same skill, so adding plugin packaging cannot silently drop the existing skills.sh path.
+
+Use the Agent Plugin installation mechanism supported by your client. Host-specific compatibility surfaces below are generated from the same canonical distribution state; they are not copies of the skill.
+
 ### GitHub CLI / GitHub Copilot
 
 GitHub CLI **2.90.0+** can preview, install and update Agent Skills directly from GitHub repositories:
@@ -63,15 +81,15 @@ gh skill preview ghspain/github-build-or-reuse github-build-or-reuse
 gh skill install ghspain/github-build-or-reuse github-build-or-reuse
 
 # Reproducible release
-gh skill install ghspain/github-build-or-reuse github-build-or-reuse@v1.2.0
+gh skill install ghspain/github-build-or-reuse github-build-or-reuse@v1.2.2
 ```
 
 For long-lived environments, prefer a release tag or `--pin` so upstream changes cannot silently alter behavior.
 
 ### ChatGPT / Codex plugin
 
 ```bash
-codex plugin marketplace add ghspain/github-build-or-reuse --ref v1.2.0
+codex plugin marketplace add ghspain/github-build-or-reuse --ref v1.2.2
 ```
 
 Then open `/plugins`, choose the **GitHub Community Spain** marketplace and install **GitHub Build or Reuse**.
@@ -89,6 +107,8 @@ Copy or install that directory into the skills location supported by your client
 
 </details>
 
+See [`docs/agent-plugin-compatibility.md`](docs/agent-plugin-compatibility.md) for the distribution invariants and evidence-based compatibility matrix.
+
 ## Why search before you build?
 
 AI coding agents made greenfield software dramatically cheaper to *start*. They did not make it free to own.
@@ -203,22 +223,26 @@ The project follows its own rule: **reuse before build**.
 
 The workflow already works with host-provided GitHub connectors/API, existing MCP integrations, authenticated `gh`, or web research. A bespoke GitHub-wrapper MCP would add authentication, maintenance and security surface without a unique capability.
 
+Agent Plugins 1.0 supports optional MCP packaging, but format support alone is not a reason to add a server.
+
 ### Tool degradation must be visible
 
 The skill prefers structured GitHub evidence, but it does not pretend unavailable checks succeeded. Missing evidence is reported explicitly; candidate repository content is treated as untrusted input.
 
 ## Standards and compatibility
 
-The canonical skill follows the open **Agent Skills** specification. The repository also follows OpenAI plugin packaging conventions (`.codex-plugin/plugin.json` + `skills/`). `AGENTS.md` remains maintainer guidance rather than runtime skill content.
+The canonical skill follows the open **Agent Skills** specification. The repository root also follows **Agent Plugins 1.0** (`plugin.json` + `skills/`) while preserving `skills.sh.json` and the existing skills.sh discovery path. Host-specific Codex, Claude Code, Cursor and Gemini manifests remain generated compatibility adapters. `AGENTS.md` remains maintainer guidance rather than runtime skill content.
 
-See [`docs/standards-and-roadmap.md`](docs/standards-and-roadmap.md) for the design rationale around Agent Skills, plugins, AGENTS.md, OpenAI Agents SDK definitions and MCP.
+See [`docs/standards-and-roadmap.md`](docs/standards-and-roadmap.md) and [`docs/agent-plugin-compatibility.md`](docs/agent-plugin-compatibility.md) for the design rationale, compatibility evidence and MCP decision.
 
 ## Quality and evals
 
-The skill ships with output evals and trigger queries under [`skills/github-build-or-reuse/evals/`](skills/github-build-or-reuse/evals/). CI validates repository packaging, generated demo consistency, the Agent Skills reference specification, GitHub CLI publishing when available, and discovery by `npx skills`.
+The skill ships with output evals and trigger queries under [`skills/github-build-or-reuse/evals/`](skills/github-build-or-reuse/evals/). CI validates repository packaging, Agent Plugins/skills.sh coexistence, generated demo consistency, the Agent Skills reference specification, GitHub CLI publishing when available, and discovery by `npx skills`.
 
 ```bash
 python scripts/validate.py
+python scripts/validate-agent-plugin.py
+python scripts/generate-distribution.py --check
 python scripts/generate_demo.py --check
 ```
 
@@ -232,16 +256,20 @@ python scripts/generate_demo.py --check
 │   ├── demo.svg        # deterministic static rendering
 │   ├── demo.cast       # deterministic asciinema recording
 │   └── demo.gif        # generated by the render workflow
+├── plugin.json         # portable Agent Plugins 1.0 manifest
+├── skills.sh.json      # skills.sh grouping/discovery metadata
 ├── .agents/plugins/marketplace.json
 ├── .codex-plugin/plugin.json
 ├── .github/workflows/
 │   ├── render-demo.yml
 │   └── validate.yml
 ├── docs/
+│   ├── agent-plugin-compatibility.md
 │   └── demo.md
 ├── scripts/
 │   ├── generate_demo.py
-│   └── validate.py
+│   ├── generate-distribution.py
+│   └── validate-agent-plugin.py
 ├── skills/github-build-or-reuse/
 ├── AGENTS.md
 ├── CHANGELOG.md
@@ -261,7 +289,7 @@ The implementations are independent. Related projects are useful precisely becau
 
 ## Search keywords
 
-Agent Skills · GitHub Copilot skill · Codex skill · Claude Code skill · open-source alternatives · GitHub repository search · software reuse · build vs buy · build vs open source · don't reinvent the wheel · repository due diligence · open-source due diligence · GitHub automation · AI coding agents · software architecture · reuse before build.
+Agent Plugins · Agent Skills · GitHub Copilot skill · Codex skill · Claude Code skill · open-source alternatives · GitHub repository search · software reuse · build vs buy · build vs open source · don't reinvent the wheel · repository due diligence · open-source due diligence · GitHub automation · AI coding agents · software architecture · reuse before build.
 
 ## Contributing
 

diff --git a/distribution.config.json b/distribution.config.json
@@ -18,6 +18,7 @@
     "open-source",
     "open-source-alternatives",
     "agent-skills",
+    "agent-plugins",
     "github-copilot",
     "codex",
     "claude-code",

diff --git a/docs/adr/0001-agent-plugin-and-skills-sh-coexistence.md b/docs/adr/0001-agent-plugin-and-skills-sh-coexistence.md
@@ -0,0 +1,51 @@
+# ADR 0001: Agent Plugins complements Agent Skills and skills.sh
+
+- Status: Accepted
+- Date: 2026-09-04
+- Issue: https://github.com/ghspain/github-build-or-reuse/issues/28
+- Parent initiative: https://github.com/svg153/skills/issues/33
+
+## Context
+
+The repository already publishes a portable Agent Skill and several generated host-specific packaging surfaces. Agent Plugins 1.0 standardizes a portable plugin root with fixed discovery of Agent Skills from `skills/` and optional MCP servers from `mcp.json`.
+
+The project is also already discoverable through the Agent Skills / skills.sh ecosystem. Replacing that layout with a plugin-specific copy would risk breaking existing installation paths and create two runtime sources of truth.
+
+## Decision
+
+1. `skills/github-build-or-reuse/SKILL.md` remains the only canonical runtime skill.
+2. The repository root is also a conforming Agent Plugins 1.0 package through `plugin.json` plus the existing fixed `skills/` directory.
+3. `skills.sh.json` remains a supported distribution surface. Agent Plugin adoption must not rename, move, or duplicate the canonical skill as an incidental packaging change.
+4. CI enforces parity between the skills Agent Plugins discovers from `skills/*/SKILL.md` and the skills registered in `skills.sh.json`.
+5. Host-specific manifests remain generated adapters and cannot override the portable runtime source.
+6. No custom GitHub-wrapper MCP is bundled unless a future evidence-backed capability gap requires one. Existing native connectors, GitHub MCP integrations, `gh`, GitHub APIs, and web research are preferred.
+7. Compatibility documentation must distinguish schema/manifest compatibility, install/discovery verification, and actual runtime verification.
+
+## Consequences
+
+### Positive
+
+- Existing skills.sh and Agent Skills users retain the same repository, skill name, and canonical path.
+- Agent Plugins-compatible clients can consume the repository without a second copy of the skill.
+- Distribution drift becomes testable rather than a documentation convention.
+- Future host adapters can be removed as clients converge on Agent Plugins without rewriting runtime behavior.
+
+### Trade-offs
+
+- External skills.sh indexing availability cannot be guaranteed by repository CI; only the stable repository inputs and local discovery path can be guaranteed.
+- Some client-specific adapters remain necessary until those clients consume the portable package directly.
+- Runtime compatibility still has to be tested per client; a valid manifest alone is not proof of equivalent execution.
+
+## Rejected alternatives
+
+### Move the skill into a plugin-only directory
+
+Rejected because Agent Plugins already discovers the existing `skills/` layout and moving it would risk breaking skills.sh and Agent Skills consumers for no capability gain.
+
+### Duplicate `SKILL.md` for every platform
+
+Rejected because copies drift and make provenance, releases, fixes, and behavioral eval ownership ambiguous.
+
+### Bundle a custom GitHub MCP immediately
+
+Rejected because the project already has multiple ways to collect GitHub evidence and a wrapper would contradict the reuse-before-build principle without a demonstrated missing capability.