Pin the npx skills install command to the stable tag - #83
Merged
Conversation
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
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.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
README.mddocuments two ways to install this repository's Agent Skill. #72 pinned the Claude Code plugin path through thestabletag and #78 implemented it; thenpx skillsline 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.mdto anyone installing or updating through that path, while the binary they have frombrew installis still the last released tag. The skill describes flags their binary does not have, and nothing goes red anywhere.stableitself 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— thenpx skillscommand 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 existingAssert the plugin distribution wiringstep, 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 existingstableis 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@stableon the grounds that both resolvestableat 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:skillsreads the suffix inowner/repo@suffixas a skill-name filter, not a git ref —@stablenever reaches git and does not pin anything. TheSource: ... .git @stableline 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.mdandCLAUDE.mdstates 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:
Installing with the new command on macOS, project scope, in an empty temp directory records
"ref": "stable"andnpx skills updatepreserves it — recorded on the Issue.go test -race ./...andgolangci-lintboth pass (no Go code changes).Considered and not done
npx skills addline 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 onenpx skills addoccurrence with the rule now recorded inCLAUDE.mdfor the next editor. A divergence across the threelintjobs costs more than the case it covers.Closes #81