Toonkit

View saved version →

---
name: 3dref
description: Create or edit ToonKit 3D camera/action previz when explicitly requested or selected for a production stage. Uses live MCP features and visible browser Export; deterministic and credit-free.
metadata:
  short-description: Camera/action previz with efficient staging and export
hooks:
  PreToolUse:
    - matcher: "mcp__.*toonkit.*__toonkit_(create_canvas|get_canvas|get_canvas_mutation|canvas_group_nodes|canvas_reference3d_(catalog|create|edit|get_scene))"
      hooks:
        - type: command
          timeout: 30
          command: >-
            i=$(cat); d="${TOONKIT_3DREF_SPOOL:-$HOME/.cache/toonkit-3dref/spool}";
            case "$i" in *'"3dref-spool:'*) ;; *) set -- "$d"/*.pending; [ -e "$1" ] || exit 0;; esac;
            for p in python3 python; do if "$p" -c 'import sys; sys.exit(sys.version_info < (3, 8))' >/dev/null 2>&1; then
            printf '%s' "$i" | "$p" "${CLAUDE_PLUGIN_ROOT}/skills/3dref/scripts/spool_hook.py"; exit 0; fi; done; exit 0
  PostToolUse:
    - matcher: "mcp__.*toonkit.*__toonkit_(create_canvas|get_canvas|get_canvas_mutation|canvas_group_nodes|canvas_reference3d_(catalog|create|edit|get_scene))"
      hooks:
        - type: command
          timeout: 30
          command: >-
            i=$(cat); d="${TOONKIT_3DREF_SPOOL:-$HOME/.cache/toonkit-3dref/spool}";
            case "$i" in *'"3dref-spool:'*) ;; *) set -- "$d"/*.pending; [ -e "$1" ] || exit 0;; esac;
            for p in python3 python; do if "$p" -c 'import sys; sys.exit(sys.version_info < (3, 8))' >/dev/null 2>&1; then
            printf '%s' "$i" | "$p" "${CLAUDE_PLUGIN_ROOT}/skills/3dref/scripts/spool_hook.py"; exit 0; fi; done; exit 0
  PostToolUseFailure:
    - matcher: "mcp__.*toonkit.*__toonkit_(create_canvas|get_canvas|get_canvas_mutation|canvas_group_nodes|canvas_reference3d_(catalog|create|edit|get_scene))"
      hooks:
        - type: command
          timeout: 30
          command: >-
            i=$(cat); d="${TOONKIT_3DREF_SPOOL:-$HOME/.cache/toonkit-3dref/spool}";
            case "$i" in *'"3dref-spool:'*) ;; *) set -- "$d"/*.pending; [ -e "$1" ] || exit 0;; esac;
            for p in python3 python; do if "$p" -c 'import sys; sys.exit(sys.version_info < (3, 8))' >/dev/null 2>&1; then
            printf '%s' "$i" | "$p" "${CLAUDE_PLUGIN_ROOT}/skills/3dref/scripts/spool_hook.py"; exit 0; fi; done; exit 0
---

# 3D reference previz

Deliver an editable ToonKit scene and its playable source-linked video. Preserve requested duration, FPS, actors and camera intent. A location sheet supplies spatial relationships: build only surfaces, silhouettes and obstacles needed by the shot, using simple proxies. Do not recreate panorama detail.

## Choose the smallest suitable route

- **Native MCP:** simple continuous presets, a few root/camera keys, existing-scene edits, other catalog geometry/animals or existing uploaded assets. Read [native execution](references/native.md). No Node/three/FBX setup for this route. The live catalog defines available ToonKit features; the compiler's limits do not disable them.
- **Compiled choreography:** multi-actor trajectories with measured contact, wall-as-floor roll, composed body motion or shared root/body slow motion. Read [production input](references/production-input.md) and [execution](references/execution.md). Read [source motion](references/body-motion.md) only for composed/retimed actions. Python/Node calculate the frames, binds and checks; do not handwrite dense arrays or replace a failed measured constraint with fabricated evidence.
- No AI catalogs, balance, quotes or generation SSOT for either deterministic route. Generation remains a separately authorized stage.

## Compiled route

1. Read [conventions](references/conventions.md) and `references/examples/` first; do not study `scripts/` source (loading the launcher as [execution](references/execution.md) describes is expected). Write one compact `3dref-production-v2` spec from the user's references. Plan actors/camera first, then shot-relevant proxies and real support faces. Actor count is bounded by live capacity, not fixed at two.
2. Compile in a fresh run directory. The package converts center/size to actual primitive pivots, bakes each distinct motion once, solves the wall-floor roll sign, culls irrelevant geometry, reduces keys and checks emitted interpolation. Fix concrete planning failures locally before writing: read only `<run>/diagnostic.json`, edit the spec, recompile (seconds). Default hold observations are advisory; explicit requested limits are enforced.
3. Use the packaged runtime or [portable relay](references/direct.md), both over the same bridge. On Claude Code the relay parks MCP payloads through this skill's hook (`--spool`); never retype requests or responses. Skill hooks apply only to the main conversation, so run the relay there, not in a subagent. Keep the exact editor visible. Apply all base keys before pose overlays; wait for accepted pending work before new revisions.
4. Compare exposed saved fields with the bundle. Check timing in the visible editor when safe readback omits it. Verify a fresh scene before Export. Never Save stale initial UI data over verified work.
5. Export through the visible editor. Record whether a click actually occurred; readiness failure with confirmed no click may resume. Uncertain clicks must be reconciled with existing output before another attempt. Confirm the new source edge, exact output node and decoded duration/dimensions.

## Scope and invariants

The compiler currently calibrates boxes, fresh unit-scale stock humans, one camera and the documented source motions. Other live MCP features use the native route with appropriately scoped checks; do not silently substitute the compiler's subset for the user's request. Existing compiled runs use their original matching runtime.

`engine-profile.json` records calibrated geometry/interpolation and maintenance evidence. Web JS filenames are not execution requirements: ordinary frontend rebuilds or lazy loading must not stop production. Live catalog/scene incompatibility or a changed source FBX needed for baking requires concrete inspection of that operation. Do not reverse-engineer the website on every request.

All compiled actor frames need real finite support, a declared transfer, or bounded intended flight. Root/body share a time map for slow motion; root height is applied once. Walls-as-floor require projected outward normal screen-up. Bone markers and stride comparisons are approximations, not skin/sole IK or artistic certification.

Scene/canvas edits use MCP; browser work is editor/navigation, readiness, Save/Export and resulting media. No hidden app stores/private endpoints or substitute renderer. Preserve existing user work. Do not lower FPS, shorten or split the shot, spend generation credits, or waive a failed measured constraint just to reach Export.

No prior project, local test log or conversation is required. Compiled runs retain `spec.json`, `compiled.json`, `journal.jsonl`; failed plans retain diagnostics. Load helpers once and emit summaries, not arrays. Native runs retain only the plan/receipts needed for recovery. Development tests run at release time, not on user requests.

Keep the result visible and group this run's source/output once. Return the canvas link, actual duration/dimensions, scene FPS and concise verified/unverified scope. Export success does not establish visual acceptance or R2V compatibility. No routine screenshot/contact-sheet or repeated playback loops.

For underspecified staging read [direction](references/direction.md); for a failed constraint or release maintenance read [verification](references/preflight.md). Read the [MCP contract](references/mcp-contract.md) for operations outside the compiler or changed connected declarations.

Referenced files: 35 — file references are metadata, not package contents.

View saved version →

---
name: toonkit-motion-mv
description: 2D anime motion-graphics video production with ToonKit — kinetic typography and shapes composited with ToonKit-generated 2D anime characters, rendered locally with HyperFrames + GSAP. Use only when this skill is invoked explicitly, when the user explicitly asks for a 2D anime motion-graphics video made with ToonKit, or when toonkit-project-manager hands over a 2D anime motion-graphics video request. Not for ordinary image, clip or voice generation (toonkit-project-manager).
metadata:
  short-description: 2D anime motion-graphics videos with ToonKit characters
---

# ToonKit Motion-MV

Produce a finished MP4 in which **typography and shapes lead** and a ToonKit character performs inside them. Norms: [spec](references/MOTION-MV-SPEC.md). Prompts: [PROMPTS](references/PROMPTS.md). Composition contract, `shots.json` schema and tool commands: [COMPOSITION](references/COMPOSITION.md). Read the spec once per run, before planning.

**Paid generation** follows the co-distributed [AI production workflow](../toonkit-project-manager/references/ai-production.md) and [generation SSOT](../toonkit-project-manager/TOONKIT-GENERATION-SSOT.md): live catalog entries, live quotes, one plan report, confirmation of unauthorized spend, idempotency and recovery. This skill decides *what* to generate; those documents govern *how* it is bought.

## Hard rules

1. **Every character reference image is generated on a flat chroma background** (sheets, pose stills, any character asset used as a reference). Default `#00FF00`; magenta if the design contains green. A style-locked canonical image that ignores chroma is used only as the style reference for chroma sheets.
2. **Fast or impact beats are pose cuts. Smooth continuous acting is a video plate.** A fast action on a plate needs a measured smear cover or a split.
3. **Plates use the 2D cel-anime Seedance variant** with the anti-smear block from PROMPTS, for cel-styled characters. Another model only on explicit user instruction.
4. **No 1080p generation by default.** 720p plates (optional 480p preview). 1080p only if the user insists after being told that smear is drawn by the model and resolution does not remove it.
5. **Motion tokens only**: `enter` / `move` / `exit`, plus one `slam` accent per beat.
6. **Sync is measured**: lyric lines are snapped to vocal onsets and beats; MG events bind to analyzed plate frames or pose-cut times, never to prompted seconds.
7. **Composite at ≥ 1920×1080**; plates and poses scale into it.

## Prerequisites (check before planning spend)

Run `node scripts/mvkit.mjs doctor`. It needs Node 20+ and ffmpeg/ffprobe with libvpx-vp9. HyperFrames rendering needs Node 22+ and runs through `npx` inside the scaffolded project; the first scaffold needs network access for npm. If a requirement is missing, report it and stop before any paid call.

## Workflow

### 1. Brief
Decompose into goal, fixed requirements, delegated choices, and inspection/cost scope (AI-production §1). MV specifics:
- music (file and cut length), duration, aspect
- character count and designs, art style
- asset caps (images, video seconds)
- **all on-screen copy** (lyrics, titles, logo text). Copy is the user's; propose it only when delegated.

Screen content risk before spending (real people; existing character IP by name or reference; commercial music — warn that publishing may trigger copyright claims).

### 2. Music map and shot data (free)
1. `mvkit scaffold` the project. Put the trimmed audio in `audio/`.
2. **Beat grid**: `npx hyperframes beats` (gives the BPM), then `mvkit grid <audio> --bpm N --bars` (gives phase and per-bar structure).
3. **Lyrics**: `npx hyperframes init <tmp> -a <audio> --language <lang>` produces a whisper transcript. Read it with `mvkit transcript`. Map the user's lines to it, then `mvkit snap --audio <audio>` snaps them to vocal onsets and beats. Regularize lines to the phrase grid (lines usually start every 4 or 8 beats) where the transcript is uncertain.
4. Write **`shots.json`** (COMPOSITION §6) with spec §3 shot types. Choose pose cut vs plate per beat with spec §1; every text event names its kinetic primitive. Run `node scripts/shotkit.mjs <project>` then `mvkit plan-check` until the plan passes. Plan-check is free — iterate here, not in renders.

### 3. Asset plan, quotes, confirmation
List every paid item:
- canonical design images (if a style preset is required)
- 1 chroma sheet per character
- pose stills (one per pose; flips of symmetric designs are free second poses)
- plates with seconds at 720p

Quote them live with the exact references, present one plan report (shot table, models and reasons, subtotals, zero-credit MG), and confirm once.

### 4. Reference images → gate
Canonical images, then chroma sheets (PROMPTS §1). Gate each **batch** with one side-by-side image you inspect yourself: identity, proportions, flat chroma, no key-adjacent colors (lime yellows key out). Regenerate only failures.

### 5. Poses and plates (one parallel launch)
Launch all pose stills (PROMPTS §2, the sheets as references, one shared framing block per set) and all plates (PROMPTS §3, smooth actions only) in the same turn.

### 6. Processing (free)
- Batch-download results in one shell call.
- Key all poses in one loop: `mvkit key … --stroke 9 --fit 1920x1080`.
- `mvkit analyze` each plate and read only the summary. Check smear frames, spans and background flatness.
- For cyclic motion (sways, bounces), `mvkit cycle` emits the retime map and phase, keeping playback speed within 0.75–1.35×. Re-analyze with the same map, then key plates with `--stroke-adaptive` and rim colors.
- Every smear window gets a pose-cut replacement, an MG cover or a size reduction (spec 8-5).

### 7. Composition, review, render — budgeted
1. `node scripts/shotkit.mjs <project>`, then gates in **one** shell call: `mvkit plan-check`, `mvkit lint`, `npx hyperframes lint` (0 errors).
2. `mvkit review <project>`. It runs the runtime validation (JS errors fail fast), then snapshots frame 0, every shot midpoint and the last frame into contact sheets. **Inspect those sheets once.** Fix everything found in **one batch**, and re-run `review` only if the fixes changed layout.
3. **One final render**: `npx hyperframes render -f 24 -q delivery`. Verify it with metadata only (duration, frame count, audio stream) plus frame 0. Render again only for a defect found in the render itself.
4. With a size cap, `mvkit bitrate` → two-pass re-encode of the final file (no re-render).

### 8. Canvas record and delivery
The final MP4 cannot be uploaded over MCP (images only), so it stays local. On the project canvas:
- keep all asset nodes (`REF-*`, `POSE-*`, `PLATE-*`)
- add 1–3 poster frames as media nodes when uploads are allowed
- add a text node with the shot summary, credits, measured results and the render path

Group once (AI-production §4).

Report three lists:
- **Executed**: jobs, credits, files.
- **Verified**: gates, smear audit, review sheets.
- **Unverified**: motion feel and taste, anything not measured, and reference media you could not watch.

## Execution economy (hard limits)

| Item | Budget |
|---|---|
| Full renders | 1 final (+1 only for a render-only defect). No draft renders; `review` snapshots replace them |
| Visual reviews | one image per asset batch; one `review` pass (+1 after layout fixes); no per-second contact sheets |
| Generation polling | wait in the background for the expected duration (image batch ≈ 2–6 min, plates ≈ 8–15 min), then check **all** pending jobs in one message. `get_generation` echoes the full prompt, so never poll one job repeatedly |
| Shell calls | batch downloads, keying loops and gates into single calls; print summaries, never full analysis JSON |
| Authoring | write `shots.json` data, not composition code. Custom code only for a kind shotkit lacks, and then add it to the project runtime rather than hand-writing HTML |

Hosts that can call MCP tools from code may run polling and downloads inside a script instead of model turns; the budgets above still apply.

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: toonkit-project-manager
description: Default workflow for ToonKit image, video, voice and canvas work, even without an explicit planning request. Explains model choices and costs before paid generation; routes deterministic 3D previz separately.
---

# ToonKit Project Manager

Run the applicable workflow for ToonKit work unless the user explicitly stands it down. Follow the user's workflow first; honor explicit requirements, infer only delegated gaps and scale the report to the request. Do not write a scenario document for one short clip.

Before new paid generation, give a **visible plan even without “plan first”**: what will be generated and why, exact model/variant and applicable preset, resolution, selection reasons, and the quote inputs and cost status. Model choices must not remain internal or be replaced by “two images at 2K.” The AI report below defines the details; users need not name this skill or SSOT separately. Default paid flow: one report → confirmation of decisions/spend not already authorized → execution. Preserve existing explicit choices and authorization; do not ask again for unchanged approved work. A plan-only request ends with the plan; a requested approval checkpoint must precede generation.

## Route before loading documents

| Request/stage | Load |
|---|---|
| Only deterministic 3D previz, staging/motion/camera or browser-runtime export | The co-distributed [3dref](../3dref/SKILL.md) skill and its routed execution instructions. **No AI workflow or SSOT.** |
| An explicit 2D anime **motion-graphics** video request (kinetic typography/shapes composited with ToonKit characters) | Hand over to the co-distributed [toonkit-motion-mv](../toonkit-motion-mv/SKILL.md) skill. It routes its paid stages back to the AI production workflow below. Ordinary video or clip requests stay here. |
| AI image/video/voice generation, including R2V after previz | [AI production](references/ai-production.md) and [SSOT](TOONKIT-GENERATION-SSOT.md), once before choosing models/references or spending. |
| Existing result/status without new generation | Relevant read-only status tools, not production manuals or a new job. |

A previz exported as MP4 is still deterministic, not AI-video generation. Do not query models, balance, guide or credit quotes for it alone; use the 3D catalog. Missing AI-only SSOT must not block standalone previz.

In mixed pipelines, load AI rules for actual AI stages; do not reread unchanged SSOT on entry/exit from previz. Select previz only when specified or when particular shots need precise spatial/action/camera reference, not every shot. If explicitly required but unavailable, report the prerequisite instead of silently skipping.

## Scope a location reference

For 3Dref, “faithful to the location sheet” means preserving shot-relevant positions, distances, height relationships and interaction surfaces using simple proxies. Plan the actors and camera first, then construct only the needed part of the camera's swept view. Do not rebuild the city panorama, visual style or decorative details. Use the 3dref compiler for measured contact, wall rolls and body retiming; simple native operations and other catalog features use its native MCP route with scoped checks. Save/Export success alone is not proof that the planned beats, slowmo or camera roll were implemented.

## Connection

Toonkit tool names may carry a client-specific prefix; use the connected tool whose name ends with the documented name. If the tools or the generation guide are unavailable, explain the connection problem and help the user authenticate or reconnect. Do not guess generation arguments or submit paid work meanwhile. Never include OAuth tokens or other credentials in output.

## Shared boundaries

- Scene/canvas authoring and generation use MCP. Only 3dref permits scoped visible timeline, navigation, Save and Export; never UI scene authoring or general canvas manipulation.
- Paid work requires the AI workflow's live quote, confirmation and idempotency/recovery rules. Previz authorization does not authorize AI motion purchases or R2V.
- Keep payloads in orchestration memory; emit compact summaries. Reuse unchanged schemas/guides/references. Do not load both structured and serialized copies.
- Use the packaged 3D compiler/runtime (or its portable relay over the same bridge) for supported fresh scenes. It owns connection, journaling, application waits and one export transaction. Do not recreate adapters, transfer/readback scripts or per-batch files.
- Preserve user work. Remove only confidently identified slop this run created when within scope, never prior results/caches for cosmetic tidiness.

## AI-only authority

The SSOT ships next to this SKILL.md and governs model character/selection judgment. Live catalogs/quotes govern numeric limits/prices; the live generation guide governs contracts, billing and error semantics. Live contradictions win; flag stale guidance. If missing when an AI stage actually needs it, search the install root, then ask rather than guess. Fetch candidate model entries, not the full video catalog.

## Delivery

The canvas holds actual deliverables. For standalone previz, the named editable node and source-linked exported video suffice; a short limitations note is optional. No full scenario/prompt/generation-node scaffolding for work with no AI jobs.

Separate executed, verified and unverified. Previz uses numeric/data fidelity and matched decoded-video metadata, with no routine screenshot QA. Generated image assets retain the AI workflow's visual inspection gate. Playable previz does not itself establish R2V compatibility. Return the canvas link and concise result, not temporary-file inventories or expiring URLs.

Referenced files: 2 — file references are metadata, not package contents.