Your first run¶

By the end of this you will have installed skillup, run it against a marketplace you create, and seen it catch a change that would have reached nobody.

Nothing here touches a real repository. Everything happens in a throwaway directory you delete at the end.

You need: Go 1.26.5 or newer, and git.

1. Install it¶

go install gitlab.com/phpboyscout/skillup/cmd/skillup@v0.1.0

Check it runs — $(go env GOPATH)/bin needs to be on your PATH:

$ skillup --help
Version the segments of a Claude Code plugin marketplace

Usage:
  skillup [command]

Available Commands:
  apply       skillup apply
  check       skillup check
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  plan        skillup plan
  tag         skillup tag
  version     Print version, commit, and build date

No Go toolchain, or you would rather build from a clone? See Install skillup.

2. Make a marketplace to point it at¶

mkdir -p /tmp/demo/plugins/alpha/.claude-plugin /tmp/demo/.claude-plugin
cd /tmp/demo
git init -q .

cat > .claude-plugin/marketplace.json <<'JSON'
{
  "name": "demo",
  "owner": { "name": "you" },
  "plugins": [{ "name": "alpha", "source": "./plugins/alpha" }]
}
JSON

cat > plugins/alpha/.claude-plugin/plugin.json <<'JSON'
{
  "name": "alpha",
  "description": "A demo segment",
  "version": "0.3.0"
}
JSON

git add -A && git commit -qm "chore: seed the marketplace"

One segment, at 0.3.0, and no tags anywhere. That matters — you will see why shortly.

3. Ask what should happen¶

$ skillup plan --path .
  every segment is at the version its commits warrant

Nothing has changed since the manifest was written, so there is nothing to do.

4. Make a change, the way you normally would¶

echo "a new capability" > plugins/alpha/feature.md
git add -A && git commit -qm "feat(alpha): add a capability"

Now ask again:

$ skillup plan --path .
  alpha      0.3.0    -> 0.4.0    (minor, 1 commit(s))

A feat: earns a minor. Had you written fix:, it would say 0.3.1.

This is the moment the tool exists for. If you committed and pushed now, the content would be on the branch and the version would still say 0.3.0 — and because both harnesses cache by version, nobody would ever receive it. No error, no warning.

5. Watch the gate fail¶

check is what CI runs:

$ skillup check --path .
  alpha                    is 0.3.0 but its commits warrant 0.4.0 (minor)
      f1e2d3c4 feat(alpha): add a capability (minor)

  To fix, on your branch:

      skillup apply --path .
      git add -u && git commit --amend --no-edit   # or a new commit

  The version is what ships a segment: both harnesses cache by
  <marketplace>/<plugin>/<version> and neither resolves a git ref, so a
  version that does not move withholds your change from every consumer.

2026/08/11 14:07:14 ERRO a segment's version is behind what its commits warrant hints="run `skillup apply` and commit the result alongside your change; a version that does not move withholds the change from every consumer"

The instruction is printed on stdout above the error, deliberately. In a CI log the last line is a red ERRO, and the reader scrolling to it is looking for something to do, not a diagnosis.

$ echo $?
1

6. Fix it¶

$ skillup apply --path .
  alpha    0.3.0 -> 0.4.0

Look at what changed:

$ git diff
-  "version": "0.3.0"
+  "version": "0.4.0"

One line. The rest of the manifest is untouched, byte for byte.

Commit it with the change that earned it:

git add -u && git commit -q --amend --no-edit

$ skillup check --path . ; echo $?
  every segment is at the version its commits warrant
0

7. See that it needed no tags¶

You never created one. skillup worked out the previous version by reading the git history of plugins/alpha/.claude-plugin/plugin.json — the commit where that version last changed.

Prove it by making another change:

echo "a fix" >> plugins/alpha/feature.md
git add -A && git commit -qm "fix(alpha): correct it"
skillup plan --path .

  alpha      0.4.0    -> 0.4.1    (patch, 1 commit(s))

It counted from 0.4.0 — the version you just committed — not from 0.3.0. The manifest's own history is the baseline, which is why an untagged repository is a perfectly good input.

Clean up¶

cd .. && rm -rf /tmp/demo