feat(plugin): publish kbagent through keboola/ai-kit, deprecate this repo's marketplace

[claude]

Requested by Jordan Burger · Slack thread

What it does

Keboola had two Claude Code plugin marketplaces; this leaves one — keboola-claude-kit in keboola/ai-kit — and turns this repo's marketplace into a deprecated shim that still serves existing installs.

Before / After

Before. Installing the kbagent plugin meant adding this repo as a marketplace. Keboola therefore advertised two competing marketplaces, and a user had no way to tell which was the real one.

/plugin marketplace add keboola/cli
/plugin install kbagent@keboola-agent-cli

After. One marketplace, keboola-claude-kit, published from keboola/ai-kit. The old commands keep working for now; the new ones are what every doc, kbagent context, and kbagent doctor tell you.

/plugin marketplace add keboola/ai-kit
/plugin install kbagent@keboola-claude-kit

How

The plugin source stays here, in plugins/kbagent/. Four CI gates in this repo generate and validate those files against the live command tree — make skill-gen / make skill-check, scripts/sync_version.py, scripts/check_command_sync.py, make version-check — and none of them exist in ai-kit, so moving the files would trade one marketplace for a permanent drift risk. What moves is publication: ai-kit's marketplace carries an external git-subdir entry pointing at plugins/kbagent in this repo, pinned to a release tag, and a new release job repoints that entry on every stable tag.

The syncing mechanism

.github/workflows/release-kbagent.yml gains an ai-kit-marketplace job, gated exactly like the existing homebrew job (needs: [version, freeze, publish-s3], non-prerelease, refs/tags/, environment: release). It checks out keboola/ai-kit with a new write-scoped PAT, jq-rewrites the kbagent entry's version and source.ref, and opens a PR with gh pr create rather than pushing to main, so ai-kit's Tier 0 / Tier 1 evals see the change before it ships.

Properties worth knowing:

• No-op safe. It compares the entry's version + source.ref values before touching the file (jq re-emits the whole document with its own indentation, so a git diff alone would open empty PRs), and exits 0 when they already match. Re-running a tag is free.
• Fails loudly if the file or the kbagent entry is missing in ai-kit — that means the entry was never registered or was reverted, and silently publishing nothing would be worse.
• A release no longer ships to plugin users by itself. Somebody has to merge the ai-kit PR. CONTRIBUTING.md's release checklist grows a step 13 saying so, and the sync map grows a row.

The deprecation shim, and how long it lives

.claude-plugin/marketplace.json is kept, mechanically intact, so existing installs keep resolving updates. The only change is that the kbagent entry's description now leads with the migration notice:

DEPRECATED — install from keboola/ai-kit: /plugin marketplace add keboola/ai-kit && /plugin install kbagent@keboola-claude-kit — …

That description string is what /plugin listings show, which makes it the only in-product channel that reaches people already installed from here. scripts/sync_version.py still round-trips the file (it only writes version; verified), so make version-check stays green and the file is untouched in the git diff --exit-code path lists in the Makefile and this workflow.

Intended lifetime: about three releases. Then drop the entry and leave a renames: {"kbagent": null} tombstone. Note that renames cannot redirect across marketplaces — it only renames within one — so there is no mechanism that migrates an installed user automatically. The migration is necessarily a manual two-line user action, which is exactly why the notice lives in the description and why doctor nags.

doctor and the docs

• doctor's claude_plugin check now probes both cache dirs, new first: ~/.claude/plugins/cache/keboola-claude-kit/kbagent, then the legacy ~/.claude/plugins/cache/keboola-agent-cli/kbagent. A plugin found only under the legacy dir still passes — it works and it updates — but the message appends reinstall-from-ai-kit instructions. The warn message for a missing plugin prints the two new /plugin lines. Three new tests cover the legacy-dir pass, the both-dirs-present preference, and an empty legacy root.
• Install commands updated in AGENT_CONTEXT (kbagent context), README.md, docs/TUTORIAL.md (including the cache path), docs/use-cases.md, plugins/kbagent/skills/kbagent/SKILL.md, plugins/kbagent/.claude-plugin/CLAUDE.md.
• CLAUDE.md's "This repo doubles as a Claude Code plugin marketplace" framing is rewritten to "the plugin lives here and is published through keboola/ai-kit", including why the source stays and why the shim must not be deleted.

