From 6d7cd2c664070c5c412e85ebe51d7855bf0c10c3 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Tue, 11 Aug 2026 16:37:09 +0200 Subject: [PATCH 1/4] feat(skills): distribute both skills as Claude Code plugins (#2595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds .claude-plugin/marketplace.json so the two published skills install with '/plugin marketplace add nevermined-io/docs' plus one '/plugin install' each, and auto-update thereafter — replacing a six-line sparse-checkout incantation. The marketplace is named 'nevermined', so users see and type '@nevermined' rather than the repository name. Entries use source './skills' with an explicit per-plugin skills array (the shape Anthropic's own amd-skills entry uses): 'source: "./"' also works but copies the entire 33 MB docs repo into the plugin cache for a 64 KB skill. Verified with 'claude plugin validate', then by adding the marketplace and installing both plugins locally. Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 59 +++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 .claude-plugin/marketplace.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 00000000..9f4a33c7 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,59 @@ +{ + "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", + "name": "nevermined", + "description": "Nevermined's AI coding skills: monetize an agent with the Payments SDK, or let one buy from external x402 / MPP services through the Nevermined Router.", + "owner": { + "name": "Nevermined", + "url": "https://nevermined.ai" + }, + "plugins": [ + { + "name": "nevermined-payments", + "displayName": "Nevermined Payments", + "description": "Charge for your AI agent or API. Covers the Nevermined Payments SDK (TypeScript and Python), the x402 protocol, payment plans and credits, and middleware for Express, FastAPI, Strands, MCP and Google A2A.", + "author": { + "name": "Nevermined", + "url": "https://nevermined.ai" + }, + "homepage": "https://nevermined.ai/docs/development-guide/build-using-nvm-skill", + "license": "MIT-0", + "category": "development", + "keywords": [ + "payments", + "x402", + "agents", + "monetization", + "mcp" + ], + "source": "./skills", + "strict": false, + "skills": [ + "./nevermined-payments" + ] + }, + { + "name": "nevermined-router", + "displayName": "Nevermined Router", + "description": "Let your agent pay external services it has no account with. Covers discovering services in the Agent Services Catalog, creating a capped spending Delegation, paying any x402 or MPP endpoint through the Nevermined Router, reading the payment ledger, and the guardrails an autonomous buyer must respect.", + "author": { + "name": "Nevermined", + "url": "https://nevermined.ai" + }, + "homepage": "https://nevermined.ai/docs/products/router/overview", + "license": "MIT-0", + "category": "development", + "keywords": [ + "payments", + "x402", + "mpp", + "agents", + "autonomous-buying" + ], + "source": "./skills", + "strict": false, + "skills": [ + "./nevermined-router" + ] + } + ] +} From e2ea41403d7cf029fa75cdb93073cf9125431f9b Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Tue, 11 Aug 2026 16:37:24 +0200 Subject: [PATCH 2/4] feat(skills): add condensed Router guidance to the Copilot and Codex files (#2595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .github/copilot-instructions.md and AGENTS.md are single files with no per-skill segment, so until now they carried the payments half only — an assistant reading either could help you charge for an agent but not buy from one. Each now gains a Nevermined Router section: the buy loop, the two money traps (requestId is an idempotency key not a counter; targetUrl is a complete URL not a base), whole-cent rounding, and the full BCK.ROUTER.* guardrail table with 'never widen a Delegation to get past a refusal'. Condensed rather than complete — these files are always-on context, so every line competes with the payments content. Co-Authored-By: Claude Opus 5 (1M context) --- .github/copilot-instructions.md | 74 ++++++++++++++++++++++++++++++++- AGENTS.md | 71 ++++++++++++++++++++++++++++++- 2 files changed, 141 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3ffe90e9..a7aa1c09 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,6 @@ -# Nevermined Payments — GitHub Copilot Instructions +# Nevermined — GitHub Copilot Instructions -This repository contains documentation for Nevermined, an AI payment infrastructure platform. When assisting with code that integrates Nevermined payments, follow these patterns. +This repository contains documentation for Nevermined, an AI payment infrastructure platform. It covers two halves: **receiving** payments (the SDK and REST patterns below) and **spending** at external x402 / MPP services through the **Nevermined Router** (last section). When assisting with code that integrates Nevermined, follow these patterns. ## SDK Packages @@ -95,6 +95,76 @@ Card payments: `scheme: "nvm:card-delegation"`, `network: "stripe"`. A human is - **Delegation first:** create a spending delegation (`POST /delegation/create` with `provider` + `currency` + `spendingLimitCents` + `durationSecs`, or SDK `createDelegation`) and reuse its `delegationId`. The inline create-on-the-fly `delegationConfig` (passing limits without a `delegationId`) is **deprecated since `@nevermined-io/payments` 1.8.0** — it only emits a runtime warning now; always pass an explicit `delegationId`. - **Seller analytics:** discover your `orgId` from `.orgId` on `GET /protocol/plans` / `/protocol/agents` records (no separate lookup endpoint). A malformed/placeholder `orgId` returns a silent 200-of-zeros; a non-Premium org returns `403 BCK.ORGANIZATIONS.0022`; a non-admin org returns `403 BCK.AUTH.0004`. +## Nevermined Router — paying external services + +Use the Router when the agent must **pay** a service it has no account with — any x402 agent or MPP merchant. Everything above is the other half: *receiving* payments and buying Nevermined plans. Plain HTTP, no SDK: `Authorization: Bearer $NVM_API_KEY` against `$NVM_API_URL` (`https://api.sandbox.nevermined.app` sandbox, `https://api.live.nevermined.app` live). **Never send `NVM_API_KEY` to the merchant** — it authenticates you to Nevermined only; the merchant's own auth goes in `headers`. + +The Router pays a price quoted **on the wire**. A service answering `401`/`403` rather than `402` wants authentication, not payment — say so, don't route it. + +### 1. Create a Delegation (the budget) + +```bash +curl -sX POST "$NVM_API_URL/api/v1/delegation/create" \ + -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \ + -d '{"provider":"erc4337","currency":"usdc","spendingLimitCents":500,"durationSecs":604800}' +# → { "delegationId": "5e7481c3-…" } +``` + +All four fields are required — no defaults. `erc4337` is the crypto-funded Delegation both stablecoin rails need. Create it once and reuse the id. + +### 2. Fund the buyer wallet + +Both rails **pull** from your own custodial wallet: a Delegation authorizes a spend, it does not supply funds. Read the address off the live Delegation every time — `GET /api/v1/delegation/{id}` → `providerPaymentMethodId` — and fund it with the payment asset on the network you intend to pay on. **Never reuse a cached address**: a stale one is the most common cause of `402 BCK.ROUTER.0009`, and that error deliberately does not echo the address it checked. + +### 3. Discover a service (public catalog, no API key) + +```bash +curl -s "$NVM_API_URL/api/v1/catalog/services?protocol=x402&search=web+search" +``` + +- Only `protocol` of `x402` or `mpp` is routable — filter for them. +- **`targetUrl` is the default endpoint's complete URL, not a base** (it may already carry the path), so concatenating yields `/search/search`. Resolve instead: + +```ts +const url = endpoint ? new URL(endpoint.path, service.targetUrl).toString() : service.targetUrl +``` + +### 4. Pay + +```bash +curl -sX POST "$NVM_API_URL/api/v1/router/route" \ + -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \ + -d '{"delegationId":"'"$NVM_DELEGATION_ID"'","url":"https://service.example/api/resource", + "method":"POST","body":{"query":"…"},"requestId":"search-nevermined-router-v1"}' +# → { "status": 200, "body": {…}, "paid": true, +# "payment": { "paymentId": "…", "settlement": { "approxCents": "1" }, "status": "Settled" } } +``` + +The Router probes the merchant, auto-detects the protocol from the 402, pays and relays. `status`/`body` are the merchant's own; `paid: false` with no `payment` block means the resource was free — handle that. For streaming use `ALL /api/v1/router/proxy` with `X-Router-Target-Url`, `X-Router-Delegation-Id` and `X-Router-Request-Id` headers. + +- **`requestId` is an idempotency key, not a request counter.** Use one stable id per logical purchase, reused across retries of that purchase: the same id returns the original payment, a fresh id buys again. **A fresh `uuid4()` per HTTP attempt is how an agent double-spends.** +- Budget is debited in **whole cents, rounded up** — 1000 calls at $0.001 costs $10.00, not $1.00. `settlement.approxCents` is what was actually reserved; trust it over any catalog `priceLabel`. + +### 5. Read what you spent + +`GET /api/v1/router/payments` (filters `delegationId`, `from`, `to`, `format=csv`) and `/api/v1/router/payments/summary`. `amount` is the asset's smallest unit, not cents. A record at `Issued` is **not** an error — the money moved; do not retry it. + +### Guardrails — a refusal is the system working + +| Code | Status | Meaning | Retry? | +| --- | --- | --- | --- | +| `BCK.ROUTER.0001` | 400 | Bad input / no fundable option / non-allowlisted asset; `details` names it | No | +| `BCK.ROUTER.0002` | 409 | `requestId` already used; the original `paymentId` is in the response | No | +| `BCK.ROUTER.0003` | 402 | Delegation over cap, expired, exhausted or revoked | No — **stop** | +| `BCK.ROUTER.0006` | 500 | Transient failure building the payments summary | **Yes** | +| `BCK.ROUTER.0007` | 429 | Too many concurrent routed requests in flight | **Yes**, after backoff | +| `BCK.ROUTER.0008` | 403 | Legacy API key — create a new one | No | +| `BCK.ROUTER.0009` | 402 | Wallet short on the target network; nothing was signed | No — **stop** | + +**Never widen a Delegation, and never create a second one, to get past a refusal.** The cap is the user's decision, not a runtime obstacle; minting a fresh Delegation to escape an exhausted one defeats the whole mechanism. Report and stop. Only `0006` and `0007` are retryable — everything else is a decision, and retrying it unchanged gives the same answer. Delegations also expire silently, so check `expiresAt` before diagnosing a `0003` as anything else. + ## Full Reference See `skills/nevermined-payments/SKILL.md` for complete integration patterns (Track A = operate autonomously via REST; Track B = add payments to your code via SDK). + +See `skills/nevermined-router/SKILL.md` and its `references/` for the Router half — discovery, mode A vs mode B, the ledger, and every guardrail. diff --git a/AGENTS.md b/AGENTS.md index 8eba8eda..074292a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ -# Nevermined Payments SDK +# Nevermined — Payments SDK and Router -This repository contains documentation for Nevermined, an AI payment infrastructure platform. When assisting with code that integrates Nevermined payments, follow these patterns. +This repository contains documentation for Nevermined, an AI payment infrastructure platform. It covers two halves: **receiving** payments (the SDK and REST patterns below) and **spending** at external x402 / MPP services through the **Nevermined Router** (last section). When assisting with code that integrates Nevermined, follow these patterns. ## SDK Packages @@ -82,6 +82,73 @@ await payments.a2a.start({ port: 3005, basePath: '/a2a/', agentCard, executor }) When an agent must act on its own behalf at runtime (buy a plan, enroll a card, check credits/revenue), call the REST API directly with `Authorization: Bearer $NVM_API_KEY` against `https://api.sandbox.nevermined.app` (sandbox) or `https://api.live.nevermined.app` (live). Buy in two calls — `POST /api/v1/x402/permissions` (→ `accessToken`) then `POST /api/v1/x402/settle` (→ `creditsRedeemed`, `remainingBalance`). Crypto uses `scheme: "nvm:erc4337"` / `network: "eip155:84532"`; cards use `scheme: "nvm:card-delegation"` / `network: "stripe"`. A human is needed only for one-time setup — the first API key, plus card enrollment if paying by card (the stablecoin path needs neither). Full runbook: `skills/nevermined-payments/references/autonomous-operations.md`. +## Nevermined Router — paying external services + +Use the Router when the agent must **pay** a service it has no account with — any x402 agent or MPP merchant. Everything above is the other half: *receiving* payments and buying Nevermined plans. Plain HTTP, no SDK: `Authorization: Bearer $NVM_API_KEY` against `$NVM_API_URL` (`https://api.sandbox.nevermined.app` sandbox, `https://api.live.nevermined.app` live). **Never send `NVM_API_KEY` to the merchant** — it authenticates you to Nevermined only; the merchant's own auth goes in `headers`. The Router pays a price quoted **on the wire**, so a service answering `401`/`403` rather than `402` wants authentication, not payment — say so, don't route it. + +### 1. Create a Delegation (the budget) + +```bash +curl -sX POST "$NVM_API_URL/api/v1/delegation/create" \ + -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \ + -d '{"provider":"erc4337","currency":"usdc","spendingLimitCents":500,"durationSecs":604800}' +# → { "delegationId": "5e7481c3-…" } +``` + +All four fields are required — no defaults. `erc4337` is the crypto-funded Delegation both stablecoin rails need. Create it once and reuse the id. + +### 2. Fund the buyer wallet + +Both rails **pull** from your own custodial wallet: a Delegation authorizes a spend, it does not supply funds. Read the address off the live Delegation every time — `GET /api/v1/delegation/{id}` → `providerPaymentMethodId` — and fund it with the payment asset on the network you intend to pay on. **Never reuse a cached address**: a stale one is the most common cause of `402 BCK.ROUTER.0009`, and that error deliberately does not echo the address it checked. + +### 3. Discover a service (public catalog, no API key) + +```bash +curl -s "$NVM_API_URL/api/v1/catalog/services?protocol=x402&search=web+search" +``` + +Only `protocol` of `x402` or `mpp` is routable — filter for them. **`targetUrl` is the default endpoint's complete URL, not a base** (it may already carry the path), so concatenating yields `/search/search`. Resolve instead: + +```ts +const url = endpoint ? new URL(endpoint.path, service.targetUrl).toString() : service.targetUrl +``` + +### 4. Pay + +```bash +curl -sX POST "$NVM_API_URL/api/v1/router/route" \ + -H "Authorization: Bearer $NVM_API_KEY" -H "Content-Type: application/json" \ + -d '{"delegationId":"'"$NVM_DELEGATION_ID"'","url":"https://service.example/api/resource", + "method":"POST","body":{"query":"…"},"requestId":"search-nevermined-router-v1"}' +# → { "status": 200, "body": {…}, "paid": true, +# "payment": { "paymentId": "…", "settlement": { "approxCents": "1" }, "status": "Settled" } } +``` + +The Router probes the merchant, auto-detects the protocol from the 402, pays and relays. `status`/`body` are the merchant's own; `paid: false` with no `payment` block means the resource was free — handle that. For streaming use `ALL /api/v1/router/proxy` with `X-Router-Target-Url`, `X-Router-Delegation-Id` and `X-Router-Request-Id` headers. + +- **`requestId` is an idempotency key, not a request counter.** Use one stable id per logical purchase, reused across retries of that purchase: the same id returns the original payment, a fresh id buys again. **A fresh `uuid4()` per HTTP attempt is how an agent double-spends.** +- Budget is debited in **whole cents, rounded up** — 1000 calls at $0.001 costs $10.00, not $1.00. `settlement.approxCents` is what was actually reserved; trust it over any catalog `priceLabel`. + +### 5. Read what you spent + +`GET /api/v1/router/payments` (filters `delegationId`, `from`, `to`, `format=csv`) and `/api/v1/router/payments/summary`. `amount` is the asset's smallest unit, not cents. A record at `Issued` is **not** an error — the money moved; do not retry it. + +### Guardrails — a refusal is the system working + +| Code | Status | Meaning | Retry? | +| --- | --- | --- | --- | +| `BCK.ROUTER.0001` | 400 | Bad input / no fundable option / non-allowlisted asset; `details` names it | No | +| `BCK.ROUTER.0002` | 409 | `requestId` already used; the original `paymentId` is in the response | No | +| `BCK.ROUTER.0003` | 402 | Delegation over cap, expired, exhausted or revoked | No — **stop** | +| `BCK.ROUTER.0006` | 500 | Transient failure building the payments summary | **Yes** | +| `BCK.ROUTER.0007` | 429 | Too many concurrent routed requests in flight | **Yes**, after backoff | +| `BCK.ROUTER.0008` | 403 | Legacy API key — create a new one | No | +| `BCK.ROUTER.0009` | 402 | Wallet short on the target network; nothing was signed | No — **stop** | + +**Never widen a Delegation, and never create a second one, to get past a refusal.** The cap is the user's decision, not a runtime obstacle; minting a fresh Delegation to escape an exhausted one defeats the whole mechanism. Report and stop. Only `0006` and `0007` are retryable — everything else is a decision, and retrying it unchanged gives the same answer. Delegations also expire silently, so check `expiresAt` before diagnosing a `0003` as anything else. + ## Full Reference See `skills/nevermined-payments/SKILL.md` for complete integration patterns (Track A = operate autonomously via REST; Track B = add payments to your code via SDK) and its reference files. + +See `skills/nevermined-router/SKILL.md` and its `references/` for the Router half — discovery, mode A vs mode B, the ledger, and every guardrail. From c04a80581bd80eeba0b74d4a7976c528aa08d3d0 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Tue, 11 Aug 2026 16:37:24 +0200 Subject: [PATCH 3/4] docs(skills): lead the Claude Code install with the plugin, and document ClawHub (#2595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The install page told Claude Code users to sparse-checkout git, and never mentioned ClawHub at all — despite a CI job publishing both skills there on every push to skills/**. The registry we pay to publish to was invisible to readers. - Claude Code tab now leads with the plugin; the file copy stays as the pin-a-version fallback. - New ClawHub tab. Notes that --dir is a global flag (it must precede the subcommand) and that the payments skill's slug is 'nevermined', not 'nevermined-payments'. - 'Supported Tools at a Glance' no longer says Router is unavailable on Copilot and Codex, and gains a ClawHub row. - CLAUDE.md records both distribution channels and why source must stay './skills'. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 6 +- development-guide/build-using-nvm-skill.mdx | 76 ++++++++++++++------- 2 files changed, 57 insertions(+), 25 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a8a3dc45..7e52a585 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,8 +43,10 @@ They give AI coding assistants (Claude Code, Cursor, Copilot, Codex, Windsurf, C | `.windsurf/rules/.md` | payments, router (**6,000-char limit per file**) | | `.clinerules/.md` | payments, router | | `.amazonq/rules/.md` | payments, router | -| `.github/copilot-instructions.md` | payments only — single file, no skill segment | -| `AGENTS.md` | payments only — single file, no skill segment | +| `.github/copilot-instructions.md` | payments + a condensed Router section — single file, no per-skill split | +| `AGENTS.md` | payments + a condensed Router section — single file, no per-skill split | + +Both skills are also distributed as **Claude Code plugins** via `.claude-plugin/marketplace.json` at the repo root (`/plugin marketplace add nevermined-io/docs`), and to the **ClawHub** registry by `.github/workflows/publish-skill-clawhub.yml`. The marketplace entries use `source: "./skills"` with an explicit per-plugin `skills` array, so each plugin ships only `skills/` and not the whole 33 MB docs repo — do not change `source` to `"./"`. Validate any edit with `claude plugin validate .` before committing. `.cursor/` is otherwise gitignored; `.gitignore` re-includes `.cursor/rules/` specifically, because those files are published — users `curl` them from `main`, so one that fails to commit becomes a 404 in their editor. Both `development-guide/build-using-nvm-skill.mdx` (the install page) and its "Supported Tools at a Glance" table must be updated when this set changes. diff --git a/development-guide/build-using-nvm-skill.mdx b/development-guide/build-using-nvm-skill.mdx index 7abfc489..aeda5c26 100644 --- a/development-guide/build-using-nvm-skill.mdx +++ b/development-guide/build-using-nvm-skill.mdx @@ -17,11 +17,11 @@ There are two, and which one you want depends on which side of the payment you'r | **`nevermined-payments`** | **receiving** money, or buying a Nevermined plan | SDK integration, middleware, plans, credits — the rest of this page | | **`nevermined-router`** | **spending** money at external services | Discovering services in the catalog, creating a spending Delegation, paying any x402 or MPP endpoint through the [Nevermined Router](/products/router/overview) | -Installing both is fine — they don't overlap. How you install the Router one depends on your tool: +Installing both is fine — they don't overlap. Every supported tool can now get either skill: -- **Claude Code, Cursor, Windsurf, Cline, Amazon Q** — swap `nevermined-payments` for `nevermined-router` in the paths below, or run the extra command shown in each tab. -- **Codex CLI** — its `AGENTS.md` route is a *single* file with no skill name in it, and that file carries the **payments** guidance only. Use the tab's **"install as a Codex skill"** alternative instead: `.agents/skills/` takes a skill directory, so `nevermined-router` works there. -- **GitHub Copilot** — `.github/copilot-instructions.md` is a single file with nothing to swap, and it carries the **payments** guidance only. Until that changes, use the [full skill on GitHub](https://github.com/nevermined-io/docs/tree/main/skills/nevermined-router) or paste it in manually. +- **Claude Code** — install them as plugins, one command each. See the tab below. +- **Cursor, Windsurf, Cline, Amazon Q** — swap `nevermined-payments` for `nevermined-router` in the paths below, or run the extra command shown in each tab. +- **Codex CLI and GitHub Copilot** — `AGENTS.md` and `.github/copilot-instructions.md` are *single* files with no skill name to swap, so each one carries **both** halves: the payments guidance and a condensed Router section. Take the whole file. Codex can also install `nevermined-router` as a proper skill directory under `.agents/skills/` — see its tab. ## What's Included @@ -34,6 +34,13 @@ The skill provides your coding assistant with: - **Client-side** integration — ordering plans, generating tokens, calling protected APIs - **Troubleshooting** for common errors (402, `-32003`, `-32002`) +And, from the Router skill: + +- **Service discovery** in the public Agent Services Catalog +- **Spending Delegations** — creating a capped budget and funding the buyer wallet +- **Paid calls** over x402 and MPP through one endpoint, with the protocol auto-detected +- **Guardrails** — every `BCK.ROUTER.*` code, what's retryable, and why a refusal must not be worked around + ## Install the Skill Choose your AI coding tool below for step-by-step installation instructions. @@ -42,7 +49,20 @@ Choose your AI coding tool below for step-by-step installation instructions. ### Claude Code - **Commands to install** from the Nevermined repository: + Install from the Nevermined plugin marketplace — two commands, and Claude Code keeps the skills up to date for you: + + ```bash + /plugin marketplace add nevermined-io/docs + + /plugin install nevermined-payments@nevermined # charging for your agent + /plugin install nevermined-router@nevermined # buying from external services + ``` + + Install either or both. The marketplace is named `nevermined` (that's the `@nevermined` suffix); `nevermined-io/docs` is just the repository it's served from. + + Claude Code loads each skill when it's relevant to your work, and refreshes it in the background when we publish changes. To update by hand, run `/plugin marketplace update nevermined`. + + **Alternative — copy the files directly.** Use this if you'd rather pin a version, or you're on a Claude Code build without plugin support: ```bash mkdir -p ~/.claude/skills @@ -57,27 +77,32 @@ Choose your AI coding tool below for step-by-step installation instructions. cd - rm -rf "$tmpdir" + ``` + Claude Code discovers skills automatically from `~/.claude/skills/` (personal) and `.claude/skills/` (project). Copied this way they're a snapshot — you re-run the command to update. + + + + ### ClawHub + + Both skills are published to the [ClawHub](https://clawhub.ai) registry under the `nevermined-io` publisher, so any tool that reads a `skills/` directory can pull them with one command: + + ```bash + npx clawhub install nevermined-router # buying through the Router + npx clawhub install nevermined # the payments skill ``` - This downloads the `SKILL.md` and all reference files into your local Claude Code skills directory. Claude Code automatically loads the skill when it's relevant to your work. + This writes to `skills//` in the current directory. `--dir` sets a different target — it's a global flag, so it goes **before** the subcommand: - **Alternative — manual installation:** + ```bash + npx clawhub --dir ~/.claude/skills install nevermined-router + ``` - 1. Clone or download the skill files: - ```bash - git clone https://github.com/nevermined-io/docs.git /tmp/nvm-docs - ``` - 2. Copy to your personal skills directory: - ```bash - cp -r /tmp/nvm-docs/skills/nevermined-payments ~/.claude/skills/ - ``` - 3. Or copy to a project-specific location: - ```bash - cp -r /tmp/nvm-docs/skills/nevermined-payments .claude/skills/ - ``` + No account or login is needed to install. Run `npx clawhub update` to pull the latest published version, and `npx clawhub inspect nevermined-router` to see what you'd get without installing it. - Claude Code discovers skills automatically from `~/.claude/skills/` (personal) and `.claude/skills/` (project). + + ClawHub publishes the payments skill under the slug **`nevermined`**, not `nevermined-payments`. The Router skill's slug matches its name. + @@ -238,13 +263,18 @@ Choose your AI coding tool below for step-by-step installation instructions. | Tool | Config File | Router available? | Auto-Activates | |---|---|---|---| -| **Claude Code** | `~/.claude/skills//SKILL.md` | Yes | Yes — when relevant | +| **Claude Code** | plugin, or `~/.claude/skills//SKILL.md` | Yes | Yes — when relevant | | **Cursor** | `.cursor/rules/.mdc` | Yes | Yes — on `.ts`, `.js`, `.py` files | | **Windsurf** | `.windsurf/rules/.md` | Yes | Yes — model decides | -| **GitHub Copilot** | `.github/copilot-instructions.md` | **No** — single file, payments only | Yes — always | -| **Codex CLI** | `AGENTS.md` or `.agents/skills//` | Yes — via `.agents/skills/`; **not** via `AGENTS.md` (single file, payments only) | Yes — always or when relevant | +| **GitHub Copilot** | `.github/copilot-instructions.md` | Yes — condensed, in the same single file | Yes — always | +| **Codex CLI** | `AGENTS.md` or `.agents/skills//` | Yes — condensed in `AGENTS.md`, in full via `.agents/skills/` | Yes — always or when relevant | | **Cline** | `.clinerules/.md` | Yes | Yes — on `.ts`, `.js`, `.py` files | | **Amazon Q** | `.amazonq/rules/.md` | Yes | Yes — always | +| **Any** (ClawHub) | `skills//SKILL.md` | Yes | Depends on the tool | + + +The Copilot and Codex files are **condensed** — they carry the buy loop, the money traps and every guardrail, but not the full reference set. For the complete Router skill, install it as a directory (Claude Code plugin, ClawHub, or `.agents/skills/`). + ## Example Prompts From ec89768db9d8fba189da457b6a66049f6a3702b1 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Tue, 11 Aug 2026 16:38:47 +0200 Subject: [PATCH 4/4] docs(router): link the agent skill from the Router section (#2595) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Router docs never mentioned the skill. Grepping products/router/ for 'skill' returned exactly one hit — a note pointing at the *internal* demo skill — so the skill linked out to these pages and the pages never linked back. #2595's 'stays in sync with the docs section' criterion was one-way. - overview.mdx: a section with the plugin and ClawHub one-liners, plus which of the two skills to install for which direction. - quickstart.mdx: a tip up top, since the five steps here are exactly what the skill automates. - agent-autonomy.mdx: points at the public skill for readers who want their own agent to do the run, next to the existing internal-demo note. Co-Authored-By: Claude Opus 5 (1M context) --- products/router/agent-autonomy.mdx | 9 +++++++++ products/router/overview.mdx | 23 +++++++++++++++++++++++ products/router/quickstart.mdx | 4 ++++ 3 files changed, 36 insertions(+) diff --git a/products/router/agent-autonomy.mdx b/products/router/agent-autonomy.mdx index fb8466f3..6b585e23 100644 --- a/products/router/agent-autonomy.mdx +++ b/products/router/agent-autonomy.mdx @@ -240,6 +240,15 @@ Before a first run, check the things that most often turn into a "Router bug" th - **Confirm the merchant still answers `402`** on the rail you expect. A service that stops charging is relayed with `paid: false`, and a run can otherwise "succeed" having bought nothing. - **Check the catalog is loaded**, not serving placeholder rows — compare `total` and look at the `targetUrl`s. +If you'd rather have *your* agent do the run than drive it yourself, give it the public **`nevermined-router` skill** — the same six steps plus the guardrails, written for an assistant to act on: + +```bash +/plugin marketplace add nevermined-io/docs # Claude Code +/plugin install nevermined-router@nevermined +``` + +Other tools are covered in [AI Coding Skill](/development-guide/build-using-nvm-skill). The skill teaches the loop; it does not lift the cap, and an agent following it will stop on a refusal exactly as described above. + **Nevermined staff:** a scripted version of exactly this run — the six steps plus a preflight covering every point above — lives in the internal `nvm-monorepo` repository at `.claude/skills/nvm-router-demo/`. It adds `--dry-run` (spends nothing) and `--selfcheck` (offline). It is not public, and nothing on this page depends on it. diff --git a/products/router/overview.mdx b/products/router/overview.mdx index 83c5eb19..1ea91201 100644 --- a/products/router/overview.mdx +++ b/products/router/overview.mdx @@ -75,6 +75,29 @@ Both rails settle **real value on public networks**. The Router is a payment sys +## Let your coding assistant drive it + +Everything on this page is also packaged as an **AI coding skill** — the machine-readable twin of this section, carrying the same facts and the same error codes. Install it once and your assistant knows how to discover a service, create a Delegation, make the paid call, and — just as importantly — when to stop rather than route around a refusal. + + + +```bash Claude Code +/plugin marketplace add nevermined-io/docs +/plugin install nevermined-router@nevermined +``` + +```bash ClawHub +npx clawhub install nevermined-router +``` + + + +Cursor, Windsurf, Cline, Amazon Q, Codex and Copilot are covered too — see [AI Coding Skill](/development-guide/build-using-nvm-skill) for the per-tool instructions, or read [the skill itself](https://github.com/nevermined-io/docs/tree/main/skills/nevermined-router). + + +Install `nevermined-router` when your agent is **spending** at external services. Its sibling, `nevermined-payments`, is for the opposite direction — **receiving** payments and buying Nevermined plans. Installing both is fine; they don't overlap. + + ## Next diff --git a/products/router/quickstart.mdx b/products/router/quickstart.mdx index f16470f1..712a7c56 100644 --- a/products/router/quickstart.mdx +++ b/products/router/quickstart.mdx @@ -8,6 +8,10 @@ By the end of this page your agent will have paid a service that has never heard Everything here is plain HTTP. The Nevermined SDKs don't expose the Router yet, so the examples use `curl` and `fetch` — which is also the point: any agent, in any language, can drive it. + +**Prefer to have your coding assistant do this?** These five steps ship as an AI coding skill. In Claude Code, `/plugin marketplace add nevermined-io/docs` then `/plugin install nevermined-router@nevermined`; elsewhere, see [AI Coding Skill](/development-guide/build-using-nvm-skill). It also carries the guardrails an autonomous buyer must respect, which matter more than the calls themselves. + + Set your environment once: