Skip to content

Drop the setup skill; move auth recovery into the error path#6

Merged
walkerhughes merged 1 commit into
mainfrom
refactor/drop-setup-skill
Jul 25, 2026
Merged

Drop the setup skill; move auth recovery into the error path#6
walkerhughes merged 1 commit into
mainfrom
refactor/drop-setup-skill

Conversation

@walkerhughes

Copy link
Copy Markdown
Owner

Now that harbor auth login resolves 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_SUGGESTIONS in infra/errors.py said:

"Set HARBOR_API_KEY in this repo's .env file (see .env.example)."

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.py had the same stale .env advice for HARBOR_MCP_ENABLE_WRITES.

Where the guidance lives now

On failure, AUTH_SUGGESTIONS carries 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 instructions field, which Claude Code already loads into every session with no invocation. That is the mechanism for influencing how the plugin gets used.

CLAUDE.md at 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 description is 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 a list_jobs call the model can make when it needs one.

Verification

Check Result
claude plugin validate harbor-mcp passes (a plugin with no skills is valid)
claude plugin validate . passes; added the marketplace description it warned about
Lint ruff check and format clean
Unit suite 72 passed

The existing test_errors.py caught the stale assertion rather than silently passing. It now asserts the new procedure is present and that .env never reappears in it, so this specific regression cannot come back.

Bumped to 0.4.0 so installed copies receive it.

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.
@walkerhughes
walkerhughes merged commit 5102529 into main Jul 25, 2026
4 checks passed
@walkerhughes
walkerhughes deleted the refactor/drop-setup-skill branch July 25, 2026 07:32
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.

1 participant