agentkey

What this skill does

# AgentKey

<SUBAGENT-CONTEXT>Skip to Query Mode.</SUBAGENT-CONTEXT>

**Step 0 (always run first):**

0.A — **Server beacon check (cross-client; runs on every client including Claude Desktop):**

If the tool `agentkey_skill_meta` is visible in `list_tools`, call it **once** with `{}`. Otherwise skip to 0.B.

The response is structured JSON conforming to [protocol/skill-meta-v1](https://github.com/chainbase-labs/agentkey/blob/main/protocol/skill-meta-v1.md). Apply these rules **in order**:

1. Response missing, threw, or not valid JSON → skip silently to 0.B.
2. `response.protocol_version !== 1` → only honor `update_doc_url`; if present, remember it as a fallback for any prompt below.
3. `response.skill_version_latest === ""` → server admitted it can't tell (offline / rate-limited). Skip to 0.B without prompting.
4. `response.skill_version_latest` equals this SKILL.md's frontmatter `version:` field (read it from the top of this file) → up to date. Skip to 0.B.
5. Otherwise (versions differ): run the **Upgrade flow** below using `response.update_command` / `response.update_command_kind` / `response.update_doc_url`. **Never** call `agentkey_skill_meta` a second time in the same session.

0.B — **Inline check (compatibility path for clients with a Bash tool, e.g. Claude Code):**

```bash
bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/agentkey/scripts/check-update.sh" 2>/dev/null
```

The script may print **two kinds of lines** (in any order):

- **Update line** (one of):
  - `UP_TO_DATE` or empty → continue silently to 0.C.
  - `UPGRADE_AVAILABLE <old> <new>` → if 0.A already prompted the user this session, skip; else run the legacy **Upgrade flow** below with the new version, then continue to 0.C.
- **Telemetry line** (zero or one):
  - `TELEMETRY <event> <key=value> ...` → forward via MCP, silently and best-effort:
    ```
    agentkey_internal({
      path: "telemetry/event",
      params: { event: "<event>", properties: { /* parsed key=value pairs */ } }
    })
    ```
  - If the tool does not exist or fails, **ignore completely** — never surface a telemetry error to the user.
  - Do not let the telemetry dispatch block 0.C.

If your client has no Bash tool (Claude Desktop, some web-based clients), this step is a no-op — that's fine, 0.A already covered it.

0.C — **Verify MCP tools.** Confirm `list_tools`, `find_tools`, `describe_tool`, `execute_tool` are visible. If **any** are missing → **Setup** (regardless of what the user asked). Do not attempt Query without all 4. `agentkey_account` is optional — present on current servers, absent on older deployments; don't gate Setup on it.

### Upgrade flow

Triggered by either:
- **(A)** Step 0.A: `agentkey_skill_meta` returned a `skill_version_latest` different from this SKILL.md's frontmatter version. Use that response's `update_command` (when present) instead of the default `npx skills update` command below. The `<old>` is this SKILL.md's frontmatter version; `<new>` is `response.skill_version_latest`.
- **(B)** Step 0.B: `check-update.sh` printed `UPGRADE_AVAILABLE <old> <new>`. Use `<old>` and `<new>` from that line.

Below, `<old>` and `<new>` refer to whichever pair was resolved above.

**Step A — Check for auto-upgrade opt-in.** Run:
```bash
if [ "${AGENTKEY_AUTO_UPGRADE:-0}" = "1" ] || [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/agentkey/auto-upgrade" ]; then echo AUTO=1; fi
```
If the output is `AUTO=1`: tell the user once "Auto-upgrading AgentKey v\<old\> → v\<new\>…", run **Step C**, then continue to step 0.C. **Do not** show the AskUserQuestion prompt.

**Step B — Otherwise, prompt the user.**

If a Bash tool is available (Claude Code etc.), use `AskUserQuestion`. Otherwise (Claude Desktop and any web/sandboxed client without shell access), display the question and four options as a normal chat message and parse the user's natural-language reply.

**Important — persistence caveat for no-Bash clients:** the *Always*, *Not now*, and *Never ask again* options each persist state by writing a file under `~/.config/agentkey/`. Without a Bash tool you **cannot** write those files. Do not pretend you did — follow the no-Bash fallback line in each option below and tell the user exactly what state did or didn't get saved.

- Question: `AgentKey v<new> is available (currently on v<old>). Upgrade now?`
- Options:
  - **`Yes, upgrade now`** → run **Step C**.

    After running **Step C**, dispatch (silently, ignore failures):
    ```
    agentkey_internal({
      path: "telemetry/event",
      params: { event: "upgrade_decision", properties: {
        from_version: "<old>", to_version: "<new>", choice: "accept_once"
      }}
    })
    ```
  - **`Always keep me up to date`** →
    - **With Bash:** run `mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/agentkey" && touch "${XDG_CONFIG_HOME:-$HOME/.config}/agentkey/auto-upgrade"`. Tell the user "Auto-upgrade enabled — future AgentKey updates install automatically. Remove `~/.config/agentkey/auto-upgrade` to undo." Then run **Step C**.
    - **No Bash:** tell the user verbatim: "Your current client can't run shell commands, so I can't enable auto-upgrade for you. To turn it on, run this in your terminal once: `mkdir -p ~/.config/agentkey && touch ~/.config/agentkey/auto-upgrade`. For now I'll proceed with this one-time upgrade." Then run **Step C**.

    After the action, dispatch (silently, ignore failures):
    ```
    agentkey_internal({
      path: "telemetry/event",
      params: { event: "upgrade_decision", properties: {
        from_version: "<old>", to_version: "<new>", choice: "accept_always"
      }}
    })
    ```
  - **`Not now`** →
    - **With Bash:** run the snooze script:
      ```bash
      _CFG="${XDG_CONFIG_HOME:-$HOME/.config}/agentkey"
      _SNOOZE="$_CFG/update-snoozed"
      _NEW="<new>"
      _LEVEL=0
      if [ -f "$_SNOOZE" ]; then
        _SVER=$(awk '{print $1}' "$_SNOOZE" 2>/dev/null)
        [ "$_SVER" = "$_NEW" ] && _LEVEL=$(awk '{print $2}' "$_SNOOZE" 2>/dev/null)
        case "$_LEVEL" in *[!0-9]*) _LEVEL=0 ;; esac
      fi
      _LEVEL=$((_LEVEL + 1)); [ "$_LEVEL" -gt 3 ] && _LEVEL=3
      mkdir -p "$_CFG" && echo "$_NEW $_LEVEL $(date +%s)" > "$_SNOOZE"
      echo "SNOOZED_LEVEL=$_LEVEL"
      ```
      Translate the level into a duration for the user — `SNOOZED_LEVEL=1` → "Next reminder in 24h", `2` → "in 48h", `3` → "in 1 week". Continue to step 0.C — **do not** upgrade.
    - **No Bash:** tell the user verbatim: "Skipping for now. Your current client can't persist a snooze, so you may be re-prompted next session. To silence prompts for longer, run in a terminal once: `mkdir -p ~/.config/agentkey && touch ~/.config/agentkey/update-disabled` (permanently off — delete that file to re-enable)." Continue to step 0.C — **do not** upgrade.

    Map the choice for telemetry: With-Bash uses `SNOOZED_LEVEL` (`1` → `snooze_1d`, `2` → `snooze_2d`, `3` → `snooze_7d`); No-Bash uses `snooze_1d` (no persisted level). Then dispatch (silently, ignore failures):
    ```
    agentkey_internal({
      path: "telemetry/event",
      params: { event: "upgrade_decision", properties: {
        from_version: "<old>", to_version: "<new>", choice: "<mapped choice>"
      }}
    })
    ```
  - **`Never ask again`** →
    - **With Bash:** run `mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/agentkey" && touch "${XDG_CONFIG_HOME:-$HOME/.config}/agentkey/update-disabled"`. Tell the user "Update checks disabled. Remove `~/.config/agentkey/update-disabled` to re-enable." Continue to step 0.C — **do not** upgrade.
    - **No Bash:** tell the user verbatim: "Your current client can't run shell commands, so I can't persist this. To disable update checks permanently, run in a terminal once: `mkdir -p ~/.config/agentkey && touch ~/.config/agentkey/update-disabled`. I'll skip this prompt for the rest of this session." Continue to step 0.C — **do not** upgrade.

    After the action, dispatch (silently, ignore failures):
    ```
    agentkey_internal({
      path: "tel