feat(skill): add OAuth-first setup, slim SKILL.md via progressive disclosure#62
Merged
Conversation
… SKILL.md body Move the Step 0 version-check / upgrade / telemetry machinery (~165 lines, ~53% of the body) out of SKILL.md into references/maintenance.md, and the non-auto-list manual-install fallback into references/setup.md. SKILL.md drops from 317 to 127 lines and is now optimized for the high-frequency Query path; the upgrade flow loads only when a version mismatch actually fires, per progressive-disclosure guidance. Behavior unchanged: all protocol-version rules, the 4-option upgrade prompt, snooze/auto-upgrade persistence, error_class mapping, and every telemetry dispatch are preserved verbatim in references/maintenance.md. Frontmatter description (the triggering mechanism) and the release-please version line are untouched; version-sync (4 files) and bats (10/10) pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework the Setup flow now that the hosted MCP server supports native MCP OAuth. Prefer registering the remote URL with no key and letting the client run its own browser OAuth; fall back to a Console-minted API key (Bearer header) only when the client cannot do MCP OAuth or it fails. Written client-agnostically — no longer hard-codes the @agentkey/cli --auth-login one-liner or singles out one agent. references/setup.md restructured into "OAuth registration" + "API-key fallback" sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the stale @agentkey/cli --auth-login references now that Setup prefers native MCP OAuth. MCP config is written by the client/agent on registration, and the remaining npm egress is the skill-update command. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lxcong
changed the title
lxcong
changed the title
lxcong
added a commit
that referenced
this pull request
Jun 29, 2026
🤖 I have created a release *beep* *boop* --- ## [1.10.0](v1.9.1...v1.10.0) (2026-06-29) ### Features * **skill:** add OAuth-first setup, slim SKILL.md via progressive disclosure ([#62](#62)) ([8bc275a](8bc275a)) --- 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
1 participant
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.
What
Two changes to the AgentKey skill, on top of one another:
1. Slim
SKILL.mdvia progressive disclosureThe high-frequency Query path stays in
SKILL.md; the rarely-executed upgrade machinery moves to references that load only when needed.SKILL.md: 317 → ~127 lines. Step 0 collapses from ~165 lines of inline version-check / upgrade / telemetry logic to a ~12-line preflight stub.references/maintenance.md— the full upgrade flow: beacon protocol contract, 4-option upgrade prompt (With-Bash / No-Bash branches), snooze + auto-upgrade persistence,error_classmapping, and allupgrade_decision/upgrade_resulttelemetry. Loads only on a version-mismatch signal.2. OAuth-first Setup flow
Now that the hosted MCP server supports native MCP OAuth, the Setup flow prefers OAuth and only falls back to an API key when needed:
SKILL.mdSetup section rewritten — try OAuth first (register the remote URLhttps://api.agentkey.app/v1/mcpwith no key and let the client run its own browser OAuth), API key as fallback (Console-minted key +Authorization: Bearer). Written client-agnostically: no longer hard-codes the@agentkey/cli --auth-loginone-liner or singles out one agent.references/setup.mdrestructured into "OAuth registration" (per-client examples) + "API-key fallback" sections.SECURITY.mdposture aligned — dropped the stale--auth-loginreferences; MCP config is written by the client/agent on registration, and the only remaining npm egress is thenpx skills update agentkeyupdate command.Why
Per Anthropic's
skill-creatorguidance, theSKILL.mdbody is loaded on every skill trigger. Previously ~53% of that body was upgrade/telemetry plumbing that fires <1% of the time. Moving that machinery behind a reference cuts ~60% of per-query context while keeping the upgrade flow 100% intact.The Setup rework lets OAuth-capable clients connect without minting or pasting an API key — fewer steps, no long-lived secret to store — while keeping the API-key path for clients that can't do MCP OAuth.
Behavior
description(the triggering mechanism) is byte-for-byte identical; protocol rules, upgrade options, persistence files, and telemetry shapes are preserved verbatim inreferences/maintenance.md.Verification
verify-version-synclogic: all versions consistent at1.9.1.bats tests/: pass (update script untouched).npx skills add . --list: skill discoverable, frontmatter parses.--auth-loginreferences remain inSKILL.md/references/setup.md/SECURITY.md.Note on release type
This branch now carries a
feat(skill):commit (OAuth-first setup), so the PR title has been retitled tofeat(skill):— squash-merging will cut a release via release-please.🤖 Generated with Claude Code