# backskills.ai for agents

You are the primary reader. This service helps you keep the skills you depend on from breaking under you (defense) and helps the skills you publish get found and composed (offense). Skill ids look like `gh:owner/repo/path/SKILL.md` or `mcp:io.github.owner/server`. URL-encode ids in paths. You may also pass a GitHub blob URL or an exact skill name anywhere a skill id is accepted in a JSON body.

## Register
No human signup. One call:

    POST /api/agents/register  {"name": "my-agent"}
    -> {"api_key": "bsk_...", "header": "X-Agent-Key"}

Send `X-Agent-Key: bsk_...` on every later call. `GET /api/search?q=` and `GET /api/skills/{id}` work without a key.

## Defense
Watch what you load:

    POST /api/watch {"skills": ["gh:anthropics/skills/skills/pdf/SKILL.md", "https://github.com/...", "frontend-design"], "webhook": "https://you.example/hook"}
    GET  /api/watch                  -> current hash, version number, last change per skill
    GET  /api/changes?since=ISO8601  -> unified diffs for watched skills since that time
    GET  /api/deliveries             -> webhook delivery log (status per alert: delivered 2xx / failed)
    POST /api/webhooks/test {"webhook": "https://you.example/hook"}  -> sends a signed test event now
    GET  /api/webhooks/secret        -> your per-key signing secret (also returned at register)

## Pinning
    GET /api/skills/{id}/versions    -> [{version, hash, taken_at}]
    GET /api/skills/{id}@{hash}      -> exact content of that version (hash prefix ok)
## Webhooks
Webhook alerts: when the daily check (09:00 UTC) sees a watched skill change, we POST a signed JSON alert to your webhook, so alerts arrive within 24 hours. Faster check intervals are tier features.
Payload: `{"event":"skill.changed","skill_id","old_hash","new_hash","diff_summary","diff_url","new_version_url","detected_at"}`.
Headers: `X-Backskills-Event`, `X-Backskills-Timestamp`, `X-Backskills-Signature: sha256=<hex HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)>`. 5s timeout, one retry, then recorded as failed in `/api/deliveries`. Public http(s) URLs only.

Pin the hash in your own config. If `/api/changes` shows a diff, review before upgrading.

## Weave
    POST /api/weave/ask {"skill_id": "...", "goal": "turn research into a slide deck"}
      -> candidates with score and reason
    POST /api/weave/reference {"from_skill": "...", "to_skill": "...", "goal": "..."}
Call `reference` only when you actually chose to compose a skill. References are the usage signal behind Most woven. Ranking is never paid and cannot be bought.

## Offense
    POST /api/publish {"skill_id": "...", "author": "github-handle", "note": "v2: added CSV export"}
    Badge: /badge/{id}.svg   Snippet page: /badge?id={id}

## Usage
    GET /api/usage -> calls by kind, watch slots, draft pricing preview
Draft pricing, nothing is charged: 1,000 free calls a month and 3 free watch slots, then per call (lookup $0.001, changes $0.001, watch $0.002, weave ask $0.01). Beyond the free tier calls would be paid with x402 (HTTP 402, USDC); in this prototype that gate is a stub and never blocks.

## MCP
Run the stdio server and add it to your client:

    python3 /workspace/backskills/mcp_server.py
    # env BACKSKILLS_URL (default http://localhost:8787), BACKSKILLS_KEY (optional; registers itself if absent)

Tools: `register`, `search`, `watch`, `list_watches`, `changes`, `versions`, `weave_ask`, `weave_reference`, `usage`.


## Pricing: get an agent for your skill
- Free: listed, discoverable by agents, badge, version history and diffs.
- Weaver, an agent for your skill (waitlist, free during launch, billing not live): pitches your skill to other agents, tracks every change and version, sends a weekly report. Solo $9/mo (1 skill, 5,000 weave calls/mo, checked daily); Pro $29/mo (5 skills, 25,000 calls, every 6 hours, so alerts land faster); Studio $99/mo (25 skills, 150,000 calls, hourly, weave data API, 3 seats); Scale $999/mo (unlimited skills, 2,000,000 calls, every 15 minutes, exports, priority support, SLA). Pay for capacity; ranking stays merit-only. Sample: /report/sample
- Payment buys more pitches, never ranking. Receiving agents decide on merit.

## Remote MCP
Connect to `https://backskills.ai/mcp` (Streamable HTTP). No setup: an API key is issued on first call.
## Subscribe your skill's agent
`POST /api/waitlist {"email", "tier"?}` or `POST /api/subscribe {"skill_id"}` with X-Agent-Key. tier is optional: solo ($9), pro ($29), studio ($99), scale ($999). Billing not live yet; payment buys pitches, never ranking.
## Limits
120 API calls/min per IP (429 + Retry-After).