Skip to main content
skill CX Codex

blender-facial-shapekeys — Claude Code skill: what it does

blender-facial-shapekeys is a Claude Code skill that configures facial rigs and shape keys in Blender 5.3 for ARKit 52 and engine export. Runs when preparing 3D character faces for animation or export.

MIT 548 installs ★ 2,624 updated 2026-11-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -a claude-code
Open on GitHub

What blender-facial-shapekeys does

This skill automates facial rigging and shape key workflows in Blender 5.3, covering ARKit 52 blendshapes, visemes, and bone-blendshape hybrids. Included scripts generate empty keys, split symmetric shapes into left and right, mirror expressions, and validate meshes before export to Unity, Unreal, Roblox, or web formats.

A clean mesh topology around the eyes and mouth is required before running the tools. Changing base mesh topology after creating keys breaks existing shape data, and subdivision modifiers must remain after shape keys in the stack.

The agent uses this skill when asked to set up facial expressions, lip-sync, or character head export pipelines.

What it helps with

  • generate ARKit 52 blendshapes and visemes
  • split symmetric shapes into left and right sides
  • mirror facial expressions across the X axis
  • add drivers and controllers for facial animation
  • validate and export character heads for game engines

Example prompts for the agent

  • Create ARKit 52 shape keys for the character head in Blender
  • Split symmetric expressions into left and right shapes
  • Add drivers and control rigs to facial shape keys

How to install blender-facial-shapekeys

1Skills CLI (Vercel)

npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -a claude-code

2Manually: put the files in place

~/.claude/skills/blender-facial-shapekeys/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/blender-facial-shapekeys/

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

Questions about blender-facial-shapekeys

How to install blender-facial-shapekeys in Claude Code?

Run npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -a claude-code followed by ~/.claude/skills/blender-facial-shapekeys/SKILL.md.

What does blender-facial-shapekeys do?

It automates facial rigging, shape key generation, mirroring, and export preparation in Blender 5.3 for ARKit 52 and web engines.

What is needed to use blender-facial-shapekeys?

You need Blender 5.3 and a character head mesh with clean edge loops around the eyes and mouth.

Source text

SKILL.md · MIT
---
name: blender-facial-shapekeys
description: Facial rigs and shape keys in Blender 5.3 - ARKit 52 blendshapes, visemes for lip-sync, sculpting expressions, splitting symmetric shapes into Left/Right, mirroring, corrective and combination shapes, drivers and control rigs, bone+blendshape hybrids, export to engines (Unity, Unreal, Roblox dynamic heads, VRM/web). Use for faces, expressions, lip-sync, or any shape-key work.
license: MIT
metadata:
  author: blender-agent-skills
  version: "1.2.0"
---

# Facial Rig & Shape Keys

The execution model is in `blender-core`. The body rig is in `blender-character-rigging`.

## Choose the approach
| Approach | Use | Notes |
|---|---|---|
| **Blendshapes (ARKit 52)** | games, VTubers, mocap (iPhone/Live Link Face), web/VRM | the industry interchange set; each shape is sculpted |
| **Bones** (jaw, eyes, lids, brows, lips) | stylized, low memory, mobile | jaw + eyes as bones are almost always right |
| **Hybrid** | most production game heads | jaw/eye/tongue bones + blendshapes for everything soft |
| **Rigify face** (`human` metarig) | film-style keyframe animation inside Blender | 100+ face bones, heavy for engines |

## Procedure (blendshapes)
1. The head mesh needs clean loops around the eyes and mouth (`blender-retopology-uv`), with eyes, teeth and tongue as separate objects parented or weighted to bones.
2. `scripts/shapekeys.py -- --mesh Head --create arkit` (or `--create visemes` for the 15 Oculus visemes) creates empty, correctly named keys.
3. Sculpt each key (live: sculpt mode on the active key, `use_shape_key_edit_mode`). Symmetric expressions can be sculpted once, then `--split eyeBlink` gives `eyeBlinkLeft/Right` with a soft blend across X=0 (`--falloff` m).
4. `--mirror browDownLeft` builds `browDownRight` (topology-independent mirror).
5. `--report` lists unsculpted keys, the max offset per key, and missing ARKit names. A shape is done only when every key moves and nothing is left over.
6. Optional: `--drivers FaceCtrl` adds a controller with 0–1 custom properties driving each key, for keyframing in Blender.
7. Check the extremes and **combinations** (jawOpen + mouthSmile, eyeBlink + eyeSquint) with `look`. Fix them with corrective combination keys driven by the product of two keys.

