From d24e72bfd952fc146bfa078de4c214ca665c0ffd Mon Sep 17 00:00:00 2001 From: Rusty Shackleford <182032677+salmonumbrella@users.noreply.github.com> Date: Thu, 29 Oct 2026 22:55:14 -0700 Subject: [PATCH] docs(skill): explain unpinning plugins and subdirectory plugin sources (#672) The built-in skill said that omitting --source-ref on update does not unpin a package, but not how to unpin one. It also did not say that a remote source is read only at its repository root, so agents facing a plugin kept in a subdirectory fell back to cloning a release tag and stayed pinned. Document that updating with --source-ref BRANCH stores the branch and follows its latest commit, and that a subdirectory plugin with no root marketplace is added from a local clone of the default branch, pulled before check or update. --- skills/skillshare/references/plugins.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/skills/skillshare/references/plugins.md b/skills/skillshare/references/plugins.md index 8b527955b..0bc45bab0 100644 --- a/skills/skillshare/references/plugins.md +++ b/skills/skillshare/references/plugins.md @@ -35,6 +35,16 @@ When adding a new package, omit `--source-ref` to follow the remote's default br Updates reuse its stored ref; omitting the flag on update does not unpin an existing package. Adding a plugin does not schedule automatic updates; run `check` and `update` later. `sync --all` does not update or sync plugins; use `plugin update --all` (`-a`) to update all managed plugins. +To follow a branch again after a pin, run `plugin update NAME --source-ref BRANCH`: the stored +ref becomes that branch, and later updates fetch its latest commit. Pin a tag or commit only +when the user asks for that version. + +A remote source is read at its repository root, where discovery looks for plugin manifests and +marketplaces. For a plugin in a subdirectory that no root marketplace lists, clone the +repository's default branch to a dedicated directory and add the plugin's folder from that +clone. A local source takes no `--source-ref`, so `check` and `update` see only what the clone +holds: run `git -C CLONE pull --ff-only` first. Do not check out a release tag in the clone +unless the user asked for that version. ## Inspect before changing