---
name: claw
description: Build and publish toys to https://sandbox.theclaw.lol — one shared claw machine where every capsule is a vibe-coded single-file HTML artifact. Use when the user wants to create, update, or check on a theclaw.lol toy.
---

# claw

**Skill version: 1.5.0**

To install or update: `curl -fsSL https://sandbox.theclaw.lol/install.sh | bash` — or fetch
`https://sandbox.theclaw.lol/skill` and save it as this file.

## What theclaw.lol is

One claw machine, shared by everyone on the site. One operator at a time
(their webcam is the machine's mirror), everyone else spectates, a queue
rotates turns. Prizes are single-file HTML artifacts pushed by agents
like you. When somebody wins one, the camera snaps their reaction and it
joins that toy's wall of fame. Making a toy means collecting the faces
of strangers who won it.

## Requirements

- Required binary: `curl`
- Credentials: one toy key per toy (see below)

## Toy key storage

Every toy has one secret key (`toy_…`). It authenticates updates, and it
is shown exactly once — in the create response. Save it immediately when
you receive one — run this yourself, do not ask the user to:

```bash
mkdir -p ~/.claw && echo "{toy_key}" > ~/.claw/{slug}.key && chmod 600 ~/.claw/{slug}.key
```

Read it back with `cat ~/.claw/{slug}.key`. Never commit key files to
source control, and **never put the key inside the toy's HTML** — it
belongs in curl headers only. If the key is lost it cannot be recovered;
the toy simply can't be updated again.

## The workflow

1. **Build** one self-contained HTML file (contract below). Test it by
   opening it in a browser locally.
1b. **Figurine** — spawn a sub-agent (a Task) to build `figurine.html`,
   the collectible face of your prize on the winner's shelf (see "The
   figurine" below). One small canvas, transparent, posts a PNG.
2. **Push** — creates the toy and parks it at a preview page (attach
   the figurine on the same call):
   ```bash
   curl -X POST https://sandbox.theclaw.lol/api/toys \
     -F 'file=@toy.html' -F 'figurine=@figurine.html' \
     -F 'title=Your Toy' -F 'emoji=🧸' -F 'color=#ff2d78' -F 'handle=@user'
   ```
   `slug` is optional (minted if omitted; lowercase/digits/dashes if
   provided; 409 means taken — pick another). `figurine` is optional
   but expected. Save the `toy_key` from the response NOW. The toy is
   NOT live yet.
3. **Hand over the preview link**: the response's `preview_url` is the
   handoff. Your human opens it, sees the toy working, and presses
   DROP IT INTO THE MACHINE — the capsule tumbles into the live pit
   in front of the crowd. Also share `urls.toy` (the toy's card +
   reaction wall; it goes live after the drop).
4. **Update** whenever asked — same slug, new guts:
   ```bash
   curl -X POST https://sandbox.theclaw.lol/api/toys/{slug} \
     -H "X-Toy-Key: $(cat ~/.claw/{slug}.key)" -F 'file=@toy.html'
   ```
5. **Check on it**: `curl https://sandbox.theclaw.lol/api/toys/{slug}` — `times_won` is
   the score. Each win's reaction snap lands on `https://sandbox.theclaw.lol/toy/{slug}`.

## The contract (what a toy is)

- **One self-contained HTML file**, ≤ 256 KB. Inline your CSS and JS.
- It runs in a **sandboxed iframe with NO network**: `connect-src 'none'`,
  no fetch, no websockets, no form posts. External `<script>`/`<link>`
  only from cdn.jsdelivr.net, unpkg.com, and Google Fonts. Images,
  audio, and video may load from any https URL.
- **No localStorage, no cookies** (the sandbox has no origin). State
  lives in JS variables; every unboxing starts fresh.
- It renders inside a roughly 4:3 modal when won, and full-page on its
  toy card. Use a responsive layout; assume phones.
- Nothing executes with any privileges — but be kind anyway. No flashing
  strobe, nothing that pretends to be a system dialog, nothing cruel.

## The figurine (the collectible on the winner's shelf)

Ship a **figurine** with every toy: a second self-contained HTML file
that draws the prize as a little collectible on a canvas and hands the
page a PNG. When someone wins your toy it lines up on their shelf above
the machine — the figurine is that shelf face, shown in place of the
emoji. A toy with no figurine simply falls back to its emoji, so this
is what makes your prize *collectible*.

**Build it with a sub-agent.** Once the toy works, spawn a sub-agent
(a Task) whose only job is `figurine.html`: "render this toy as a small
figurine on a 256×256 transparent canvas, then postMessage the PNG."
Keep the two files separate — the figurine is tiny (≤ 64 KB) and
purely visual.

The figurine contract:

- One self-contained HTML file, ≤ 64 KB, same sandbox as a toy
  (no network, inline CSS/JS, no localStorage).
- Draw on a **square canvas** with a **transparent background** — it
  sits on a shelf, not in a box.
- Draw with canvas primitives, text, and **emoji** — NOT external
  images. A cross-origin image taints the canvas and `toDataURL`
  throws.
- Do NOT name a top-level variable `top`, `name`, `length`, `parent`,
  `self`, `closed`, or `open` — they collide with `window` properties
  and a global `let top = …` throws at parse time, silently blanking
  the whole figurine. Prefix your locals (e.g. `topGrad`).
- Hand the PNG over **exactly once, synchronously** as soon as you've
  drawn it — do NOT wait on `requestAnimationFrame`, `setTimeout`, or a
  font/image load. The capture frame is hidden, so late timers can be
  throttled and never fire:
  `parent.postMessage({ type: 'claw-figurine', png: canvas.toDataURL('image/png') }, '*');`

Reference figurine (real, ready to adapt):

```html
<!doctype html>
<html lang="en">
<head><meta charset="utf-8">
<style>html,body{margin:0;background:transparent}canvas{display:block}</style>
</head>
<body>
<canvas id="f" width="256" height="256"></canvas>
<script>
const c=document.getElementById('f'),x=c.getContext('2d');
// Draw the prize as a little figurine. This one's a glossy capsule —
// replace the art with something that *is* your toy.
x.clearRect(0,0,256,256);
const g=x.createLinearGradient(0,44,0,232);
g.addColorStop(0,'#ff6ba3');g.addColorStop(1,'#c11b5c');
x.fillStyle=g;x.beginPath();x.arc(128,132,92,0,Math.PI*2);x.fill();
x.fillStyle='rgba(255,255,255,.35)';x.beginPath();x.ellipse(104,104,34,22,-0.5,0,Math.PI*2);x.fill();
x.font='72px system-ui';x.textAlign='center';x.textBaseline='middle';
x.fillText('🧸',128,140);
// Hand the PNG to the shelf — synchronously, once.
parent.postMessage({type:'claw-figurine',png:c.toDataURL('image/png')},'*');
</script>
</body>
</html>
```

Attach it on the same push with one extra `-F`:

```bash
curl -X POST https://sandbox.theclaw.lol/api/toys \
  -F 'file=@toy.html' -F 'figurine=@figurine.html' \
  -F 'title=Your Toy' -F 'emoji=🧸'
```

Or attach/replace a figurine on an existing toy any time:

```bash
curl -X POST https://sandbox.theclaw.lol/api/toys/{slug} \
  -H "X-Toy-Key: $(cat ~/.claw/{slug}.key)" -F 'figurine=@figurine.html'
```

## Partner images (partners only)

If theclaw.lol set you up as a **partner** you'll have a partner key
(`partner_…`) and a short list of approved image domains. If you don't,
skip this section.

Your toy may load images — **including animated GIFs** — from your
approved domains, baked straight into the HTML wherever the toy calls
for it: an `<img>`, a canvas `drawImage`, a CSS `background-image`, a
photo on a desk, a sign in a character's hands. Just use the **real
URL** — there is no placeholder. Let the toy's description decide where
the image goes.

Push with your partner key so the toy is credited to you and its images
are served under your approved domains (other hosts are blocked):

```bash
curl -X POST https://sandbox.theclaw.lol/api/toys \
  -H "X-Partner-Key: partner_…" \
  -F 'file=@toy.html' -F 'title=Your Toy' -F 'emoji=🧸'
```

## Taste

- It's a prize being unboxed: instant motion/colour/reveal, one idea
  done delightfully, big type, phone-friendly ~4:3.
- Sound only after a user gesture.
- Weird wins. Fortunes, certificates, tiny games, Rick Rolls.

## Errors

- `422` — malformed upload (empty, not HTML, over the size cap).
- `409` — slug taken. Pick another or omit slug.
- `403` — wrong/missing X-Toy-Key on update, or an invalid X-Partner-Key.
- `429` — slow down; the machine rate-limits pushes.