Sync only the skills this CLI owns to basecamp/skills

basecamp/skills is shared by several CLIs, and every one of them ran the
same sync script against one shared .managed-skills: publish skills/*,
then delete every name in that file that the publisher's own tree lacks.
So hey-cli's v0.1.1 release deleted skills/basecamp and
skills/basecamp-doctor (basecamp/skills@08ef7ea), and basecamp-cli's
v0.10.0 and v0.11.0 deleted skills/hey (728a916, 42716d7). Today the
distribution repo holds only whichever CLI released last
(basecamp/skills#5).

Each publisher now owns a manifest of its own, .managed-skills.<source>,
and reads only that file to decide what to remove. A skills/<name> goes
only when this source's manifest lists it, this release no longer ships
it, and no other source's manifest claims it — a name two manifests
list is a collision to settle upstream, so it is warned about and left,
and a name another source's manifest holds is refused for publishing.
A target with no manifest for this source yet removes nothing; the old
"no manifest, so everything under skills/ is ours" fallback is gone,
since it is exactly what deleted the sibling's skills.

The legacy .managed-skills stays, rewritten on every run as a
comment-only tombstone. The pre-fix script skips every line it cannot
parse as a skill name, so a sibling still running it deletes nothing;
had the file been removed, that script's fallback would have claimed
every skills/* directory. That is what makes the rollout order across
CLIs irrelevant.

A push rejected because a sibling published first ("fetch first" on a
depth-1 clone, or non-fast-forward) drops the stale commit and applies
the sync again from the remote's new tip, collision guard included. The
token reaches git through a private GIT_CONFIG_GLOBAL insteadOf rewrite
rather than the clone URL, and the checkout must be clean before the
sync sweeps it into a commit.

SYNC_SOURCE overrides the source name (the bot identity and commit
message derive from it) so a test can play the other CLI, and
SKILLS_TARGET points the script at an existing checkout instead of
cloning; with DRY_RUN=local it applies and commits but skips the push.
scripts/test-sync-skills.sh (make test-sync-skills, in bin/ci) builds a
target reproducing basecamp/skills as the history above left it and runs
the script interleaved as both CLIs, through a rejected push included.

The script is the shared CLI seed's, byte-identical apart from the
CLI_NAME default. It also gains SKILLS_SOURCE, as hey-cli's already had,
and the manual recovery workflow adopts hey-cli's two-checkout pattern:
sync logic from the dispatching ref, content from the release tag.

Author: jeremy

.github/workflows/sync-skills.yml

@@ -7,8 +7,10 @@
 # a way back without cutting a new tag. This is it.
 #
 # scripts/sync-skills.sh mirrors the skills/ tree at the given ref into
-# basecamp/skills and no-ops when the content already matches, so re-running it
-# for an already-synced release is safe.
+# basecamp/skills — only this CLI's skills, tracked in its own manifest there
+# (.managed-skills.basecamp-cli); other CLIs' skills are never touched — and
+# no-ops when the content already matches, so re-running it for an
+# already-synced release is safe.
 name: Sync skills
 
 on:
@@ -52,8 +54,8 @@ jobs:
             exit 1
           fi
 
-          # sync-skills.sh mirrors the tree wholesale, so syncing an older tag
-          # would roll basecamp/skills back. Unlike the AUR, there is no
+          # sync-skills.sh mirrors this CLI's skills wholesale, so syncing an
+          # older tag would roll them back in basecamp/skills. Unlike the AUR, there is no
           # independent record of what the distribution repo currently holds, and
           # the only reason to run this by hand is that the newest release failed
           # to sync — so require exactly that release.
@@ -63,11 +65,24 @@ jobs:
             exit 1
           fi
 
-      # Check out the tag itself, not main: the sync must mirror the skills tree
-      # as it was released, even if main has moved on since.
+      # Two checkouts: sync logic from the dispatching ref, skills content from
+      # the release tag. A defect in scripts/sync-skills.sh is one of the ways
+      # the automatic sync fails, and running the tagged copy here would just
+      # re-run the defective script — recovery must be able to run a fix merged
+      # to main without cutting a new tag.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ inputs.tag }}
+          persist-credentials: false
+
+      # The content still mirrors the skills tree as it was released, even if
+      # main has moved on since: SKILLS_SOURCE points the script at this
+      # checkout. Fully qualified: actions/checkout resolves a bare name as a
+      # branch before a tag, so a branch sharing the tag's name would win and
+      # mirror unreleased content.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          path: release
           persist-credentials: false
 
       # Needed for dry runs too: the honest preview clones the target, so it
@@ -83,12 +98,14 @@ jobs:
           repositories: skills
           permission-contents: ${{ inputs.dry_run && 'read' || 'write' }}
 
-      # github.sha is the dispatching ref's SHA (main), not the tag's, so resolve
-      # the commit actually checked out — otherwise the sync records the wrong
-      # provenance for the release it claims to mirror.
+      # github.sha is the dispatching ref's SHA (main), not the tag's, so
+      # resolve the tagged commit from its own checkout — otherwise the sync
+      # records the wrong provenance for the release it claims to mirror.
       - name: Resolve the tagged commit
         id: source
-        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+        env:
+          TAG: ${{ inputs.tag }}
+        run: echo "sha=$(git -C release rev-parse --verify "refs/tags/${TAG}^{commit}")" >> "$GITHUB_OUTPUT"
 
       # DRY_RUN=remote, not local: the local path never clones basecamp/skills
       # and diffs against an empty repo, so every skill reads as newly added and
@@ -100,5 +117,6 @@ jobs:
           SKILLS_TOKEN: ${{ steps.skills-token.outputs.token }}
           RELEASE_TAG: ${{ inputs.tag }}
           SOURCE_SHA: ${{ steps.source.outputs.sha }}
+          SKILLS_SOURCE: release/skills
           DRY_RUN: ${{ inputs.dry_run && 'remote' || '' }}
         run: scripts/sync-skills.sh

.github/workflows/test.yml

@@ -181,6 +181,9 @@ jobs:
       - name: Run BATS integration tests
         run: make test-e2e
 
+      - name: Test the skills sync
+        run: make test-sync-skills
+
   cli-surface:
     name: CLI Surface Check
     runs-on: ubuntu-latest

Makefile

@@ -383,7 +383,7 @@ check-smoke-coverage: build
 
 # Run all checks (local CI gate)
 .PHONY: check
-check: fmt-check vet lint lint-actions test test-e2e check-naming check-surface check-skill-drift check-bare-groups check-lint-lockstep check-smoke-coverage provenance-check tidy-check
+check: fmt-check vet lint lint-actions test test-e2e test-sync-skills check-naming check-surface check-skill-drift check-bare-groups check-lint-lockstep check-smoke-coverage provenance-check tidy-check
 
 # Lint GitHub Actions workflows (requires actionlint + zizmor)
 .PHONY: lint-actions
@@ -564,6 +564,11 @@ sync-skills:
 	RELEASE_TAG=$(TAG) SOURCE_SHA=$$(git rev-parse HEAD) DRY_RUN=local scripts/sync-skills.sh
 
 # Sync skills (dry-run against real target repo)
+# Run the skills sync against a throwaway basecamp/skills, as two CLIs publishing in turn
+.PHONY: test-sync-skills
+test-sync-skills:
+	scripts/test-sync-skills.sh
+
 # Usage: make sync-skills-remote TAG=v1.2.3 SKILLS_TOKEN=ghp_...
 .PHONY: sync-skills-remote
 sync-skills-remote:
@@ -647,6 +652,7 @@ help:
 	@echo ""
 	@echo "Skills:"
 	@echo "  sync-skills         Local dry-run of skill sync (TAG=v1.2.3)"
+	@echo "  test-sync-skills    Run the skills sync as two CLIs against a throwaway target"
 	@echo "  sync-skills-remote  Remote dry-run (TAG=v1.2.3 SKILLS_TOKEN=...)"
 	@echo ""
 	@echo "  help           Show this help"

RELEASING.md

@@ -70,6 +70,28 @@ basecamp skill
 basecamp skill install
 ```
 
+## Skills sync
+
+Stable releases mirror `skills/` into [basecamp/skills](https://github.com/basecamp/skills),
+which several CLIs share. `scripts/sync-skills.sh` owns only this CLI's skills there:
+it records the names it published in `.managed-skills.basecamp-cli` at the target root
+and removes a `skills/<name>` only when that manifest lists it, the release no longer
+ships it, and no other CLI's `.managed-skills.*` claims it (a collision is warned about
+and left alone), and refuses outright to publish a name another CLI's manifest holds.
+A target with no `.managed-skills.basecamp-cli` yet is a first run: nothing is removed.
+A push rejected because another CLI published first is retried by applying the whole
+sync again from the remote's new tip, not by replaying the stale commit. The legacy shared `.managed-skills` is rewritten as a comment-only
+tombstone so a CLI still on the pre-fix script — which deleted everything its own tree
+lacked — deletes nothing (basecamp/skills#5).
+
+If the release-time sync fails, recover with the `Sync skills` workflow
+(`workflow_dispatch`, stable tag, optional dry run). It refuses anything but the latest
+stable release so it cannot roll the distribution repo back, and it runs the sync script
+from the dispatching branch against the tag's skills tree — so when the failure was a
+defect in `sync-skills.sh` itself, merge the fix to main and dispatch; no new release
+needed. `scripts/test-sync-skills.sh` (`make test-sync-skills`, in `bin/ci`) pins the
+ownership contract by running the script as both CLIs against a throwaway target.
+
 ## Requirements
 
 - On `main` branch with clean, synced working tree