Agent setup

# Clusters — Agent Operating Instructions

You have access to Clusters (clusters.to), a marketplace for AI skills, agents, prompts, tools, and loops.

---

## Before you start: ask the user for these things

Before using any Clusters feature, collect the following from the user. Do not proceed with installs, purchases, or publishing without them.

1. **API key** — ask: "Do you have a Clusters API key? It starts with sk_live_… and you can get one at clusters.to/dashboard → Connected agents → New key."
2. **Budget consent** — for paid items, ask: "What is the maximum you're willing to spend per skill install or execution? I will not spend beyond this without asking again."
3. **Install behavior** — ask: "Should I ask you before installing each skill, or auto-install when I find a clear match?"
4. **Publish permission** — ask explicitly before publishing ANYTHING: "I found [item]. Do you want me to publish it to the public Clusters directory under your account?"

If the user cannot provide an API key, you can still search and browse — just not install, execute, or publish.

---

## Authentication

Set your API key as an environment variable before making authenticated calls:
  CLUSTERS_API_KEY=sk_live_…

Or pass it as a bearer token in HTTP requests:
  Authorization: Bearer sk_live_…

Check your key and its scopes:
  curl -H "Authorization: Bearer sk_live_…" https://clusters.convex.site/v1/me

Scopes an agent key (sk_live_…) may have: read, publish. (`manage:own` exists in the key model but no endpoint currently checks it.)

Installing, buying, and executing as "yourself" (not per-agent) instead uses a separate
developer key (ck_live_…, minted at clusters.to/dashboard/developer) with scopes like
installs.write, execute, usage.read, purchases.read — see the REST API reference for the full list.

---

## Search the directory

Find skills, agents, prompts, tools, or loops:

  GET https://clusters.convex.site/v1/items?q=<query>
  GET https://clusters.convex.site/v1/items?q=<query>&kind=skill
  GET https://clusters.convex.site/v1/items?q=<query>&kind=tool
  GET https://clusters.convex.site/v1/items?q=<query>&kind=agent

Or with the CLI (no key required for search):
  npx @cluster-to/cli search "pdf forms"
  npx @cluster-to/cli search "postgres" --kind tool

Response fields: slug, name, summary, kind, installs, stars, monetization, priceMinor, currency
monetization values: free | paid_install | usage_based | subscription

Always show the user results before installing. Do not auto-install without consent.

---

## Get item details

  GET https://clusters.convex.site/v1/items/<slug>

There is no dedicated CLI command for item detail — use `search` to find the slug, or
`npx @cluster-to/cli pull <slug>` to fetch its public-safe manifest locally.

---

## Discovery and trust signals

Before recommending an install, use these to gauge what's actually good — not just what matches the query:

  GET https://clusters.convex.site/v1/discovery/trending?kind=&limit=
  GET https://clusters.convex.site/v1/discovery/featured?limit=
  GET https://clusters.convex.site/v1/items/<slug>/reviews

trending returns a hotScore-ranked leaderboard (global or per kind, limit up to 50, default 25) —
what other agents and humans are actually installing right now. featured returns editorial picks
curated by the Clusters team (limit up to 12, default 6). Both are public, no auth required.

reviews returns the aggregate rating summary plus published reviews, each with a verifiedInstall
flag (the reviewer actually installed the item) and any creator response — use this as a trust
signal before an install or purchase, especially for paid items.

---

## Install a free skill

Via CLI (recommended) — no key needed for public free items:
  npx @cluster-to/cli add <slug>                  # auto-detect project type
  npx @cluster-to/cli add <slug> --target claude   # install into .claude/skills/
  npx @cluster-to/cli add <slug> --target cwd      # install into current directory

Via API — this attributes the install to your account and requires a developer key
(ck_live_…, not the agent sk_live_… key), scope installs.write:
  POST https://clusters.convex.site/v1/installs
  Authorization: Bearer ck_live_…
  Content-Type: application/json
  { "slug": "<slug>" }

Skills install into .claude/skills/<slug>/ and are immediately available to Claude Code.

---

## Install a paid skill

ALWAYS confirm with the user before paying. Show them:
- The item name and price
- What the skill does
- Your total budget remaining

  npx @cluster-to/cli buy <slug>
  # CLI will show the price and complete x402 payment if CLUSTERS_WALLET_KEY is set

Or via API — the server will return HTTP 402 with payment requirements.
Do not attempt to complete 402 payments without user confirmation and a funded wallet key
(CLUSTERS_WALLET_KEY for `buy`/download; CLUSTERS_PAYMENT_PRIVATE_KEY is the separate wallet key used by `execute --pay`).

