Skip to content

feat: server-beacon skill-update path for non-Bash clients#39

Merged
lxcong merged 3 commits into
chainbase-labs:mainfrom
Nowhitestar:claude/unruffled-tesla-5d3992
May 12, 2026
Merged

feat: server-beacon skill-update path for non-Bash clients#39
lxcong merged 3 commits into
chainbase-labs:mainfrom
Nowhitestar:claude/unruffled-tesla-5d3992

Conversation

@Nowhitestar
Copy link
Copy Markdown
Contributor

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.2 since 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_meta tool).

What's in here

  1. Protocol (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.
  2. SKILL.md — Step 0 now has 0.A (beacon, cross-client) → 0.B (inline bash, Code-only compat) → 0.C (MCP tool sanity check). Step B branches every persistence option on whether Bash is available, with explicit no-Bash fallback text that tells the user what didn't get saved and the exact terminal command to persist it manually. Step C points the non-shell fallback at GitHub Releases (we don't have a docs site).
  3. install/uninstall scriptsnpx skills remove chainbase-labs/agentkey was 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 in install.sh when git clone fails mid-run. Both fixed; added post-install filesystem verification.
  4. README / README_zh — accurate per-client update story, including a one-time bootstrap command for users currently stuck on a pre-1.4.0 skill on Desktop.
  5. CI (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).
  6. docs/SERVER-IMPLEMENTATION.md — handoff doc for the server PR.

How verified

  • 4/4 fixtures pass schema; 4/4 bad payloads correctly rejected
  • All cross-references in spec doc resolve
  • verify-version-sync awk still extracts 1.3.0 from SKILL.md frontmatter
  • Companion server PR exercises the actual MCP handshake (initialize + tools/list + tools/call); response is valid v1 JSON
  • Real GitHub Releases fetch + ETag caching works on the server side

Test plan

  • CI green (protocol-validate.yml and verify-version-sync.yml both pass)
  • Companion server PR merged + new @agentkey/mcp published
  • Release-please cuts v1.4.0 from this branch
  • On Claude Code: existing inline-bash Step 0 still fires for users on v1.3.x; they get prompted to update normally
  • On Claude Desktop with a pre-1.4.0 skill: user runs the README bootstrap command once to land v1.4.0; from that point on, every subsequent version is auto-discovered via the meta tool
  • On Cursor / Codex: meta tool returns the npx skills update -g agentkey recipe; user upgrades via shell

Notes for the reviewer

  • This is additive: Claude Code's existing inline-bash path is unchanged, so no regression risk there. The protocol's protocol_version: 1 + immortal update_doc_url fallback make future v2 servers safely degradable for v1 skills.
  • Claude Desktop deliberately has no update_command recipe 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's RECIPES map).

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.
@Nowhitestar Nowhitestar force-pushed the claude/unruffled-tesla-5d3992 branch from d4e3061 to c9034e1 Compare May 12, 2026 08:55
@Nowhitestar Nowhitestar changed the title Server-beacon skill-update path for non-Bash clients (Desktop fix) feat: server-beacon skill-update path for non-Bash clients May 12, 2026
@lxcong lxcong merged commit 65fb2f8 into chainbase-labs:main May 12, 2026
4 of 5 checks passed
@lxcong lxcong mentioned this pull request May 12, 2026
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).
@Nowhitestar Nowhitestar deleted the claude/unruffled-tesla-5d3992 branch May 12, 2026 10:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants