Skip to content

Pin the npx skills install command to the stable tag - #83

Merged
178inaba merged 3 commits into
mainfrom
fix/81-unpinned-npx-skills-install
Sep 1, 2026
Merged

Pin the npx skills install command to the stable tag#83
178inaba merged 3 commits into
mainfrom
fix/81-unpinned-npx-skills-install

Conversation

@178inaba

@178inaba 178inaba commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Why

README.md documents two ways to install this repository's Agent Skill. #72 pinned the Claude Code plugin path through the stable tag and #78 implemented it; the npx skills line a few lines below was left naming no ref, so the installer clones the default branch.

That is the same silent drift #72 closed, still open on a channel the README advertises — and running the other way. Merging to main ships the current skills/rdsh/SKILL.md to anyone installing or updating through that path, while the binary they have from brew install is still the last released tag. The skill describes flags their binary does not have, and nothing goes red anywhere.

stable itself already moves correctly: the release workflow force-pushes it onto the new tag once the archives are published and attested. Nothing about the release pipeline changes here. What was missing is that this one install command did not ask for it.

What

  • README.md — the npx skills command now names the tag in URL form, npx skills add https://github.com/178inaba/rdsh/tree/stable, with a short comment recording why the shorthand is not used.
  • .github/workflows/ci.yml — a fifth assertion in the existing Assert the plugin distribution wiring step, matching the whole install command and emitting its own ::error:: line. Folded into that step rather than added beside it: it is the same class the step already guards, where a break reddens nothing and the first signal is a user running a skill their binary does not match. The step's comment previously described the symptom in one direction only (updates that stop arriving) and now covers both.
  • CLAUDE.md — the existing stable is moved only by the release workflow bullet names the README install line as a third consumer of the tag. No new bullet: this is one more consumer of a rule that already exists.

The shorthand, and a correction to the Issue

The Issue asks for the URL form over 178inaba/rdsh@stable on the grounds that both resolve stable at install time but only the URL form records the ref in the lockfile. Probing with a ref that cannot exist shows the first half of that is not what happens:

npx skills add 178inaba/rdsh@definitely-not-a-ref   → installs fine, from the default branch
npx skills add 178inaba/rdsh#definitely-not-a-ref   → fatal: Remote branch ... not found in upstream origin

skills reads the suffix in owner/repo@suffix as a skill-name filter, not a git ref — @stable never reaches git and does not pin anything. The Source: ... .git @stable line the installer prints is the shorthand echoed back, not a resolved ref; a real ref prints with a space (@ stable). Separately, the # fragment form (178inaba/rdsh#stable) does record "ref": "stable", so the URL form is not the only spelling that works.

Neither correction changes the requested command, but the rationale committed to README.md and CLAUDE.md states the measured behaviour rather than the Issue's reading — a guard rail arguing from a false premise stops guarding the moment someone checks it. Details and full output are in a comment on the Issue, which is worth carrying over to the sibling Issues 178inaba/cflio#76 and 178inaba/slio#56 that repeat the same table.

Verification

The new assertion was written before the README edit and run as-is against the still-unpinned README, so its red state is the one CI would produce:

::error::README.md's npx skills install command must pin the stable tag
exit=1        # against `npx skills add 178inaba/rdsh`
exit=0        # after the edit

Installing with the new command on macOS, project scope, in an empty temp directory records "ref": "stable" and npx skills update preserves it — recorded on the Issue. go test -race ./... and golangci-lint both pass (no Go code changes).

Considered and not done

  • Asserting the complement — "no unpinned npx skills add line exists" rather than "the pinned line exists". It is the stricter form and would catch a second, unpinned install snippet added later. Not taken: the Issue prescribes this shape with its reasoning, the same Issue is open on both sibling repositories, and the README has exactly one npx skills add occurrence with the rule now recorded in CLAUDE.md for the next editor. A divergence across the three lint jobs costs more than the case it covers.
  • Widening the step name past "plugin distribution wiring" now that it also asserts the non-plugin install path. It is still this skill's distribution wiring, and renaming drifts further from the sibling repositories' step names.

Closes #81

The command named no ref, so the installer cloned the default branch and
the skill ran ahead of the released binary it describes. The URL form is
required over the 178inaba/rdsh@stable shorthand: both resolve the ref at
install time, but only the URL form records it in the lockfile, so only it
survives npx skills update.
Measured against the installer rather than its output line: `skills` reads
the suffix in `owner/repo@ref` as a skill-name filter, not a git ref, so
`178inaba/rdsh@definitely-not-a-ref` installs from the default branch while
`178inaba/rdsh#definitely-not-a-ref` fails to clone. The shorthand does not
resolve the tag at all, and the `#ref` fragment form does record a ref — so
neither half of the rationale as first written held.
@178inaba 178inaba self-assigned this Sep 1, 2026
@178inaba
178inaba marked this pull request as ready for review September 1, 2026 16:41
Three lines of caveat over a one-line command read as the caveat being the
point. What stops the command from being shortened is the shorthand's
behaviour; what the URL form records is already on the stable bullet in
CLAUDE.md, so only the first half needs to sit in the install block.
@178inaba
178inaba merged commit 6391d4d into main Sep 1, 2026
3 checks passed
@178inaba
178inaba deleted the fix/81-unpinned-npx-skills-install branch September 1, 2026 17:05
@daemon-bot daemon-bot Bot mentioned this pull request Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Pin the npx skills install command to the stable tag, and assert it on CI

1 participant