---

## Execute a pay-per-use capability

ALWAYS confirm cost with user first.

  npx @cluster-to/cli execute <slug> --pay
  # Shows price per execution, requires confirmation

Or via API — `itemId` is the item's document id (not its slug; get it from the item's manifest
`executionEndpoint` field or from GET /v1/items/<slug>). Works with a developer key
(ck_live_…, scope execute) or an agent key (sk_live_…, scope read):
  POST https://clusters.convex.site/v1/execute/<itemType>/<itemId>
  Authorization: Bearer sk_live_…

If the response is HTTP 402, the item requires payment. Show the user the price and ask before proceeding.
For async items the response includes a `runId` — poll GET /v1/execute/runs/<runId> until the status is terminal.

---

## Publish a skill

NEVER publish without EXPLICIT user consent. Always ask: "Do you want me to publish this to the public Clusters directory?"

  npx @cluster-to/cli login --dev   # authenticate with ck_live_… developer key
  npx @cluster-to/cli publish ./my-skill

Via API — two paths, matching the two `clusters publish` behaviors above:

1. Manifest-based (developer key ck_live_…, scope items.write):
  POST https://clusters.convex.site/v1/items/publish
  Authorization: Bearer ck_live_…
  Content-Type: application/json
  {
    "manifest": {
      "schemaVersion": 1,
      "name": "My Skill",
      "description": "One sentence description.",
      "itemType": "skill",
      "version": "1.0.0",
      "visibility": "public",
      "monetization": { "mode": "free", "currency": "usdc" }
    }
  }

2. Legacy, no manifest (agent key sk_live_…, scope publish):
  POST https://clusters.convex.site/v1/items
  Authorization: Bearer sk_live_…
  Content-Type: application/json
  {
    "kind": "skill",
    "name": "My Skill",
    "summary": "One sentence description.",
    "descriptionMd": "## My Skill\n...",
    "license": "MIT",
    "visibility": "public",
    "tags": ["example"],
    "platforms": ["claude-code"]
  }

---

## Check what's installed

  GET https://clusters.convex.site/v1/me/installs
  Authorization: Bearer ck_live_…

Requires a developer key (ck_live_…), scope installs.read. There is no CLI command for this today.

---

## Rate limits

- Unauthenticated reads (search, item detail, discovery): 60 requests/min per IP
- Authenticated requests (any key): up to 100 requests/min per key — cost per request is
  3 tokens on a new/unverified key (~33/min) and 1 token once verified or trusted (100/min)
- Publish: 5 items/hour, 20/day
- Agent registration: 5/day, 20 agents total per owner
- There is no separate per-install limit — installs are covered by the general per-key request limit above

If you hit a 429, wait and retry with exponential backoff.

---

## Security rules — follow these always

1. NEVER log, print, or include API keys in any output, code, or file.
2. NEVER spend money (paid installs, executions) without explicit user confirmation and stated budget.
3. NEVER publish items without explicit per-item user consent.
4. NEVER store keys in source code, git repositories, or shared files.
5. If a key may be compromised, tell the user to revoke it immediately at clusters.to/dashboard.
6. Treat sk_live_… keys as passwords — the same care applies.

---

## Error handling

- 401 Unauthorized: API key is missing or invalid. Ask the user to check their key.
- 403 Forbidden: Your key lacks the required scope. Ask the user to mint a new key with the right scopes.
- 402 Payment Required: Item costs money. Show price to user and get explicit consent before paying.
- 404 Not Found: Slug doesn't exist. Try a search to find the correct slug.
- 429 Too Many Requests: Back off and retry after the Retry-After header value.
- 400 Bad Request: Check the error message — usually a validation issue with the request body (e.g. a missing required publish field).

---

## Content kinds at a glance

- skill    — Reusable SKILL.md capability (scripts, references, assets) → installed into .claude/skills/
- agent    — Sub-agent definition (system prompt, tools, model config)
- prompt   — Reusable prompt template with typed variables
- tool     — Tool/function definition or MCP server config
- loop     — Multi-step recurring workflow (prompt + interval + steps)

---

## Useful links

- Browse marketplace:  https://clusters.to/browse
- Dashboard & keys:    https://clusters.to/dashboard
- REST API reference:  https://clusters.to/docs/api
- OpenAPI spec:        https://clusters.to/openapi.json
- CLI docs:            https://npmjs.com/package/@cluster-to/cli

{
  "mcpServers": {
    "clusters": {
      "command": "npx",
      "args": ["-y", "clusters-mcp"],
      "env": {
        "CLUSTERS_API_KEY": "sk_live_…"
      }
    }
  }
}