## Summary
Companion change to
[chainbase-labs/AgentKey-Server#32](https://github.com/chainbase-labs/AgentKey-Server/pull/32).
The npm package has been renamed; this PR updates everything users
actually see.
**User-facing**
- \`scripts/install.{sh,ps1}\`: \`MCP_PACKAGE\` / \`$McpPackage\` →
\`CLI_PACKAGE\` / \`$CliPackage\`
- \`scripts/uninstall.{sh,ps1}\`: sweep BOTH \`@agentkey/cli\` and
\`@agentkey/mcp\` so users upgrading from v0.x get a clean uninstall
- \`skills/agentkey/SKILL.md\`: setup command + manual-config JSON
example
- \`README.md\` + \`docs/README_zh.md\`: every \`npx @agentkey/mcp\`
command + the manual-config JSON examples (switched from stale stdio
shape to the remote-HTTP shape that \`--auth-login\` actually writes in
v1.0)
**Internal / protocol docs**
- \`SECURITY.md\`: file/network audit tables
- \`protocol/skill-meta-v1.md\`, \`docs/SERVER-IMPLEMENTATION.md\`:
clarify the protocol partner is AgentKey-Server's hosted \`/v1/mcp\`
endpoint, not a standalone npm package — these references were already
misleading before the rename
- \`.claude/CLAUDE.md\`: keep Claude-session guidance in sync
\`CHANGELOG.md\` left untouched (release-please manages history).
## Sequencing
Merge this PR **after** \`@agentkey/cli\` is published to npm —
otherwise the install scripts here will reference a package that doesn't
exist yet. Recommended order:
1. Merge
[AgentKey-Server#32](https://github.com/chainbase-labs/AgentKey-Server/pull/32)
2. \`cd cli && npm publish\` (first \`@agentkey/cli\` release at
\`1.0.0\`)
3. Merge this PR
## Test plan
- [ ] Verify \`npx -y @agentkey/cli --auth-login\` works end-to-end
after npm publish
- [ ] Verify \`scripts/uninstall.sh\` on a machine with
\`@agentkey/mcp\` globally installed cleans it up
- [ ] Spot-check the rendered README on GitHub for any missed references
## 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 scripts** — `npx 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).
Bruce