feat: publish generated plugin distributions

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,10 +14,10 @@ What changed and why?
 
 Describe native harness checks performed and explicitly list checks not run. Include screenshots or before/after behavior where useful; omit credentials and account data.
 
-- [ ] Portable root manifest and MCP config validate against the published Agent Plugins schemas
-- [ ] Package paths and skill references remain inside the repository/plugin root
+- [ ] Generated portable manifest and MCP config validate against the vendored Agent Plugins schemas
+- [ ] Package paths and skill references remain inside each generated plugin root
 - [ ] Marketplace, skills, MCP, and icon paths are valid
-- [ ] Exactly one canonical skill library; no per-harness copies
+- [ ] Exactly one canonical skill library; generated copies are not committed
 - [ ] Claude compatibility metadata/endpoint and marketplace sources agree with the portable package
 - [ ] Tool schemas, authorization, and retry behavior reviewed
 - [ ] README and changelog updated; versions consistent

.github/workflows/check-distributions.yml

@@ -0,0 +1,39 @@
+name: Check plugin distributions
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Build plugin distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+
+      - name: Validate portable schemas
+        run: |
+          uvx --from 'check-jsonschema==0.34.1' check-jsonschema \
+            --schemafile schemas/1.0.0/plugin.schema.json \
+            src/plugins/portable/plugin.json
+          uvx --from 'check-jsonschema==0.34.1' check-jsonschema \
+            --schemafile schemas/1.0.0/mcp.schema.json \
+            src/plugins/portable/mcp.json
+
+      - name: Check distribution builder
+        run: |
+          uvx ruff@0.13.2 check scripts/build-distributions.py
+          uvx ruff@0.13.2 format --check scripts/build-distributions.py
+
+      - name: Build plugin distributions
+        run: python3 scripts/build-distributions.py dist
+
+      - name: Verify checksums
+        working-directory: dist/site/downloads
+        run: sha256sum --check SHA256SUMS

.github/workflows/publish-distributions.yml

@@ -0,0 +1,74 @@
+name: Publish plugin distributions
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-deploy
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build plugin distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+
+      - name: Validate portable schemas
+        run: |
+          uvx --from 'check-jsonschema==0.34.1' check-jsonschema \
+            --schemafile schemas/1.0.0/plugin.schema.json \
+            src/plugins/portable/plugin.json
+          uvx --from 'check-jsonschema==0.34.1' check-jsonschema \
+            --schemafile schemas/1.0.0/mcp.schema.json \
+            src/plugins/portable/mcp.json
+
+      - name: Build plugin distributions
+        run: python3 scripts/build-distributions.py dist
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08
+        with:
+          name: site
+          path: dist/site
+          include-hidden-files: true
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: site
+          path: site
+
+      - name: Configure Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e

.gitignore

@@ -12,3 +12,5 @@ tokens.json
 .cursor/
 .hermes/
 .pi/
+__pycache__/
+dist/

CHANGELOG.md

@@ -1,3 +1,8 @@
 # Changelog
 
 ## 0.0.1 — Unreleased
+
+- Treat this repository as canonical source instead of an installable plugin root.
+- Generate portable, Claude, and Codex distributions from one skill library.
+- Isolate OpenAI assets under the portable `com.openai` extension directory.
+- Publish versioned archives, checksums, unpacked packages, and release metadata through GitHub Pages.

CONTRIBUTING.md

@@ -4,19 +4,19 @@
 
 1. Fork or create a feature branch. Use a conventional PR title, such as `feat(cursor): update plugin metadata`.
 2. Edit shared workflows in root `skills/` first. Keep `SKILL.md` capability-oriented; put execution details in `references/cli.md` and `references/mcp.md`. Load only the selected interface reference. Watch remains CLI-only; its MCP reference explains the limitation rather than inventing a tool.
