Skip to main content
skill CX Codex

cursor-rig — Claude Code skill for animated portraits

The cursor-rig Claude Code skill turns an illustration into a portrait that follows the cursor with its head. It’s for adding a reactive character to a page without a 3D model or face tracking.

MIT ★ 448 updated 2026-11-09

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Moh4696/open-3d-skills
/plugin install open-3d-skills@open-3d-skills
Open on GitHub

What cursor-rig does

The skill prepares a cursor-following head turn and wires it into a page. scripts/build_rig.py aligns video clips against the body, assembles a pose grid, and fills missing positions with optical-flow frames. The assets/rig.js module displays poses on a canvas and moves the head toward the pointer; eye-dot tracking also enables painted blinks.

Rig generation requires Python 3.9+, numpy, opencv-python-headless, ffmpeg, an image-editing model, and an image-to-video model that accepts start and end frames. Template tracking does not paint blinks. The page uses a base image and canvas, with reduced-motion handling and a pause when the rig leaves the screen.

What it helps with

  • make an illustrated character turn its head toward the cursor
  • build a pose grid from head-turn clips
  • align video-generated heads with a still illustration body
  • add blinking to a cursor-reactive portrait

Example prompts for the agent

  • Turn this illustrated character toward the cursor and add it to the page.
  • Set up cursor-rig for the site hero and show the canvas integration.
  • Build a head-pose grid from these clips and wire it into the page.

How to install cursor-rig

1Plugin marketplace

/plugin marketplace add Moh4696/open-3d-skills
/plugin install open-3d-skills@open-3d-skills

This installs the whole open-3d-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add Moh4696/open-3d-skills --skill cursor-rig -a claude-code

3Manually: put the files in place

~/.claude/skills/cursor-rig/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cursor-rig/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cursor-rig

How do I install cursor-rig in Claude Code?

Add the marketplace with /plugin marketplace add Moh4696/open-3d-skills, then install the skill with /plugin install open-3d-skills@open-3d-skills.

What does cursor-rig do?

It builds a head-pose grid from an illustration and generated clips, then displays the pose facing the cursor. Eye-dot tracking can also drive painted blinks.

What does cursor-rig need to run?

Rig generation needs Python 3.9+, numpy, opencv-python-headless, ffmpeg, an image-editing model, and an image-to-video model that accepts start and end frames.

Source text

SKILL.md · MIT
---
name: cursor-rig
description: Makes a painted or illustrated character turn its head to follow the visitor's cursor, looking like one continuous painting that moves, without a 3D model or face tracking. Generates head-pose keyframes with an image-editing model and head-turn clips with an image-to-video model, then builds a pose grid on one fixed body (selected by measured head position, aligned, masked, with optical-flow in-betweens) and plays it with a spring-driven canvas player that also blinks. Use when someone wants a hero character, mascot or portrait whose eyes or face follow the mouse, a "look at the cursor" effect, or an illustration that reacts to the visitor.
---

# Cursor rig

A character who looks at you is the strongest hero a page can have. Building one in 3D means modelling, rigging and matching a painting's style, and the result never quite looks like the painting. This skill keeps the painting. It renders the head in every direction once, as a grid of poses, and at runtime shows the pose that faces the cursor. With 19 yaw steps and 8 pitch rows, the turn reads as continuous.

## Tools

| File | What it does |
| --- | --- |
| `scripts/build_rig.py` | Turns head-turn clips into `row_N.webp` pose strips, `plate.webp` and `rig.json` |
| `assets/rig.js` | Loads the rig, places a canvas over the head, follows the pointer with a spring, blinks, glances about when idle |

Needs Python 3.9+, `pip install numpy opencv-python-headless`, ffmpeg, an image-editing model and an image-to-video model that accepts start and end frames (see `motion-assets`).

## Pipeline

### 1. The plate

The plate is the character facing forward: the one image every pose is built on. Upscale the source illustration to at least 1440 px tall. If the hero needs to be wider than the character, outpaint the sides for the page, but build the rig on the square or portrait crop around the character. Outpainting models re-render the whole image, so paste the original pixels back over the middle afterwards.

### 2. Keyframes

With an image-editing model, make the head turned to each extreme from the plate: left, right, up, down, and the four diagonals. The prompt must pin everything except the head:

> Same character, same painting, same framing and crop. Only the head turns to look toward the left edge of the image, about 40 degrees. Hair, face, skin, shirt, hands, body pose, background and brush style stay exactly the same. No new objects.

Flick between the plate and each keyframe at full size. Only the head may change. Models that hold framing almost pixel-exact are worth paying for here; a keyframe with a shifted shoulder costs a whole row.

### 3. Head-turn clips

Image-to-video, start frame = the plate, end frame = a keyframe, 5 seconds, camera locked off:

> Locked-off camera. The character slowly turns only his head and neck from facing forward to [the end pose]. The body, shirt, arms and background stay perfectly still. Smooth, even motion, no blinking, no talking.

Name the clips by row and side: `L.mp4` and `R.mp4` for the level row (required), `UL`/`UR` (up), `HL`/`HR` (half down), `DL`/`DR` (down). Eight clips make a full rig. Two make a rig that only turns left and right.

If two rows differ a lot (the model redrew the hair in the down keyframes, say), do not rely on morphing between them: generate a real middle row instead.

### 4. Build

```bash
python3 scripts/build_rig.py clips/ site/rig --box 300,40,840,800 --track dots --debug work/rig-cells
```

