feat(skills): distribute the skills as Claude Code plugins, document ClawHub, and give Copilot/Codex the Router

[r-marques]

Closes the publishing half of nvm-monorepo#2595. Part of epic #2268.

Why

The nevermined-router skill has been published since #267 — it's on GitHub, and on ClawHub at nevermined-io/nevermined-router (v0.1.1, 172 downloads). So #2595 was never blocked on where to publish. It was blocked on two things that made the skill hard to actually get:

1. The Claude Code install was a six-line sparse-checkout incantation with no update path.
2. ClawHub was invisible. Zero occurrences of "clawhub" anywhere in the docs — we run a CI job publishing to a registry we never tell a reader about.

And one thing that made it incomplete: Copilot and Codex carried the payments half only, which the issue title (Claude / Cursor / Copilot) explicitly promises.

What changed

A Claude Code plugin marketplace (.claude-plugin/marketplace.json):

/plugin marketplace add nevermined-io/docs
/plugin install nevermined-router@nevermined

Two commands, and Claude Code keeps them current. The marketplace is named nevermined, so that's what users see and type — nevermined-io/docs is only the source it's served from.

Router guidance in the two single-file surfaces. .github/copilot-instructions.md and AGENTS.md each gain a condensed Router section: the buy loop, the two money traps, and the full guardrail table. Condensed on purpose — these files are always-on context, so every line competes with the payments content.

The install page now leads with the plugin, gains a ClawHub tab, and its "Supported Tools at a Glance" table no longer says the Router is unavailable on Copilot and Codex.

Two findings worth keeping

source: "./" copies the entire repo. The documented same-repo shape installs 33 MB into the plugin cache for a 64 KB skill — and twice over if you install both. Entries therefore use source: "./skills" with an explicit per-plugin skills array, matching the shape Anthropic's own amd-skills entry uses. 33 MB → 236 KB. Recorded in CLAUDE.md so nobody "simplifies" it back.

--dir is a global clawhub flag, so it has to precede the subcommand. clawhub install nevermined-router --dir ~/.claude/skills silently ignores it; the docs show the working form.

Verification