Version bump

Bumped 0.86.0 → 0.87.0 with a changelog entry, via make version-sync (no hand-edits to __init__.py / plugin.json). Reasoning: CONTRIBUTING.md defines a release as "whenever you bump pyproject.toml's version", and the merged history shows user-facing code changes bumping (#615, #616) while CI-only and docs-only changes do not (#610, #617). This changes user-visible doctor and context output and the install command every user types, so it is on the bump side. The changelog entry leads with Change (install path): — deliberately not BREAKING:, because nothing breaks today.

Coordination

• The ai-kit PR should merge first. It registers the kbagent entry in keboola-claude-kit. Until it lands, the commands this PR documents do not resolve, and the ai-kit-marketplace job would fail its missing-entry guard.
• secrets.AI_KIT_TOKEN must be provisioned in the release environment before the next release, scoped to contents + pull-requests on keboola/ai-kit only. Without it the new job fails (the rest of the release still ships, and no ai-kit PR appears — which is the symptom to look for).

Overlap with #625

Draft PR #625 (feat/kbagent-setup-slash-command, adds /kbagent:setup) touches six of the same files in the same hunks: README.md, docs/TUTORIAL.md, src/keboola_agent_cli/commands/context.py, install.sh, plugins/kbagent/skills/kbagent/SKILL.md, plugins/kbagent/.claude-plugin/CLAUDE.md. I read its diff and kept the edits here surgical — in those six files this PR changes the marketplace/install command lines and nothing adjacent, and the two additions that are not command-line swaps (SKILL.md, plugin CLAUDE.md) are appended clear of #625's hunks.

#625 landing first is fine and preferred. Two notes for whoever rebases second:

• install.sh on current main does not mention the marketplace, so this PR leaves it alone. feat(plugin): add /kbagent:setup one-command first-run setup #625 adds a /plugin marketplace add keboola/cli, /plugin install kbagent@keboola-agent-cli line to its "Next steps" output — that line needs the new marketplace/plugin names, whether it is fixed in feat(plugin): add /kbagent:setup one-command first-run setup #625 or in a follow-up here.
• CLAUDE.md will conflict: feat(plugin): add /kbagent:setup one-command first-run setup #625 edits the surfaces sentence in the section this PR rewrites wholesale. Keep both — the rewritten framing plus feat(plugin): add /kbagent:setup one-command first-run setup #625's updated surface list.

Validation

make check minus changelog-check (that target shells out to gh, which is not installed in the environment this was authored in): lint, format-check, typecheck, skill-check, version-check, command-sync-check, check-error-codes, check-sentinel-guards and loc-check all green. Unit suite: 5690 passed; the only two remaining failures are test_config_store.py::TestPermissionDenied, which fail identically with pristine main files because the authoring environment runs as uid 0 and root ignores the chmod those tests rely on. Workflow YAML parses; every run: block passes bash -n; the bump step's four branches (already-current, new version, missing entry, missing file) were executed against a simulated ai-kit marketplace file. jq . .claude-plugin/marketplace.json is valid and scripts/sync_version.py round-trips it byte-for-byte.

Not in this PR

• Removing .claude-plugin/marketplace.json or its kbagent entry, and the renames tombstone — deliberately deferred ~3 releases.
• Any change in keboola/ai-kit (companion PR) or to feat(plugin): add /kbagent:setup one-command first-run setup #625.
• A machine-readable "installed from the legacy marketplace" field on doctor's JSON output; the signal is prose in message only. Worth adding if anything wants to act on it programmatically.