-3. Keep one repository-root plugin and one `skills/` tree. Root `plugin.json` and `mcp.json` target the published Agent Plugins 1.0.0 schemas. Use documented client extensions for metadata; do not add portable component-path overrides, credentials, or per-harness skill copies. Keep all package paths inside the repository root.
-4. Maintain the thin `.claude-plugin/plugin.json` compatibility layer: it discovers the same root skills and declares the same remote endpoint using Claude's native HTTP type. Keep common metadata, package versions, and root marketplace sources consistent. Do not add a root `.mcp.json` or competing native Cursor/Codex manifest. Validate native loading where available (for example, `claude plugin validate . --strict`), and verify OAuth with a portfolio read, never a financial write. Record checks not run.
+3. Keep one `skills/` source tree. Portable source manifests live under `src/plugins/portable/` and target the published Agent Plugins 1.0.0 schemas. Use documented client extensions for metadata; do not add portable component-path overrides, credentials, or hand-maintained skill copies.
+4. Maintain native source metadata under `src/plugins/`. Keep common metadata, package versions, and endpoint configuration consistent. Run `python3 scripts/build-distributions.py dist` and inspect the generated packages rather than treating the repository root as a plugin. Validate native loading where available, and verify OAuth with a portfolio read, never a financial write. Record checks not run.
 5. Use [signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits), update the README/changelog, and open a PR using the template. Obtain review before merging.
 
