feat: server-beacon skill-update path for non-Bash clients#39
Merged
lxcong merged 3 commits intoMay 12, 2026
Merged
Conversation
Two related bugs in install.sh / uninstall.sh and their PowerShell twins, both rooted in how the `npx skills` CLI handles bad inputs: 1. `skills remove` takes the **skill name** (`agentkey`), not the repo path. uninstall.sh / uninstall.ps1 were passing `chainbase-labs/agentkey`, so the CLI printed "No matching skills found" — but exited 0. The uninstaller's `if exit-code == 0` branch then printed "✓ Skill removed from detected agents" while the files stayed untouched. Switch the argument to `agentkey` and gate the success message on the stdout string instead of the exit code. 2. `skills add` exits 0 even when it prints "Installation failed" (e.g. a network / git-clone error mid-run). install.sh / install.ps1 trusted the exit code, so a failed install was reported as success. Add a post-install check that scans the well-known per-agent skill paths for `agentkey/SKILL.md` and aborts with a clear retry hint when none exist. Verified locally: passing the correct skill name now both reports success and actually deletes ~/.agents/skills/agentkey and ~/.claude/skills/agentkey.
Adds the cross-client skill-update mechanism needed for Claude Desktop and any other MCP client that can't execute the inline `bash` block in SKILL.md Step 0. Without this, Desktop users get stuck on whatever skill version shipped at first install (this machine had a sandboxed 0.1.2 from April). How it works: - A new MCP tool `agentkey_skill_meta` (implemented in the server repo, spec'd here) returns structured JSON: latest skill version, detected client, and a client-specific upgrade recipe. - The skill rule (SKILL.md Step 0.A) calls it once per session and prompts the user to upgrade when the response's version differs from the frontmatter's. The legacy inline-bash check is retained as Step 0.B for Bash-capable clients. - Protocol is versioned (`protocol_version: 1`) with five immortal fields, so v1 skills are never broken by future v2/v3 servers; they fall back to `update_doc_url`. Repo contents: - protocol/skill-meta-v1.md — normative spec - protocol/skill-meta-v1.schema.json — JSON Schema, source of truth - protocol/example-response-*.json — fixtures covering all failure modes - docs/SERVER-IMPLEMENTATION.md — implementation handoff for @agentkey/mcp - .github/workflows/protocol-validate.yml — schema/fixture/cross-ref CI - skills/agentkey/SKILL.md — rule for parsing the beacon (Step 0.A) - README.md / docs/README_zh.md — Desktop upgrade section incl. one-time bootstrap command for users currently stuck on a pre-1.4.0 skill No behavior change for Claude Code users; the inline bash path is unchanged. Desktop and similar clients get a working upgrade prompt once @agentkey/mcp ships the corresponding tool.
Two correctness fixes to the v1.4.0 beacon design before shipping: 1. Step B no-Bash fallback. The four AskUserQuestion options each persist state by writing files under ~/.config/agentkey/. On Claude Desktop and other clients without a Bash tool, those writes silently fail today, so the rule would tell the user "snooze enabled" or "auto-upgrade on" while nothing was actually saved. Each option now branches on whether Bash is available; the no-Bash branch tells the user what didn't get saved and gives them the exact one-line terminal command to persist the setting manually. 2. Step C fallback path. Previously, when no shell update_command was available the rule pointed users at update_doc_url, which the server defaulted to https://agentkey.app/docs/upgrade — a URL we don't have. Now both the schema fixtures and the SKILL.md fallback point to https://github.com/chainbase-labs/agentkey/releases/latest, which is the actual authoritative source for release archives. Knock-on changes: - example-response-claude-desktop.json no longer carries a stub shell command for a script that doesn't exist; Desktop deliberately falls through to the GitHub-release manual path until a real installer ships. - Server recipe map in docs/SERVER-IMPLEMENTATION.md drops the Desktop entry, with a comment explaining when to add it back. - Spec table marks Desktop as (omit) with the rationale captured inline.
d4e3061 to
c9034e1
Compare
lxcong
added a commit
that referenced
this pull request
May 12, 2026
🤖 I have created a release *beep* *boop* --- ## [1.4.0](v1.3.1...v1.4.0) (2026-05-12) ### Features * server-beacon skill-update path for non-Bash clients ([#39](#39)) ([65fb2f8](65fb2f8)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the silent-update-failure mode where Claude Desktop (and any MCP client without a Bash tool) gets stuck on whatever skill version shipped at first install. On this developer's Desktop the skill had been frozen at
0.1.2since April — no upgrade ever fired.Root cause is structural: SKILL.md Step 0's update check uses an inline
```bash ```block. Claude Code executes it; Desktop reads it as documentation. So the entire upgrade flow is dead code on Desktop. This PR routes the version check through the MCP server instead (always-on, available to every client), and tightens a couple of correctness bugs in the existing install/uninstall path while we're here.Companion PR: chainbase-labs/AgentKey-Server (server-side
agentkey_skill_metatool).What's in here
protocol/skill-meta-v1.md+skill-meta-v1.schema.json+ 4 fixtures) — versioned, additive-evolution wire format for an MCP meta tool that returns{skill_version_latest, client_detected, update_command, update_doc_url, …}. Spec lives in this repo (single source of truth); server vendors a copy and CI on both sides diffs them.npx skills remove chainbase-labs/agentkeywas the wrong invocation: the CLI takes the skill name (agentkey), exits 0 on no-match, and made the uninstaller falsely report success. Same class of silent-success bug ininstall.shwhengit clonefails mid-run. Both fixed; added post-install filesystem verification.protocol-validate.yml) — every fixture validates against the schema, schema rejects 4 known-bad payloads (regression guard), spec doc references every fixture (forces docs ↔ artifact sync).docs/SERVER-IMPLEMENTATION.md— handoff doc for the server PR.How verified
verify-version-syncawk still extracts1.3.0from SKILL.md frontmatterTest plan
protocol-validate.ymlandverify-version-sync.ymlboth pass)@agentkey/mcppublishedv1.4.0from this branchv1.3.x; they get prompted to update normallyv1.4.0; from that point on, every subsequent version is auto-discovered via the meta toolnpx skills update -g agentkeyrecipe; user upgrades via shellNotes for the reviewer
protocol_version: 1+ immortalupdate_doc_urlfallback make future v2 servers safely degradable for v1 skills.update_commandrecipe yet — Desktop installs skills into a sandboxed~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/<UUID>/...path that no external CLI can reach, and we don't have a first-party installer script. The skill rule's "no command → point at GitHub Releases" fallback handles this until one exists. Adding a Desktop recipe later is a non-breaking change (one row in the server'sRECIPESmap).