# 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/setup {"skills":[{"name":"pdf","source_url":"https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md","sha256":""}],"email":"you@example.com","webhook":"https://you.example/hook"} -> coverage report (covered / outdated / unknown), watches every skill; MCP tool backskills_setup (alias register_skills) GET /api/setup/report -> what this key watches, including its private skills (fingerprints only) 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=`. 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 10 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 https://www.backskills.ai), BACKSKILLS_KEY (optional; registers itself if absent) Tools: `suggest_skills`, `backskills_setup` (alias `register_skills`), `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://www.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). ## Skill Check (does your skill still work on each model?) 1. `POST /api/skill-check` with your skill (`skill_id` or `skill_content`) and 3-10 use cases, each `{"prompt": "...", "expected": "what a correct answer must do"}`. 2. You get a grid of cases by models (PASS/FAIL plus the judge's reason), a pass rate per model, suggested edits for failures and the cost of the run. Add `proposed_skill` to see which cases a proposed edit fixes or breaks on each model. 3. Limits: up to 10 cases x 3 models, 4 runs/month and 2/day per key. MCP: `skill_check_run`, `skill_check_results`. ## Skill Health `GET /api/health/{skill_id}` returns freshness, quality (a deterministic lint) and efficacy (our public baseline, labeled "estimated by backskills", built from 3 auto-generated use cases). The badge shows `skill health NN`. Your own author-verified runs are reported separately and never change the public score. None of this affects weaving ranking. ## Suggest: skills installed alongside yours POST /api/suggest with your skills-lock.json (the file `npx skills` writes) as the body, or {"lockfile": {...}}, or {"repo": "owner/name"} for a public GitHub repo. Also accepts {"skill_names": [...]} and repo URLs. Optional: "limit" (1-5, default 3), "prev_run_id" (resubmit an updated lockfile after an earlier run), "email" (opt-in emails about future skills that fit your stack; totally free + no ads for beta signups in November; never shared). Any run with a public repo is re-read once in 7 days to see if a suggestion was added. A repo without skills-lock.json returns "no_lockfile": true and "how_to_add". Signup only: POST /api/suggest/subscribe {"email","run_id"}. Returns {run_id, skills_read, suggestions:[{skill_id, name, source, install, co_install_count, with, lift, score, reason}]}. Ranked only by co-installs across public repos that commit a skills-lock.json: score = count x ln(lift), summed over your skills. Counts are distinct GitHub owners, and near-identical skill lists (Jaccard >= 0.9) count once; skills from packs you already install from are skipped. No popularity ranking, no paid or sponsored placement. MCP tool: suggest_skills. Page: / (also /suggest). The skill monitor home moved to /monitor. curl -s -X POST https://www.backskills.ai/api/suggest -H 'Content-Type: application/json' --data @skills-lock.json Each run is logged with a random run ID and a sha256 of the sorted skill list (not the lockfile). ## Guides - [How to Write a SKILL.md That Agents Actually Pick Up](https://www.backskills.ai/blog/how-to-write-a-skill-md): A SKILL.md is the one required file in an agent skill: YAML frontmatter with a name and a description, followed by Markdown instructions. - [SKILL.md vs AGENTS.md vs CLAUDE.md vs MCP: Which One Do You Need?](https://www.backskills.ai/blog/skill-md-vs-mcp-vs-agents-md): Use a SKILL.md when you want to teach an agent a repeatable task it loads only when relevant. - [How to Track Agent Skill and MCP Server Changes (and Pin Versions)](https://www.backskills.ai/blog/track-skill-changes-and-pin-versions): To stop a third-party skill or MCP server from changing under you, pin it: a SKILL.md to a git commit SHA, an MCP server to an exact package version.