-Before release, validate `plugin.json` and `mcp.json` with the [official versioned JSON Schemas](https://github.com/agentplugins/agent-plugins-spec/tree/main/schemas/1.0.0), then check semantic rules not expressed by the schemas: HTTPS URL/no credentials, fixed discovery locations, filesystem containment, and skill frontmatter. Verify exactly nine skills and their CLI/MCP references, all local links, asset paths, marketplace sources (`./`), and Claude endpoint/metadata parity. Recheck tool names against current MCP contracts and CLI patterns against installed help/templates. Run checks with temporary tooling if needed; no checked-in exporter, validator, tests directory, or CI framework is required.
+Before release, run `python3 scripts/build-distributions.py dist`. It validates portable identity, schema identifiers, the exact MCP endpoint, extension assets, filesystem containment, skill frontmatter, local links, native metadata, and version parity before creating archives and checksums. CI validates the source manifests against the vendored official schemas. Inspect each generated layout and recheck tool names against current MCP contracts and CLI patterns against installed help/templates.
 
 Review these cases explicitly: MCP-only setup never asks for CLI credentials; CLI-only setup does not assume OAuth; both available honors user choice and verifies scope; unsupported client/capability stops or asks before switching; watch is not a remote subscription; unknown order/payment outcomes never switch interfaces or generate fresh retry IDs. Confirm product/session limitations, exact approvals, preview failures, pagination, and state verification. Static checks are not authenticated smoke tests.
 
 ## Source material
 
 The skills are maintained Coinbase CLI and MCP guidance, not an automatic upstream sync. Preserve source attribution and have maintainers confirm licensing and required notices for contributed material.
 
-Shared guidance and interface references are based on the [published Coinbase guide](https://docs.cdp.coinbase.com/coinbase-for-agents/skill.md), current tool contracts, and CLI help/source. Review against the latest schemas and client support before release. All harnesses use the same root library, with `coinbase` as the entry point. No external reference repository's code, telemetry, or runtime is bundled.
+Shared guidance and interface references are based on the [published Coinbase guide](https://docs.cdp.coinbase.com/coinbase-for-agents/skill.md), current tool contracts, and CLI help/source. Review against the latest schemas and client support before release. All generated distributions use the same source library, with `coinbase` as the entry point. The vendored Agent Plugins schemas retain their upstream Apache 2.0 license; no external telemetry or runtime is bundled.
 
 The single `assets/coinbase.svg` mark is extracted from the published CDP documentation wordmark; its source URL is recorded in the asset. Confirm branding approval before public marketplace submission. OpenAI icon/presentation fields belong in `extensions.com.openai`; do not invent fields or namespaces for another client or add a top-level portable `logo` field.
 
@@ -25,7 +25,7 @@ The single `assets/coinbase.svg` mark is extracted from the published CDP docume
 - Maintainers must complete the required licensing, branding, security, and release approvals before publication.
 - Review changes for secrets, personal data, private infrastructure references, and unsupported compatibility claims.
 - Protect release branches with required reviews, signed commits, and applicable status checks.
-- If Actions are added later, pin them to full commit SHAs. Do not use repository or organization secrets; use restricted Environment secrets only when necessary.
+- Keep Actions pinned to full commit SHAs. Do not use repository or organization secrets; use restricted Environment secrets only when necessary.
 - Test every advertised harness with its approved OAuth client, update versions and changelog, and obtain explicit authorization before changing visibility or submitting marketplace listings. Access approval is not launch approval.
 
 Do not include private review records or approval evidence in public source files.

README.md

@@ -28,13 +28,23 @@ For agents with shell access, the optional [`@coinbase/coinbase-cli`](https://ww
 | [x402](skills/coinbase-x402/SKILL.md) | Discover and purchase research within an approved budget |
 | [Watch](skills/coinbase-watch/SKILL.md) | Bounded streaming and monitoring; CLI only |
 
-### Install locally
+## Plugin distributions
+
+This repository is the canonical source for three generated distributions:
+
+- `coinbase-agent-plugin-vX.Y.Z`: portable [Agent Plugins v1.0.0](https://agent-plugins.org/) package for Cursor, Hermes, and other compatible clients.
+- `coinbase-claude-vX.Y.Z`: Claude Code native package.
+- `coinbase-codex-vX.Y.Z`: Codex marketplace containing the portable package.
 
-The repository root is one [Agent Plugins v1.0.0](https://agent-plugins.org/) package, with a Claude Code compatibility manifest. Use the whole package, including tracked dot-directories, but exclude `.git` and local credentials. Plugin-format support does not imply Coinbase OAuth client approval; do not bypass rejected authentication.
+Download versioned ZIP or tar archives from [Coinbase Agent Plugin downloads](https://coinbase.github.io/agents/), verify them against `SHA256SUMS`, and extract the package for your client. Plugin-format support does not imply Coinbase OAuth client approval; do not bypass rejected authentication.
+
+For local development, run `python3 scripts/build-distributions.py dist` and use the generated directories under `dist/site/packages/`. The repository root is not an installable plugin.
+
+### Install locally
 
 #### Claude Code
 
-From the repository root:
+From the extracted `coinbase-claude-vX.Y.Z` directory:
 
 ```sh
 claude --plugin-dir "$PWD"
@@ -44,7 +54,7 @@ Open `/mcp` to authenticate, then load `/coinbase:coinbase`. See [Claude Code's
 
 #### Codex
 
-From the repository root:
+From the extracted `coinbase-codex-vX.Y.Z` directory:
 
 ```sh
 codex plugin marketplace add "$PWD"
@@ -54,11 +64,11 @@ Install and enable `coinbase` from `coinbase-agents` in the supported plugin UI.
 
 #### Cursor
 
-Copy the package into a new `~/.cursor/plugins/local/coinbase/` directory, then reload **Customize**. Local imports require administrator permission. See [Cursor's plugin documentation](https://cursor.com/docs/reference/plugins).
+Extract `coinbase-agent-plugin-vX.Y.Z` into a new `~/.cursor/plugins/local/coinbase/` directory, with `plugin.json` directly inside it, then reload **Customize**. Local imports require administrator permission. See [Cursor's plugin documentation](https://cursor.com/docs/reference/plugins).
 
 #### Hermes
 
-Copy the package into a new `~/.hermes/plugins/coinbase/` directory, or your active profile's plugin directory, then run:
+Extract `coinbase-agent-plugin-vX.Y.Z` into a new `~/.hermes/plugins/coinbase/` directory, or your active profile's plugin directory, then run:
 
 ```sh
 hermes plugins list

schemas/1.0.0/mcp.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "title": "Agent Plugins MCP Configuration",
+  "description": "Machine-readable schema for mcp.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+      "description": "Canonical identifier of the MCP configuration schema for the Agent Plugins version targeted by this document."
+    },
+    "mcpServers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/server"
+      }
+    }
+  },
+  "required": ["$schema", "mcpServers"],
+  "additionalProperties": false,
+  "$defs": {
+    "server": {
+      "title": "MCP server",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/stdioServer"
+        },
+        {
+          "$ref": "#/$defs/streamableHttpServer"
+        },
+        {
+          "$ref": "#/$defs/sseServer"
+        }
+      ]
+    },
+    "stdioServer": {
+      "title": "stdio MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "stdio"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Executable token. Resolution rules are defined by the Agent Plugins specification."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["PLUGIN_ROOT", "PLUGIN_DATA"]
+            }
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\./|\\$\\{PLUGIN_ROOT\\}(?:/|$)|\\$\\{PLUGIN_DATA\\}(?:/|$))",
+          "description": "Plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted working directory. Filesystem containment is validated separately."
+        }
+      },
+      "required": ["type", "command"],
+      "additionalProperties": false
+    },
+    "streamableHttpServer": {
+      "title": "Streamable HTTP MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "streamable-http"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "sseServer": {
+      "title": "Legacy HTTP+SSE MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "sse"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "headers": {
+      "title": "HTTP headers",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}