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.
This commit is contained in:
Rusty Shackleford
2026-10-30 13:55:14 +08:00
committed by GitHub
parent 5cf23eaa16
commit d24e72bfd9
+10
View File
@@ -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