• claude plugin validate passes.
• Actually added the marketplace and installed both plugins from this branch — SKILL.md plus all five references/ land correctly, footprint 236 KB.
• Every raw.githubusercontent.com URL on the install page maps to a real, non-gitignored file (the docs#267 trap).
• Every API fact in the two new instruction sections was checked against skills/nevermined-router/SKILL.md and its references/ — including the three I re-verified by hand: the four required delegation/create fields, Issued semantics, and the /router/proxy headers.
• JSX tag balance checked on the install page.

⚠️ mintlify broken-links cannot run on any PR right now. A bare <token> placeholder in the generated development-guide/api-errors/codes.mdx aborts the parse for the entire site before it checks a single page. It's pre-existing on main and untouched here; the source fix is nvm-monorepo#2805, still open. I verified this PR's links directly instead: one internal link (/products/router/overview, present in docs.json) and clawhub.ai (200).

Follow-ups (not in this PR)

• A second PR links the skill from the Router docs section itself — stacked on this one, because it cites the install commands this PR creates.
• Submitting to Anthropic's official plugin directory is tracked separately.

⚠️ Merge order

Merge #291 first. This PR's two condensed files document BCK.ROUTER.0010; #291 adds it to the canonical skill, the four IDE rule files and guardrails.mdx. Landing this one alone leaves a window where the condensed fallback is more complete than the artifact this page calls "the complete Router skill" — which inverts the relationship CLAUDE.md mandates and the contract SKILL.md states about itself. Both PRs branch off main and don't conflict, so the order is the only constraint.

#290 is stacked on this one and goes last.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	Aug 11, 2026, 2:38 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[r-marques]

⚠️ The PR head moved during this review (fda4b5269e03 → 52fc1f6f9ae1). Findings were produced against fda4b5269e03; inline anchors were re-validated against 52fc1f6f9ae1, so double-check the placement of any comment that looks off.

🤖 Automated PR review — ✅ Ready to merge (after folding 1 blocker, 4 mediums, 7 lows)

Two-agent panel — code-reviewer and comment-analyzer — on a PR that is almost entirely prose but instructs autonomous agents to spend real money. Between them they found one blocking issue and eleven others, several of which broke claims I had made about my own verification. All are folded in as of 52fc1f6; nothing is outstanding.

What I reviewed

• Diff range origin/main...HEAD — 5 files, +263/−29 at review time (fda4b52).
• Panel: pr-review-toolkit:code-reviewer, pr-review-toolkit:comment-analyzer. The security-sensitive classification would normally add silent-failure-hunter / pr-test-analyzer / type-design-analyzer, but there is no executable code here beyond a JSON manifest, so those had nothing in scope.
• Every Router fact re-checked against nvm-monorepo origin/main — not a local checkout, which is 1234 commits behind and contains no BCK.ROUTER.0007–0010 at all.
• The two condensed sections were diffed against each other mechanically: zero divergence in endpoints, field names, error codes or retry verdicts.

🔴 Blocker — found by execution, not reading

npx clawhub update does not work as documented. Running it against a real install returns Error: Provide <slug> or --all. I had tested clawhub install and assumed update. Now npx clawhub update --all, verified end to end, plus a note that the lock file is per working directory — so a --dir ~/.claude/skills install must be updated from that same directory with the same flag.

🟡 Mediums

1. The requestId bullet described a same-id retry as returning "the original payment" — which reads as the retry succeeding. It returns 409 BCK.ROUTER.0002 with the original paymentId and no resource (router.service.ts:156-166, no status filter). The hazard is the recovery path: an agent hits an unexpected 409, and the obvious escape from a 409 is a fresh id — exactly the double-spend the key exists to prevent. Now stated, with "never answer that 409 with a fresh id". Fixed at its source in SKILL.md too, via #291.
2. "every guardrail" / "every BCK.ROUTER.* code" were false in both directions. The condensed files omit 0004/0005, the entire refuses-outright set (splits, internal targets, redirects, forged X-Router-*) and the relay limits. Scoped honestly.
3. "pin a version" was contradicted by its own command — a --depth 1 --sparse clone off main, in a repo with zero git tags. Now "take a snapshot you control".
4. 0010 appears only in this PR's two condensed files, inverting the documented "condensed ⊂ full" relationship. This is an artefact of the PR split, not a defect in either PR — #291 adds it to the skill, the four IDE rule files and guardrails.mdx. Merge #291 first, or accept a brief window where the fallback is richer than the artifact this page calls complete. Called out in the PR description.

💡 Lows

• CLAUDE.md implied claude plugin validate guards the source/skills invariant. It does not — mutation-tested: it passes source: "./", a removed strict, and a skills entry pointing at a directory that doesn't exist. Now says what it actually checks, that the invariant is on the reviewer, and gives the round-trip test that does catch it. Also documents what strict: false is for, since the previous text explained source and skills but not the third field a maintainer would delete.
• $schema pointed at a URL that 404s (anthropic.com/claude-code/marketplace.schema.json — the one Anthropic's own marketplace uses). Switched to schemastore, which resolves and knows these fields.
• Two different update commands — marketplace update refreshes the catalogue, plugin update updates the installed plugin. Both named.
• allowedRecipients is optional, and omitting it means any merchant the Router can reach. Worth one clause in a file that teaches an agent to mint its own budget.
• /plugin blocks were in a bash fence — they're Claude Code REPL commands and fail if pasted into a shell.
• ClawHub's registry version for the payments skill doesn't match its own SKILL.md header, and this PR is what makes inspect user-facing. The tab now says which to trust.
• "Every supported tool can now get either skill" overclaimed for Copilot, which gets a condensed section, not the skill. Plus the page frontmatter and lead-in still described payments only.

Strengths the panel called out

• The two always-on files do not diverge — the hard part of this change, and it's clean.
• Every checkable Router fact matches origin/main, including 0010's mechanism, near-verbatim from the source hint rather than paraphrased.
• Guardrail framing survives intact into both surfaces: nothing anywhere suggests widening a Delegation or re-minting one as a recovery.
• Omitting version from the manifest is correct, not an oversight — version resolution falls through to the source commit SHA, which is what makes the "refreshes in the background" claim true.
• The "payments only" sweep is complete; no stale assertion survives anywhere in the repo.

Verdict: ✅ Ready to merge — 0 outstanding blockers, 0 should-fix, 0 nits. Merge after #291.

[r-marques]

Second review round — two more findings folded (0dd0a29… see latest commits). Both verified before folding; both were cases where my own justification was wrong rather than merely imprecise.

1. The retry rule was scoped wrong for the paying path. The Guardrails section closed with an unqualified "Only 0006 and 0007 are retryable", sitting directly beneath a table of pay-path errors. Both throw sites traced on nvm-monorepo origin/main: 0006 comes only from router.service.ts:928 (the payments-summary aggregation) and 0007 only from router-concurrency.service.ts:31. So on the paying path 0007 is the only retryable code, and every other 500 is a stop — the opposite of what an agent writing a retry loop around /route would have taken from that sentence. The 0010 paragraph already said this; the summarising sentence directly below undid it.

2. CLAUDE.md justified source: "./skills" by download size, and that rationale is false. Verified against the installed anthropics/claude-plugins-official: /plugin marketplace add materializes a full-content snapshot of the repo's default branch into ~/.claude/plugins/marketplaces/<name>/ — every top-level directory, no .git — regardless of what source says. The repo lands on disk either way.

What source actually controls is what each installed plugin copies and loads on top of that snapshot. The reason this mattered more than a wording nit: left as written, a maintainer would add the marketplace, watch ~32 MiB arrive anyway, conclude "the source trick does nothing", and simplify it back to "./" — reaching the right conclusion from a wrong premise. Rewritten to argue from plugin content, with an explicit warning not to re-justify it by bandwidth.

Sizes corrected while there: du -sh reports block usage, ~19% high on a tree of small files. skills/ is 203,675 bytes apparent (~200 KB, not 236 KB); the repo is 33,619,640 bytes (~32 MiB), of which video/ and images/ are ~94%.

One reported finding I checked and am not acting on: a claim that the Windsurf figures in #291 were inverted. They aren't — I published a base→head pair in each unit, and characters sit below bytes in both states (5,292/5,240 base, 5,474/5,420 head; deltas +182 bytes / +180 characters, from two multi-byte em dashes).

[aaitor]

APPROVE. A carefully-built, low-risk docs change — and your own two-round self-review already folded a blocker + 11 findings, so I focused on independently re-verifying the money-path facts against nvm-monorepo origin/main rather than re-listing what's fixed. Every BCK.ROUTER.* status, retry flag, and the 0010/0011 mechanisms in the two always-on files are faithful to source, and the two files don't diverge. The one structural risk you flagged — the condensed fallback carrying 0010/0011 + the corrected paying-path retry rule while the canonical errors.md didn't — is resolved: #291 is now MERGED on main with all three, and #289 ∩ #291 = ∅ files, so the merged result is consistent. No HIGH/MEDIUM. Two LOWs + one out-of-scope flag below.

Verification I ran

• Read all 5 changed files in post-PR state on docs/skill-install-plugin-marketplace; CI green (2/2); marketplace.json parses; source: "./skills" + per-plugin skills + strict: false are as intended.
• Cross-checked every Router fact against origin/main (libs/helpers/src/lib/output/api-errors.ts + throw sites): 0001–0009 statuses/retryable flags match the condensed table exactly; 0010 (500, retryable:false, credential minted before the failure so requestId won't suppress a retry) and 0011 (402, retryable:false, 3-DS) match near-verbatim; 0006's only throw site is router.service.ts:1615 (summary aggregation) and 0007's is router-concurrency.service.ts:31 — so "on the paying path 0007 is the only retryable code" is correct.
• Merge order: #291 is merged to main (adds 0010/0011 to errors.md/SKILL.md/guardrails.mdx/4 IDE rule files, and scopes the retry sentence to the paying path). The two PRs share zero files → clean, consistent merge.
• The two always-on files carry identical Router facts (endpoints, field names, codes, retry verdicts); the only differences are cosmetic (bullets vs prose, one paragraph break).
• Links: /products/router/overview present in docs.json; clawhub.ai → 200; all 10 raw.githubusercontent.com/.../main/... URLs on the install page resolve 200 (the docs#267 trap). JSX balanced (Tabs 1/1, Tab 9/9, Note 3/3, Card 8/8); the /plugin block uses a text fence.
• Env naming: only sandbox/live in the published surfaces; the lone staging_* string is CLAUDE.md's own policy rule, not a leak.
• Over-engineering pass (inline): lean. marketplace.json is minimal; the CLAUDE.md source/strict warnings are load-bearing (they stop a maintainer re-simplifying to "./"), not bloat. Nothing to cut.

Out of scope — for the next Router-skill PR, not this one

• 0009 is framed purely as a crypto-rail condition ("wallet short on the target network" / stale cached address) in the condensed table and the "Fund the buyer wallet" step. On the card rail (MPP-stripe) 0009 is instead a card-issuer decline with no wallet to top up (see the 0009 hint on origin/main). This is inherited verbatim from the canonical errors.md, so condensing it as-is here is correct — but the canonical reference itself under-documents the card-rail meaning of 0009. Worth a follow-up on errors.md/guardrails.mdx, next to where 0011 now lives.
• Per your own workflow (and CLAUDE.md's "sync with main first"), sync this branch with main before merge so the Mintlify preview reflects the reconciled 0010/0011 state — not required for correctness, since #289 and #291 don't overlap.