agentsclimarketplace

Release

Skill ImBIOS/swarm-tools/.claude/skills/release

Handles version bumps and npm releases for the swarm-tools monorepo (opencode-swarm-plugin, claude-code-swarm-plugin, swarm-mail, swarm-queue). Use when: creating changesets, bumping versions, preparing releases, checking release status, debugging publish failures, verifying npm packages, or merging release PRs. Triggers: "release", "publish", "changeset", "bump version", "ship it", "new version", "create a release", "check npm", "verify publish", "/release"From its SKILL.md

Install
npx -y skills add ImBIOS/swarm-tools --skill release

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.8 KB, as published. Nobody here has run it

Release Workflow

Standard Release (CI-driven)

All releases go through changesets → CI → npm. Never publish manually unless CI is broken.

1. Create changeset

cat > .changeset/<descriptive-name>.md << 'EOF'
---
"opencode-swarm-plugin": patch
---

fix: description of what changed and why
EOF

Bump levels: patch (bug fixes), minor (features), major (breaking changes).

Which packages to include — only packages with actual changes:

  • opencode-swarm-plugin — main plugin (CLI, MCP server, swarm orchestration)
  • claude-code-swarm-plugin — thin Claude Code wrapper (commands, agents, hooks, skills)
  • swarm-mail — agent messaging, memory, reservations
  • swarm-queue — task queue

Use pdf-brain for commit quotes:

pdf-brain search "<relevant topic>" --limit 1 --expand 500

2. Commit and push

git add .changeset/<name>.md <changed-files>
git commit -m "feat: description"
git push origin main

3. CI creates release PR

CI (publish.yml) runs on push to main:

  1. Detects changesets → runs changeset version + bun update
  2. Syncs plugin.json versions (lifecycle hook at .changeset/config.json)
  3. Opens/updates PR on changeset-release/main branch
  4. AI generates PR title via vercel/ai-action

4. Merge release PR

gh pr merge <number> --squash --delete-branch

CI then:

  1. Builds all packages
  2. Verifies tarballs contain expected artifacts
  3. Runs scripts/ci-publish.sh — packs with bun pm pack (resolves workspace:*), publishes via npm publish
  4. Tags releases
  5. Generates and posts release tweet to @swarmtoolsai

5. Verify

npm view opencode-swarm-plugin@latest dependencies
npm view claude-code-swarm-plugin@latest version

Critical check: Verify no workspace:* in published deps. If found, the publish script's safety net failed — see Troubleshooting.

Version Touchpoints

CI handles all of these via changesets. For manual bumps, ALL must be updated:

PackageFiles
opencode-swarm-pluginpackages/opencode-swarm-plugin/package.json, claude-plugin/.claude-plugin/plugin.json
claude-code-swarm-pluginpackages/claude-code-swarm-plugin/package.json, .claude-plugin/plugin.json
swarm-mailpackages/swarm-mail/package.json
swarm-queuepackages/swarm-queue/package.json

Manual bump script: ./scripts/bump-version.sh <version>

Troubleshooting

workspace:* in published npm package

The scripts/ci-publish.sh uses bun pm pack (resolves workspace protocol) + a python3 safety net that rewrites any remaining workspace:* to actual versions. If this still fails:

  1. Check bun version — packageManager in root package.json must be >= 1.3.5
  2. Verify safety net ran — CI logs should show "resolving from monorepo" if workspace deps leaked
  3. Nuclear option: bump the broken package (patch changeset), push, merge release PR

CI publish fails with E403

Already-published version. Normal when re-running publish — || true catches it. Only a problem if the VERSION wasn't bumped (changeset not applied).

Plugin.json version mismatch

CI lifecycle hook should sync these. If not, manually:

VERSION=$(jq -r .version packages/opencode-swarm-plugin/package.json)
jq ".version = \"$VERSION\"" packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json > /tmp/p.json
mv /tmp/p.json packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json

Release PR not created/updated

Changesets action only runs when .changeset/*.md files exist (excluding README.md). If no changesets, it skips version PR creation and goes straight to publish (for any packages with unpublished versions).

Architecture Notes

  • Two Claude Code plugins: opencode-swarm-plugin (full, bundles MCP server + CLI) and claude-code-swarm-plugin (thin wrapper, shells out to swarm CLI). Both register as plugin name "swarm".
  • Publish script (scripts/ci-publish.sh): Iterates all packages/*, skips private, packs, resolves workspace deps, publishes tarball.
  • Changeset config (.changeset/config.json): Public access, GitHub changelog, ignores @swarmtools/web.
  • Tweet bot: CI generates release tweet via claude-opus and posts to X via OAuth. Cloudflare retry logic included.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.