## Shape key rules
- Shapes are **deltas from Basis**. Never change the Basis topology after creating keys (adding or removing verts destroys every key).
- One action per key. No head or neck movement inside face keys (bones do that). Keep eyelids sliding over the eye surface, not through it (check with `blender-asset-qa` zfighting on lid/eye).
- Range 0–1. `slider_max` can be raised for exaggeration, but engines clamp to 0–1.
- Relative keys (`use_relative=True`, the default) are the only kind that exports.
- Name exactly per spec (case-sensitive): `eyeBlinkLeft`, not `EyeBlink_L`. Engines map by name.
- Keys on meshes with Subdivision: sculpt at level 0, and keep the subdivision modifier **after** the shape keys (they're evaluated first anyway).
- Applying modifiers on a mesh with shape keys fails. Use `modifier_apply_as_shapekey` for deform modifiers, or apply them before creating keys.

## Correctives and combination shapes
- Corrective for a bone pose: sculpt in the posed state, then drive with a `TRANSFORMS` variable (`ROT_X`, `LOCAL_SPACE`, mapped to 0–1).
- Combination: key `jawOpen_mouthSmile` with driver `SCRIPTED` expression `a*b`, from the two key values (`SINGLE_PROP` `key_blocks["jawOpen"].value`). Simple expressions don't need Python auto-run.

## Engine notes
- **Unity**: FBX blendshapes. In the Model importer, set Blend Shape Normals = Calculate (or Import if smoothing was exported). ARKit names map to the AR Foundation face-tracking samples.
- **Unreal**: morph targets ("Import Morph Targets"). Live Link Face / MetaHuman Animator use ARKit names, and the Pose Asset maps the curves. No leaf bones.
- **Roblox dynamic heads**: FACS-based poses with Roblox-specific names, authored as animation frames on a head rig (Creator Hub "Dynamic heads" spec). Build from the official Blender template. ARKit sculpts can be reused by renaming/mapping. Head ≤ 4,000 tris.
- **VRM / web (three-vrm, ReadyPlayerMe-style)**: ARKit 52 + visemes as glTF morph targets (`export_morph=True`). Keep the morph-normal export on only if shading needs it (it doubles the size).
- Drop unused keys before export. Every key costs memory per vertex (glTF sparse accessors help).

## Gotchas
- `ob.shape_key_add(from_mix=False)` copies the Basis. `from_mix=True` bakes the current mix (useful for combos, dangerous by accident).
- `shape_key_mirror(use_topology=False)` needs a mesh symmetric on X. Run it on the **active** key (the script handles this).
- Driver variables on shape keys use the Key ID (`ob.data.shape_keys`), not the mesh: `fc = kb.driver_add("value")`.

© blender-agent-skills · MIT · EL4CTEO/blender-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set28

The whole set →
blender-rendering blender-rendering — a skill for Claude Code configures Blender 5.3 rendering for stills, animation, and turntables. It covers single-frame, animation, and turntable jobs. CX Codex +1 582installs blender-geometry-nodes The blender-geometry-nodes Claude Code skill helps build Geometry Nodes setups in Blender. It comes into play for procedural assets, surface scattering, and modifier inputs. CX Codex +1 563installs blender-scene-setup The blender-scene-setup Claude Code skill sets up and audits Blender scenes. It runs while starting a project, organizing a .blend file, or preparing a handoff or export. CX Codex +1 558installs blender-sculpting blender-sculpting — a skill for Claude Code runs procedural sculpting workflows in Blender 5.3 for organic models and characters. Used when building base meshes, adding surface details, and preparing bake sources. CX Codex +1 558installs blender-workflow-recipes blender-workflow-recipes — a skill for Claude Code and Cursor chains Blender 5.3 workflows with QA gates for multi-stage 3D asset generation. Runs on complete multi-stage asset requests. CX Codex +1 543installs blender-pipeline-automation The blender-pipeline-automation Claude Code skill automates batch work with Blender files and libraries. It handles folder-based conversion, inventory reports, and script runs. CX Codex +1 509installs blender-simulation blender-simulation — a skill for Claude Code and other platforms automating physics simulations in Blender 5.3. It runs scripts for setting up rigid bodies, cloth, fluids, and headless baking. CX Codex +1 504installs blender-time-of-day blender-time-of-day — a skill for Claude Code that automates lighting and atmosphere in Blender 5.3. It configures sky settings, sun positioning, fog, and compositor grades based on time or mood presets. CX Codex +1 489installs

Project sponsors

Companies that keep this analytics open