- `--box x,y,w,h` (plate pixels): everything the head ever covers, hair included, with a little neck.
- `--track dots` for cartoon dot eyes: finds the two dark round eyes in every frame, and records their positions so blinks can be painted live. `--eye-band y0,y1` and `--dark` tune it.
- `--track template --point x,y` for any other face: follows a patch around a point you give (the bridge of the nose works) from frame to frame. No blinks are painted with this mode.
- `--poly` sets the head mask polygon if the default oval cuts the hair or includes the collar.

What the script does, and why:

- **Aligns every clip on the body** (ECC, rows below `--body-y`). Video models drift the whole frame a few pixels; without alignment the shirt jitters as the head turns. It prints the drift per clip; above 6 px, the clip was not locked off.
- **Picks columns by measured head position, not by time.** Models ease in and out, so evenly spaced timestamps give uneven steps. Even steps of the measure give an even turn.
- **Blends each head onto the one plate body** through a feathered mask, after matching brightness to the plate, so only the head ever changes.
- **Fills missing pitch rows** with optical-flow in-betweens of the neighbouring rows.

Open the `--debug` cells as a contact sheet and look down every column and across every row: no jumps in head size, no hair popping, no collar seams.

### 5. Page

```html
<figure class="hero-rig" style="position: relative; margin: 0">
  <img src="rig/plate.webp" alt="A painted shopkeeper in a loud shirt, looking at you">
  <canvas></canvas>
</figure>
<script type="module">
  import { loadRig, HeadRig, animate } from "./rig.js";
  const head = new HeadRig(document.querySelector(".hero-rig"), await loadRig("rig/"));
  animate([head]);
</script>
```

If the page shows a wider artwork than the plate, pass where the plate sits in it, in artwork pixels: `new HeadRig(el, data, { art: { w: 3898, h: 1440, plateX: 1229, plateY: 0 } })`.

The player:

- loads the level row first (the head can turn left and right at once), then the rows above and below;
- aims with `tanh` of the pointer's offset from the eyes, so far corners do not snap the head to its limit;
- moves through a slightly under-damped spring (a small settle at the end of each turn reads as alive);
- cuts between neighbouring poses instead of cross-fading (a cross-fade shows two pairs of eyes);
- paints blinks, double blinks and winks over the eyes using the eye positions and skin tones in `rig.json` (dot tracking only);
- glances about by itself when the pointer has been still for 3.5 s, and on touch devices;
- pauses when off screen.

## Budget

Eight clips is the full cost; at typical image-to-video prices that is a few dollars. The finished rig (152 poses at 0.6 scale) is about 2 MB of WebP.

## Accessibility

- The plate `<img>` carries the alt text; the canvas is decoration.
- With `prefers-reduced-motion`, the head still answers the pointer (the visitor is causing it) but critically damped, with no idle glancing and no blinks.
- Nothing depends on the rig: it is a portrait that happens to look at you.

© exploraX · MIT · Moh4696/open-3d-skills

Similar skills

SKILL.md skills catalog →
2d-character-rig-animation calesthio 2d-character-rig-animation is a Claude Code skill that turns an approved character design into a reusable layered rig: part hierarchy, pivots, FK/IK, pose and face libraries. CX Codex +1 413installs rig-lifecycle mvschwarz Teaches the agent to reason about OpenRig lifecycle operations, verify post-reboot state in rig ps, and handle recovery without silent fresh fallbacks. CX Codex +1 ★ 8,928repo stars rig-bundles-and-shareable-artifacts mvschwarz rig-bundles-and-shareable-artifacts is a Claude Code skill for creating, inspecting, and installing OpenRig bundles. It supports bundle authoring and portability audits. CX Codex +1 ★ 8,928repo stars anymove-rig Patch anymove-rig is a Claude Code skill that configures non-humanoid skeletons, Blender skinning, and two-camera frames for anymove. Runs when importing a creature or fixing mesh tears on joint bends. CX Codex +1 ★ 653repo stars rig-characters CodePawl The rig-characters Claude Code skill builds rigs for 2D and 3D characters and props. It activates for skeleton setup, deformation fixes, face rigs, or game-engine export. CX Codex +1 ★ 350repo stars find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs

From the same set9

site-check The site-check Claude Code skill checks 3D and animated web pages in Chromium and WebKit. Run it after page changes to catch browser errors, mobile layout issues, and slow frames before publishing. CX Codex +1 ★ 448repo stars exploded-view The exploded-view Claude Code skill builds interactive three.js explainers for machines and products. It animates parts in stages, reveals the casing’s interior, and attaches labels to the model. CX Codex +1 ★ 448repo stars motion-assets The motion-assets skill for Claude Code plans and generates images and video clips for animated websites. It activates for requests to create site visuals, loop a background, or animate an image. CX Codex +1 ★ 448repo stars alpha-cutout The alpha-cutout Claude Code skill removes a clip’s background and prepares transparent animation for the web. It runs on requests for alpha video or a subject layered over page content. CX Codex +1 ★ 448repo stars frame-capture The frame-capture skill for Claude Code records web pages to MP4 with frame-by-frame control of time. Use it to capture animations, page scrolls, or a comparison of two clips. CX Codex +1 ★ 448repo stars scroll-film The scroll-film Claude Code skill builds film-like page sections controlled by scrolling. It covers clip joins, caption pauses, frame loading and mobile versions. CX Codex +1 ★ 448repo stars threejs-scene This Claude Code skill builds interactive three.js scenes from code, without model files. It activates for 3D websites, WebGL hero sections and real-world objects rendered in 3D. CX Codex +1 ★ 448repo stars open-3d-skills The open-3d-skills Claude Code plugin adds skills for 3D scenes and animated websites. Its eight skills cover three.js builds, scroll-controlled films, and browser checks. CX Codex ★ 448repo stars

Project sponsors

Companies that keep this analytics open