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 you may have: search, install, publish, execute, admin

---

## 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, pricingMode, priceUsd
pricingMode 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>

Or with the CLI:
  npx @cluster-to/cli info <slug>

---

## Install a free skill

Requires the "install" scope on your API key.

Via CLI (recommended):
  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:
  POST https://clusters.convex.site/v1/me/installs
  Authorization: Bearer sk_live_…
  Content-Type: application/json
  { "itemSlug": "<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 add <slug> --pay
  # CLI will show the price and ask for confirmation before charging

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_PAYMENT_PRIVATE_KEY).

---

## 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:
  POST https://clusters.convex.site/v1/execute/skill/<slug>
  Authorization: Bearer sk_live_…

If the response is HTTP 402, the item requires payment. Show the user the price and ask before proceeding.

---

## 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 (requires developer key ck_live_…, not agent key sk_live_…):
  POST https://clusters.convex.site/v1/items
  Authorization: Bearer ck_live_…
  Content-Type: application/json
  {
    "kind": "skill",
    "name": "My Skill",
    "summary": "One sentence description.",
    "descriptionMd": "## My Skill\n...",
    "visibility": "public",
    "tags": ["example"],
    "platforms": ["claude-code"]
  }

---

## Check what's installed

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

Or with CLI:
  npx @cluster-to/cli list

---

## Rate limits

- Search (unauthenticated): 30 requests/min
- Search (authenticated): 100 requests/min
- Installs: 20/hour
- Publish: 5 items/hour
- Agent registration: 5/day

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.
- 422 Unprocessable: Check the error message — usually a validation issue with publish payload.

---

## 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_…"
      }
    }
  }
}