From 08153669c7f681625b94614930748f1b31749cc4 Mon Sep 17 00:00:00 2001 From: amirbena Date: Thu, 24 Sep 2026 15:16:23 +0300 Subject: [PATCH 1/5] Record live distribution install evidence and add the README install pointer (#521) Co-Authored-By: Claude Sonnet 5 --- README.md | 12 +++++++++--- docs/RELEASE.md | 4 ++-- docs/distribution.md | 27 ++++++++++++++++----------- 3 files changed, 27 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 1104351..3282575 100644 --- a/README.md +++ b/README.md @@ -57,9 +57,15 @@ how the reviewer will be used — packaging both is rarely needed. | GitHub PR review only | `./scripts/packaging/package-skills.sh github` · `./scripts/packaging/package-skills.ps1 github` | `dist/github-pr-review-skill.zip` | | Both entry points | `./scripts/packaging/package-skills.sh all` · `./scripts/packaging/package-skills.ps1 all` | both archives above | -To install from the published distribution repository instead (skills.sh, -Claude Code marketplace), and to see which install paths are verified versus -only documented, see [`docs/distribution.md`](docs/distribution.md). +To install from the published distribution repository instead: + +```bash +npx skills add amirbena/code-review-skills --skill local-code-review +``` + +For the Claude Code marketplace, Codex, Copilot, updates, and which install +paths are verified versus only documented, see +[`docs/distribution.md`](docs/distribution.md). ## Quick start diff --git a/docs/RELEASE.md b/docs/RELEASE.md index e4922bd..16cd77f 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -496,8 +496,8 @@ idempotency/drift checks. `skills//` is never touched by the adapter. 1.0.0 schema by hand (every field is declared; `additionalProperties` is false). No validator runs in CI. - Verified locally: `claude plugin validate` passes on the built root, and - `marketplace add` + `install` succeed. Codex, Cursor and Copilot reading - the root `plugin.json` is documented compatibility only until #511; consumer-facing install steps and the verified/documented + `marketplace add` + `install` succeed. Live installs from the distribution repository are + recorded in #511; consumer-facing install steps and the verified/documented table live in [`distribution.md`](distribution.md). - The `archive`-source behaviour for the release zips is **not yet tested**; the zips carry no `.claude-plugin/`, and nothing depends on that source diff --git a/docs/distribution.md b/docs/distribution.md index 36ce150..66ed107 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -26,7 +26,9 @@ Replace `` with `local-code-review` or `github-pr-review`. | --- | --- | --- | | skills.sh (`skills` CLI) | `npx skills add amirbena/code-review-skills --skill ` | Lists what is available with `--list`. | | Claude Code marketplace | `/plugin marketplace add amirbena/code-review-skills`, then `/plugin install code-review-skills@code-review-skills` | One plugin exposing both Skills. | -| Codex, Cursor, GitHub Copilot | via the root `plugin.json` (Agent Plugins 1.0.0) | See the table below; not yet exercised. | +| Codex | `codex plugin marketplace add amirbena/code-review-skills`, then `codex plugin add code-review-skills@code-review-skills` | Reads the same `.claude-plugin/marketplace.json`. | +| GitHub Copilot CLI | `copilot plugin marketplace add amirbena/code-review-skills`, then `copilot plugin install code-review-skills@code-review-skills` | Direct `copilot plugin install amirbena/code-review-skills` also works but its CLI warns that direct installs are deprecated. | +| Cursor | "Import from Repo" with the distribution repository | Not yet exercised; see the table below. | | GitHub Release zip | download `local-code-review-skill.zip` or `github-pr-review-skill.zip` from the [source repository's releases](https://github.com/amirbena/code-review-skill/releases) and unzip into your runtime's Skill directory | Manual. Not the same as the paths above; see the note below. | A direct release-zip install is **not** equivalent to a skills.sh install: @@ -41,17 +43,20 @@ a real install from the distribution repository, with evidence recorded in means the ecosystem's own documentation says it should work and nothing here has shown that it does. An unexercised path is never to be read as working. -| Ecosystem | State | Evidence | +| Ecosystem | State | Evidence (client, date, observed version) | | --- | --- | --- | -| skills.sh (`skills` CLI): discovery and copy install from the built tree | verified | CI, against a local copy of the built tree: `tests/integration/packaging/test_distribution_consumer_install.py` | -| skills.sh: install from `amirbena/code-review-skills`, `skills update`, listing on skills.sh | documented | pending live evidence in #511 | -| Claude Code marketplace | verified | run locally in #510 (`claude plugin validate`, `marketplace add`, `install`), see [`RELEASE.md`](RELEASE.md); clean-install outcome still to be recorded in #511 | -| Codex Agent Plugin path | documented | pending; the marketplace entry-path (`"./"`) restriction is unresolved | -| Cursor Agent Plugin path ("Import from Repo") | documented | pending | -| GitHub Copilot Agent Plugin path | documented | pending | - -Live evidence for each row records the client version, date, command, and -the version observed. A path that fails or cannot be exercised is recorded +| CI: `skills` CLI discovery and copy install from the built tree | verified | `tests/integration/packaging/test_distribution_consumer_install.py` (#520) | +| skills.sh: `npx skills add amirbena/code-review-skills --skill ` for both Skills | verified | `skills` 1.7.0, macOS, 2026-09-24: both installed, `metadata.version` 1.56.0 | +| skills.sh: `skills update` picking up a newer release | documented | ran `npx skills update -p -y` at 1.56.0 (refreshed both, no newer release exists); a real update needs a subsequent release | +| skills.sh listing | documented | 2026-09-24: per-Skill pages exist under `skills.sh/amirbena/code-review-skills/`, but the directory search does not return the Skills yet (listing depends on install telemetry); re-check after a release | +| Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, fresh config directory: `marketplace add` + `install` gave plugin 1.56.0 with both Skills | +| Codex Agent Plugin path | verified | Codex CLI 0.156.1, macOS, 2026-09-24: `plugin marketplace add` + `plugin add` gave 1.56.0, both Skills present. The `"./"` entry path did not block it, so no separate Codex marketplace entry is needed. Reading only the root `plugin.json`, without the marketplace file, was not exercised | +| GitHub Copilot Agent Plugin path | verified | Copilot CLI 1.0.88, macOS, 2026-09-24: direct install and `marketplace add` + `install` both gave 1.56.0 with two Skills. Not run against a pinned tag | +| Cursor Agent Plugin path ("Import from Repo") | documented | not exercised: needs the Cursor app, which was not available | + +Windows was not exercised for any path. + +Evidence records the client version, date, and the version observed. A path that fails or cannot be exercised is recorded as such. Gemini CLI and any vendor-specific adapter are out of scope here. ## Updates From f8679fa8db431121824f54fcc6fde93524dba7f0 Mon Sep 17 00:00:00 2001 From: amirbena Date: Thu, 24 Sep 2026 15:29:55 +0300 Subject: [PATCH 2/5] Record the live Cursor verification of v1.56.0 (#521) Co-Authored-By: Claude Sonnet 5 --- docs/distribution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/distribution.md b/docs/distribution.md index 66ed107..09ecb14 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -28,7 +28,7 @@ Replace `` with `local-code-review` or `github-pr-review`. | Claude Code marketplace | `/plugin marketplace add amirbena/code-review-skills`, then `/plugin install code-review-skills@code-review-skills` | One plugin exposing both Skills. | | Codex | `codex plugin marketplace add amirbena/code-review-skills`, then `codex plugin add code-review-skills@code-review-skills` | Reads the same `.claude-plugin/marketplace.json`. | | GitHub Copilot CLI | `copilot plugin marketplace add amirbena/code-review-skills`, then `copilot plugin install code-review-skills@code-review-skills` | Direct `copilot plugin install amirbena/code-review-skills` also works but its CLI warns that direct installs are deprecated. | -| Cursor | "Import from Repo" with the distribution repository | Not yet exercised; see the table below. | +| Cursor | install from `amirbena/code-review-skills` in the Cursor app (documented entry point: "Import from Repo") | No Cursor-specific file is needed; see the table below for what was tested. | | GitHub Release zip | download `local-code-review-skill.zip` or `github-pr-review-skill.zip` from the [source repository's releases](https://github.com/amirbena/code-review-skill/releases) and unzip into your runtime's Skill directory | Manual. Not the same as the paths above; see the note below. | A direct release-zip install is **not** equivalent to a skills.sh install: @@ -52,7 +52,7 @@ has shown that it does. An unexercised path is never to be read as working. | Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, fresh config directory: `marketplace add` + `install` gave plugin 1.56.0 with both Skills | | Codex Agent Plugin path | verified | Codex CLI 0.156.1, macOS, 2026-09-24: `plugin marketplace add` + `plugin add` gave 1.56.0, both Skills present. The `"./"` entry path did not block it, so no separate Codex marketplace entry is needed. Reading only the root `plugin.json`, without the marketplace file, was not exercised | | GitHub Copilot Agent Plugin path | verified | Copilot CLI 1.0.88, macOS, 2026-09-24: direct install and `marketplace add` + `install` both gave 1.56.0 with two Skills. Not run against a pinned tag | -| Cursor Agent Plugin path ("Import from Repo") | documented | not exercised: needs the Cursor app, which was not available | +| Cursor Agent Plugin path | verified | Cursor 3.17.8 (installed app version), macOS, 2026-09-24, manual test of v1.56.0: both Skills installed from `amirbena/code-review-skills` and invoked successfully; no Cursor adapter or `.cursor-plugin` was needed. The exact UI steps were not recorded, so "Import from Repo" itself is not claimed as the tested path | Windows was not exercised for any path. From 89883669651cc6996c1cdb3483e987735658da5e Mon Sep 17 00:00:00 2001 From: amirbena Date: Thu, 24 Sep 2026 15:50:25 +0300 Subject: [PATCH 3/5] Record Claude Code and Codex runtime verification of v1.56.0 (#521) Co-Authored-By: Claude Sonnet 5 --- docs/distribution.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/distribution.md b/docs/distribution.md index 09ecb14..f67759b 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -25,7 +25,7 @@ Replace `` with `local-code-review` or `github-pr-review`. | Path | Command | Notes | | --- | --- | --- | | skills.sh (`skills` CLI) | `npx skills add amirbena/code-review-skills --skill ` | Lists what is available with `--list`. | -| Claude Code marketplace | `/plugin marketplace add amirbena/code-review-skills`, then `/plugin install code-review-skills@code-review-skills` | One plugin exposing both Skills. | +| Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, v1.56.0. **Install:** `marketplace add` + `install` from the published repository gave plugin 1.56.0. **Discovery:** both Skills loaded. **Runtime:** `local-code-review` ran scope discovery, found an empty delta, and returned a vacuous `REVIEW CLEAN` with no invented findings; `github-pr-review`, invoked without a valid PR, asked for a PR target and publication mode and made no GitHub write | | Codex | `codex plugin marketplace add amirbena/code-review-skills`, then `codex plugin add code-review-skills@code-review-skills` | Reads the same `.claude-plugin/marketplace.json`. | | GitHub Copilot CLI | `copilot plugin marketplace add amirbena/code-review-skills`, then `copilot plugin install code-review-skills@code-review-skills` | Direct `copilot plugin install amirbena/code-review-skills` also works but its CLI warns that direct installs are deprecated. | | Cursor | install from `amirbena/code-review-skills` in the Cursor app (documented entry point: "Import from Repo") | No Cursor-specific file is needed; see the table below for what was tested. | @@ -50,12 +50,17 @@ has shown that it does. An unexercised path is never to be read as working. | skills.sh: `skills update` picking up a newer release | documented | ran `npx skills update -p -y` at 1.56.0 (refreshed both, no newer release exists); a real update needs a subsequent release | | skills.sh listing | documented | 2026-09-24: per-Skill pages exist under `skills.sh/amirbena/code-review-skills/`, but the directory search does not return the Skills yet (listing depends on install telemetry); re-check after a release | | Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, fresh config directory: `marketplace add` + `install` gave plugin 1.56.0 with both Skills | -| Codex Agent Plugin path | verified | Codex CLI 0.156.1, macOS, 2026-09-24: `plugin marketplace add` + `plugin add` gave 1.56.0, both Skills present. The `"./"` entry path did not block it, so no separate Codex marketplace entry is needed. Reading only the root `plugin.json`, without the marketplace file, was not exercised | +| Codex Agent Plugin path | verified | Codex CLI 0.156.1 (from the earlier install run; the version of the later runtime run was not re-captured), macOS, 2026-09-24, v1.56.0. **Install:** `plugin marketplace add` + `plugin add` gave 1.56.0. **Discovery and runtime:** both Skills were discovered and invoked. The `"./"` entry path did not block it, so no Codex adapter or separate marketplace entry is needed. Reading only the root `plugin.json`, without the marketplace file, was not exercised | | GitHub Copilot Agent Plugin path | verified | Copilot CLI 1.0.88, macOS, 2026-09-24: direct install and `marketplace add` + `install` both gave 1.56.0 with two Skills. Not run against a pinned tag | -| Cursor Agent Plugin path | verified | Cursor 3.17.8 (installed app version), macOS, 2026-09-24, manual test of v1.56.0: both Skills installed from `amirbena/code-review-skills` and invoked successfully; no Cursor adapter or `.cursor-plugin` was needed. The exact UI steps were not recorded, so "Import from Repo" itself is not claimed as the tested path | +| Cursor Agent Plugin path | verified | Cursor 3.17.8 (installed app version), macOS, 2026-09-24, manual test of v1.56.0. **Install and discovery:** both Skills installed from `amirbena/code-review-skills`. **Runtime:** both invoked successfully. No Cursor adapter or `.cursor-plugin` was needed. The exact UI steps were not recorded, so "Import from Repo" itself is not claimed as the tested path | Windows was not exercised for any path. +"Verified" here covers install, discovery, and (where the row says so) a +runtime smoke invocation of the distributed Skills. It is not a review-quality +validation: the smoke runs show the Skills load, follow their input contract, +and do not invent findings, not that their reviews are correct. + Evidence records the client version, date, and the version observed. A path that fails or cannot be exercised is recorded as such. Gemini CLI and any vendor-specific adapter are out of scope here. From a84f7ff05972fbe661af57d3e6b3b4cba2f3bcc0 Mon Sep 17 00:00:00 2001 From: amirbena Date: Thu, 24 Sep 2026 16:08:27 +0300 Subject: [PATCH 4/5] Make distribution.md the canonical install, update and verification guide (#521) Co-Authored-By: Claude Sonnet 5 --- README.md | 46 +++++----- docs/distribution.md | 206 ++++++++++++++++++++++++++++--------------- 2 files changed, 160 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 3282575..6456213 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,26 @@ its own PR — see side-by-side detail is in [`docs/CODE_REVIEW_COMPARISON.md`](docs/CODE_REVIEW_COMPARISON.md) §9. -## Install / package +## Install -Building a Skill produces one standalone archive with `SKILL.md` and -`LICENSE` at its root (never nested under a `skills/` path), so a consumer -never needs to know this repository's layout. Pick the archive that matches -how the reviewer will be used — packaging both is rarely needed. +Install from the generated distribution repository, through your tool's own +Skill or plugin mechanism. For the `skills` CLI: + +```bash +npx skills add amirbena/code-review-skills --skill local-code-review +``` + +[`docs/distribution.md`](docs/distribution.md) is the canonical install guide: +commands for Claude Code, Codex, Cursor and GitHub Copilot, how updating +works per tool, and which paths are verified versus only documented. + +### Manual / offline + +Only when managed installation is unavailable. Building a Skill produces one +standalone archive with `SKILL.md` and `LICENSE` at its root (never nested +under a `skills/` path), so a consumer never needs to know this repository's +layout. Pick the archive that matches how the reviewer will be used — +packaging both is rarely needed. | Package | Command (shell · PowerShell) | Output | |---|---|---| @@ -57,25 +71,15 @@ how the reviewer will be used — packaging both is rarely needed. | GitHub PR review only | `./scripts/packaging/package-skills.sh github` · `./scripts/packaging/package-skills.ps1 github` | `dist/github-pr-review-skill.zip` | | Both entry points | `./scripts/packaging/package-skills.sh all` · `./scripts/packaging/package-skills.ps1 all` | both archives above | -To install from the published distribution repository instead: - -```bash -npx skills add amirbena/code-review-skills --skill local-code-review -``` - -For the Claude Code marketplace, Codex, Copilot, updates, and which install -paths are verified versus only documented, see -[`docs/distribution.md`](docs/distribution.md). +Unzip an archive directly into your runtime's Skill directory — for example +`.claude/skills//`, `.agents/skills//`, +`.cursor/skills//`, or `.opencode/skills//`. A ZIP install is not +equivalent to a managed one (no update command, not counted toward skills.sh). ## Quick start -1. **Package** the Skill you need (above). -2. **Install** the archive into your runtime's Skill directory — for - example `.claude/skills//`, `.agents/skills//`, - `.cursor/skills//`, or `.opencode/skills//`. Each archive - already keeps `SKILL.md` at its own root, so unzip it directly into that - directory. -3. **Invoke** it from the runtime. +1. **Install** a Skill (above). +2. **Invoke** it from the runtime. - `local-code-review` is opt-in — it runs only when you explicitly ask, every time. Optionally pass review context to focus attention: diff --git a/docs/distribution.md b/docs/distribution.md index f67759b..f35c90d 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -1,76 +1,125 @@ -# Installing from the distribution repository +# Installing, updating, and verifying the distributed Skills + +This is the consumer-facing guide for installing and updating +`local-code-review` and `github-pr-review`, and for seeing which install +paths have actually been exercised. It is explanatory; the publication +mechanics are owned by [`RELEASE.md`](RELEASE.md). + +**Recommended:** install from the generated distribution repository, +[`amirbena/code-review-skills`](https://github.com/amirbena/code-review-skills), +through your tool's own Skill or plugin mechanism (below). Downloading and +copying release ZIPs by hand is a fallback, covered last under +[Manual / offline installation](#manual--offline-installation). + +## Why a distribution repository + +```text +source repository (amirbena/code-review-skill) + ↓ +canonical deterministic build + ↓ +amirbena/code-review-skills (generated, never edited by hand) + ↓ +skills.sh / Claude Code / Codex / Cursor / GitHub Copilot +``` + +- The source repository stays canonical for development, issues, PRs and + releases. Its `skills//` folders are not standalone (they depend on + `shared/`), so do not install from a checkout of it. +- Each release builds deterministic, self-contained Skill trees. The + distribution repository is the consumer-facing publication surface for + those trees. +- Every consumer therefore receives the same canonical Skill trees. + Vendor-specific metadata (the Claude marketplace file, the portable + `plugin.json`) is an adapter around those trees and does not change the + Skill content. + +Build and publication details: [`RELEASE.md`](RELEASE.md), "Generated +distribution repository" and "Publishing each release to the distribution +repository". + +## Install by consumer + +Use `` = `local-code-review` or `github-pr-review`. Every command below +was run during [#511](https://github.com/amirbena/code-review-skill/issues/511) +(client versions in the matrix). + +| Consumer | Install | +| --- | --- | +| skills CLI / skills.sh | `npx skills add amirbena/code-review-skills --skill ` (`--list` shows what is available) | +| Claude Code | `/plugin marketplace add amirbena/code-review-skills`, then `/plugin install code-review-skills@code-review-skills` (one plugin, both Skills) | +| Codex | `codex plugin marketplace add amirbena/code-review-skills`, then `codex plugin add code-review-skills@code-review-skills` (reads the same `.claude-plugin/marketplace.json`) | +| Cursor | install from `amirbena/code-review-skills` in the Cursor app; the exact UI steps were not recorded, so "Import from Repo" is not claimed as the tested path | +| GitHub Copilot CLI | `copilot plugin marketplace add amirbena/code-review-skills`, then `copilot plugin install code-review-skills@code-review-skills`; a direct `copilot plugin install amirbena/code-review-skills` also worked, but the CLI warns direct installs are deprecated | + +The `skills` run in #511 targeted Claude Code (`-a claude-code --copy`). + +## Updating -Both Skills are published, on every release, to a generated repository, -[`amirbena/code-review-skills`](https://github.com/amirbena/code-review-skills). -This page says how to install and update from it, which install paths have -been exercised, and how to tell which release you have. It is explanatory; -the publication mechanics are owned by [`RELEASE.md`](RELEASE.md). - -## Which repository does what - -| | Source repository (`amirbena/code-review-skill`) | Distribution repository (`amirbena/code-review-skills`) | -| --- | --- | --- | -| Purpose | development, issues, PRs, releases, GitHub Release zips | what consumers install from | -| Skill content | `skills//` source folders (not self-contained: they depend on `shared/`) | `skills//` built, self-contained trees | -| Edited by | contributors | nobody: generated at release time, never by hand | -| Report problems here | yes | no | - -Install from the distribution repository, not from a checkout of the source -repository: the source `skills//` folders are not standalone. - -## Install - -Replace `` with `local-code-review` or `github-pr-review`. +Updates are release-only: the distribution repository changes only when a +release is published, and the plugin entry pins that release version, so +nothing changes between releases. **Update mechanisms are consumer-specific.** +`npx skills update` manages Skills installed by the `skills` CLI; it does not +update Claude Code, Codex, Cursor, or Copilot plugin installations, which use +their own tools. -| Path | Command | Notes | +| Consumer | Update path | State | | --- | --- | --- | -| skills.sh (`skills` CLI) | `npx skills add amirbena/code-review-skills --skill ` | Lists what is available with `--list`. | -| Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, v1.56.0. **Install:** `marketplace add` + `install` from the published repository gave plugin 1.56.0. **Discovery:** both Skills loaded. **Runtime:** `local-code-review` ran scope discovery, found an empty delta, and returned a vacuous `REVIEW CLEAN` with no invented findings; `github-pr-review`, invoked without a valid PR, asked for a PR target and publication mode and made no GitHub write | -| Codex | `codex plugin marketplace add amirbena/code-review-skills`, then `codex plugin add code-review-skills@code-review-skills` | Reads the same `.claude-plugin/marketplace.json`. | -| GitHub Copilot CLI | `copilot plugin marketplace add amirbena/code-review-skills`, then `copilot plugin install code-review-skills@code-review-skills` | Direct `copilot plugin install amirbena/code-review-skills` also works but its CLI warns that direct installs are deprecated. | -| Cursor | install from `amirbena/code-review-skills` in the Cursor app (documented entry point: "Import from Repo") | No Cursor-specific file is needed; see the table below for what was tested. | -| GitHub Release zip | download `local-code-review-skill.zip` or `github-pr-review-skill.zip` from the [source repository's releases](https://github.com/amirbena/code-review-skill/releases) and unzip into your runtime's Skill directory | Manual. Not the same as the paths above; see the note below. | - -A direct release-zip install is **not** equivalent to a skills.sh install: -it sends no install telemetry, so it is never counted toward, or listed on, -skills.sh, and it has no update command. - -## Compatibility: documented vs. verified - -Each row is one of two states. **Verified** means the path was exercised by -a real install from the distribution repository, with evidence recorded in -[#511](https://github.com/amirbena/code-review-skill/issues/511). **Documented** -means the ecosystem's own documentation says it should work and nothing here -has shown that it does. An unexercised path is never to be read as working. - -| Ecosystem | State | Evidence (client, date, observed version) | -| --- | --- | --- | -| CI: `skills` CLI discovery and copy install from the built tree | verified | `tests/integration/packaging/test_distribution_consumer_install.py` (#520) | -| skills.sh: `npx skills add amirbena/code-review-skills --skill ` for both Skills | verified | `skills` 1.7.0, macOS, 2026-09-24: both installed, `metadata.version` 1.56.0 | -| skills.sh: `skills update` picking up a newer release | documented | ran `npx skills update -p -y` at 1.56.0 (refreshed both, no newer release exists); a real update needs a subsequent release | -| skills.sh listing | documented | 2026-09-24: per-Skill pages exist under `skills.sh/amirbena/code-review-skills/`, but the directory search does not return the Skills yet (listing depends on install telemetry); re-check after a release | -| Claude Code marketplace | verified | Claude Code 2.1.272, macOS, 2026-09-24, fresh config directory: `marketplace add` + `install` gave plugin 1.56.0 with both Skills | -| Codex Agent Plugin path | verified | Codex CLI 0.156.1 (from the earlier install run; the version of the later runtime run was not re-captured), macOS, 2026-09-24, v1.56.0. **Install:** `plugin marketplace add` + `plugin add` gave 1.56.0. **Discovery and runtime:** both Skills were discovered and invoked. The `"./"` entry path did not block it, so no Codex adapter or separate marketplace entry is needed. Reading only the root `plugin.json`, without the marketplace file, was not exercised | -| GitHub Copilot Agent Plugin path | verified | Copilot CLI 1.0.88, macOS, 2026-09-24: direct install and `marketplace add` + `install` both gave 1.56.0 with two Skills. Not run against a pinned tag | -| Cursor Agent Plugin path | verified | Cursor 3.17.8 (installed app version), macOS, 2026-09-24, manual test of v1.56.0. **Install and discovery:** both Skills installed from `amirbena/code-review-skills`. **Runtime:** both invoked successfully. No Cursor adapter or `.cursor-plugin` was needed. The exact UI steps were not recorded, so "Import from Repo" itself is not claimed as the tested path | - -Windows was not exercised for any path. - -"Verified" here covers install, discovery, and (where the row says so) a -runtime smoke invocation of the distributed Skills. It is not a review-quality -validation: the smoke runs show the Skills load, follow their input contract, -and do not invent findings, not that their reviews are correct. - -Evidence records the client version, date, and the version observed. A path that fails or cannot be exercised is recorded -as such. Gemini CLI and any vendor-specific adapter are out of scope here. - -## Updates - -Updates are release-only: the distribution repository changes only when a -new release is published, and the Claude plugin entry pins that release -version, so nothing updates between releases. To pick up a release, use your -client's update command (for the `skills` CLI, `npx skills update`) or -reinstall. +| skills CLI / skills.sh | `npx skills update` | **pending verification**: run once at v1.56.0 it only refreshed the same version. A real cross-release update can only be verified after a later release | +| Codex | the CLI documents `plugin marketplace upgrade` | documented, not exercised | +| GitHub Copilot CLI | the CLI documents `plugin update` | documented, not exercised | +| Claude Code | the plugin/marketplace update flow of Claude Code | documented, not exercised | +| Cursor | not investigated | not exercised | + +If in doubt, reinstall from the distribution repository. Installing +successfully is never evidence that a path's update mechanism works. + +## Compatibility and verification + +**Verified** means exercised by a real run against the published +distribution repository, with evidence recorded in +[#511](https://github.com/amirbena/code-review-skill/issues/511). +**Documented** means the tool's own documentation says it should work and +nothing here has shown that it does. A "not recorded" or "not verified" cell +is unverified, never assumed working. + +All runs below are v1.56.0, macOS, 2026-09-24. + +| Consumer (client version) | Installation | Discovery of both Skills | Runtime smoke | Update | +| --- | --- | --- | --- | --- | +| CI, `skills` CLI against a local copy of the built tree | verified | verified | not applicable | not applicable | +| skills CLI / skills.sh (`skills` 1.7.0) | verified | verified | not recorded | pending verification | +| Claude Code (2.1.272) | verified | verified | verified | not verified | +| Codex (CLI 0.156.1) | verified | verified | verified | not verified | +| Cursor (3.17.8, installed app version) | verified | verified | verified | not verified | +| GitHub Copilot (CLI 1.0.88) | verified | verified (the CLI reported two installed Skills) | not recorded | not verified | + +Notes on the evidence: + +- **skills.sh listing:** per-Skill pages exist under + `skills.sh/amirbena/code-review-skills/`, but the directory search did not + return the Skills on 2026-09-24. Listing depends on install telemetry; + re-check after a later release. +- **Claude Code:** `local-code-review` ran scope discovery, found an empty + delta, and returned a vacuous `REVIEW CLEAN` with no invented findings. + `github-pr-review`, invoked without a valid PR, asked for a PR target and + publication mode and made no GitHub write. +- **Codex:** no Codex adapter was needed; the `"./"` marketplace entry path + did not block installation. The version shown is from the install run and + was not re-captured for the later runtime run. Reading only the root + `plugin.json`, without the marketplace file, was not exercised. +- **Cursor:** no Cursor adapter or `.cursor-plugin` was needed. The version is + the locally installed app version. +- **Copilot:** tested through both the marketplace and the direct install; + not run against a pinned tag. +- **Not exercised anywhere:** Windows, and a clean machine (runs used isolated + config directories). + +**What "runtime smoke" means.** It shows that the distributed Skill can be +discovered, loaded, and invoked, and that it follows its basic invocation and +input contract. It does not show that reviews are correct. Review behavior +and quality are validated separately by the repository's deterministic tests +and benchmark system. ## Which release do I have? @@ -78,4 +127,19 @@ reinstall. `metadata.version` field. - In the distribution repository, `DISTRIBUTION.json` records the version, the source repository and commit, and a hash of the published contents. - Tags `vX.Y.Z` in that repository match the source repository's releases. + Tags `vX.Y.Z` there match the source repository's releases. + +## Manual / offline installation + +Use this only when managed installation is unavailable: offline machines, +archival, or debugging. Download `local-code-review-skill.zip` or +`github-pr-review-skill.zip` from the +[source repository's releases](https://github.com/amirbena/code-review-skill/releases) +and unzip it into your runtime's Skill directory (for example +`.claude/skills//`, `.agents/skills//`, or `.cursor/skills//`); +each archive keeps `SKILL.md` at its root. To build an archive yourself, see +the root [README](../README.md#install). + +A ZIP install is **not** equivalent to a managed install: it sends no install +telemetry, so it is never counted toward or listed on skills.sh, it has no +update command, and none of the verification above applies to it. From baffb295771e3b68b0cdf3665740a6c1488d554d Mon Sep 17 00:00:00 2001 From: amirbena Date: Thu, 24 Sep 2026 16:43:40 +0300 Subject: [PATCH 5/5] Record v1.56.0 to v1.57.0 cross-release update evidence (#521) Co-Authored-By: Claude Sonnet 5 --- docs/distribution.md | 47 ++++++++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/distribution.md b/docs/distribution.md index f35c90d..12f6bbd 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -65,14 +65,15 @@ their own tools. | Consumer | Update path | State | | --- | --- | --- | -| skills CLI / skills.sh | `npx skills update` | **pending verification**: run once at v1.56.0 it only refreshed the same version. A real cross-release update can only be verified after a later release | -| Codex | the CLI documents `plugin marketplace upgrade` | documented, not exercised | +| skills CLI / skills.sh | `npx skills update` | **verified**: an existing v1.56.0 install updated to v1.57.0 in place, both Skills still discoverable | +| Claude Code / Desktop | refresh the marketplace through the Claude Code CLI, then the native Desktop **Update** button (or Claude Code's own plugin update) | **verified**: 1.56.0 → 1.57.0 without reinstalling; see the note below on when Desktop offers the update | +| Codex | `codex plugin marketplace upgrade code-review-skills` | **verified**: 1.56.0 → 1.57.0, both Skills discovered and smoke-tested at 1.57.0 | | GitHub Copilot CLI | the CLI documents `plugin update` | documented, not exercised | -| Claude Code | the plugin/marketplace update flow of Claude Code | documented, not exercised | -| Cursor | not investigated | not exercised | +| Cursor | none found for the tested install | **not verified for the tested path**: a local `file://` marketplace install is commit-pinned and stayed at 1.56.0. This does not mean Cursor cannot update plugins; a source that supports refresh was not tested | If in doubt, reinstall from the distribution repository. Installing -successfully is never evidence that a path's update mechanism works. +successfully is never evidence that a path's update mechanism works; each +update row above is verified only for the path and release pair stated. ## Compatibility and verification @@ -83,23 +84,27 @@ distribution repository, with evidence recorded in nothing here has shown that it does. A "not recorded" or "not verified" cell is unverified, never assumed working. -All runs below are v1.56.0, macOS, 2026-09-24. +Installation, discovery and runtime smoke runs are v1.56.0. Update runs are +v1.56.0 → v1.57.0 (the first release after v1.56.0). All on macOS, +2026-09-24. Client versions for the update runs were not re-captured except +Cursor's. | Consumer (client version) | Installation | Discovery of both Skills | Runtime smoke | Update | | --- | --- | --- | --- | --- | | CI, `skills` CLI against a local copy of the built tree | verified | verified | not applicable | not applicable | -| skills CLI / skills.sh (`skills` 1.7.0) | verified | verified | not recorded | pending verification | -| Claude Code (2.1.272) | verified | verified | verified | not verified | -| Codex (CLI 0.156.1) | verified | verified | verified | not verified | -| Cursor (3.17.8, installed app version) | verified | verified | verified | not verified | +| skills CLI / skills.sh (`skills` 1.7.0 for install) | verified | verified | not recorded | verified (1.56.0 → 1.57.0) | +| Claude Code (2.1.272 for install) | verified | verified | verified | verified (1.56.0 → 1.57.0) | +| Codex (CLI 0.156.1 for install) | verified | verified | verified | verified (1.56.0 → 1.57.0) | +| Cursor (3.17.8, installed app version) | verified | verified | verified | not verified for the tested local commit-pinned install | | GitHub Copilot (CLI 1.0.88) | verified | verified (the CLI reported two installed Skills) | not recorded | not verified | Notes on the evidence: - **skills.sh listing:** per-Skill pages exist under `skills.sh/amirbena/code-review-skills/`, but the directory search did not - return the Skills on 2026-09-24. Listing depends on install telemetry; - re-check after a later release. + return the Skills earlier on 2026-09-24. A later check the same day returned + `github-pr-review` (1 install) and not `local-code-review`. Listing depends + on install telemetry, so neither Skill is confirmed as listed yet. - **Claude Code:** `local-code-review` ran scope discovery, found an empty delta, and returned a vacuous `REVIEW CLEAN` with no invented findings. `github-pr-review`, invoked without a valid PR, asked for a PR target and @@ -109,7 +114,23 @@ Notes on the evidence: was not re-captured for the later runtime run. Reading only the root `plugin.json`, without the marketplace file, was not exercised. - **Cursor:** no Cursor adapter or `.cursor-plugin` was needed. The version is - the locally installed app version. + the locally installed app version. The update test used an install from a + local `file://` marketplace pinned to a commit; Cursor kept resolving that + cached commit after reload, and the `install_plugin` operation is a + reinstall, so it was not used. Testing a refresh-capable source (for example + an imported GitHub marketplace) across a later release is still open. +- **Claude Desktop update lifecycle:** Desktop kept showing 1.56.0 with Update + disabled, even after a full restart, while the local marketplace clone + under `~/.claude/plugins/marketplaces/` was still at the 1.56.0 + publication. After the marketplace was refreshed through the Claude Code + CLI, the clone advanced to 1.57.0, Update became enabled, and using it + upgraded the plugin in place. This shows that refreshing the locally cached + marketplace exposed the newer version and enabled the native update. It does not establish whether or when Desktop refreshes + marketplaces on its own; the test environment had `DISABLE_AUTOUPDATER=1`. +- **Codex update:** besides both Skills being discovered at 1.57.0, the smoke + runs reported the version and boundary of each Skill. Plugin icon paths + containing `..` were ignored and both large Skill prompts produced + context-truncation warnings; neither blocked discovery or invocation. - **Copilot:** tested through both the marketplace and the direct install; not run against a pinned tag. - **Not exercised anywhere:** Windows, and a clean machine (runs used isolated