Drop the setup skill; move auth recovery into the error path#6
Merged
Conversation
Now that `harbor auth login` resolves automatically from ~/.harbor/credentials.json, the setup skill was mostly restating what two cheaper mechanisms already cover. Fixes a live bug while moving it. AUTH_SUGGESTIONS said: "Set HARBOR_API_KEY in this repo's .env file (see .env.example)." That is the exact advice that caused the original HTTP 401, and it points at a path the server stopped reading. Any auth failure handed the agent actively misleading guidance. tools/writes.py had the same stale ".env" advice for HARBOR_MCP_ENABLE_WRITES. Where the guidance lives now: - AUTH_SUGGESTIONS carries the whole recovery procedure: diagnose with `harbor auth status` (noting it exits 0 either way, so read the output), `harbor auth login` if unauthenticated, `logout` then `login` if a stored key is revoked, restart, confirm with whoami. It fires exactly when auth breaks and costs nothing otherwise. - The MCP server's `instructions` field carries the standing guidance. Claude Code loads it into every session already, no invocation needed. A CLAUDE.md at the plugin root was considered and does not work: the plugins reference states it "is not loaded as project context." Deleting the skill also drops a standing cost. A skill's description is loaded every session so the model can decide whether to trigger it, which is a poor trade for a procedure that runs once at first install. Also adds the marketplace description that `claude plugin validate` warned about, and bumps to 0.4.0 so installed copies receive this. Verified: `claude plugin validate` passes for both manifests (a plugin with no skills is valid). Ruff clean, 72 unit tests pass. The existing errors test caught the stale assertion and now asserts the new procedure is present and that ".env" never reappears in it. Rendered the real auth-failure payload to confirm what an agent would actually receive.
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.
Now that
harbor auth loginresolves automatically from~/.harbor/credentials.json, the setup skill was mostly restating what two cheaper mechanisms already cover. Net 89 lines of skill removed, and a live bug fixed along the way.The bug this uncovered
AUTH_SUGGESTIONSininfra/errors.pysaid:That is the exact advice that produced the original HTTP 401, and it points at a path the server stopped reading in #3. Every auth failure was handing the agent actively misleading guidance.
tools/writes.pyhad the same stale.envadvice forHARBOR_MCP_ENABLE_WRITES.Where the guidance lives now
On failure,
AUTH_SUGGESTIONScarries the whole procedure. This is what an agent now actually receives:{ "error": "Not authenticated. Please run `harbor auth login` first.", "suggestions": [ "Run `harbor auth status` in a terminal to see whether a credential is stored. It exits 0 either way, so read its output, not its exit code.", "If it reports `Not authenticated`, ask the user to run `harbor auth login` themselves; it is an interactive OAuth flow and stores a key scoped to them in ~/.harbor/credentials.json.", "If it reports a logged-in user, the stored key is revoked or expired: ask the user to run `harbor auth logout` and then `harbor auth login` again.", "The server must be restarted to pick up new credentials. Then call whoami to confirm." ] }It fires exactly when auth breaks and costs nothing otherwise.
Standing guidance lives in the MCP server's
instructionsfield, which Claude Code already loads into every session with no invocation. That is the mechanism for influencing how the plugin gets used.CLAUDE.mdat the plugin root was considered and does not work. The plugins reference states it "is not loaded as project context."Why deleting beats keeping a thin skill
A skill's
descriptionis loaded every session so the model can decide whether to trigger it. That is a standing token cost for a procedure that runs once, at first install. The account-snapshot step it also did is just alist_jobscall the model can make when it needs one.Verification
claude plugin validate harbor-mcpclaude plugin validate .The existing
test_errors.pycaught the stale assertion rather than silently passing. It now asserts the new procedure is present and that.envnever reappears in it, so this specific regression cannot come back.Bumped to 0.4.0 so installed copies receive it.