# Generate Motion

> Use when the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library. Picks the right curated motion, attaches the resulting clip to an AnimationPlayer. Trigger on "animation", "animate", "idle", "walk", "run", "attack animation", "motion", "mocap", "dance", "death animation".

- **Type:** Skill
- **Install:** `agentstack add skill-summerengine-summer-engine-agent-generate-motion`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SummerEngine](https://agentstack.voostack.com/s/summerengine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SummerEngine](https://github.com/SummerEngine)
- **Source:** https://github.com/SummerEngine/summer-engine-agent/tree/main/skills/animation/generate-motion
- **Website:** https://summerengine.com/

## Install

```sh
agentstack add skill-summerengine-summer-engine-agent-generate-motion
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Generate Motion — Curated Meshy Library

Picks a clip from a **curated mocap library** by name (`idle`, `walk`, `run`, `attack_sword`, ~70 standard names) and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap.

The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `summer:asset-pipeline/asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.

> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on the roadmap but not shipped yet. For one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo. See the Edge cases section.

## Web Chat / Public Orchestrator Equivalent

In PublicSummerEngine chat, the equivalent direct tools are:

```
rigModel({ modelAssetId })
generateAnimation({ rigAssetId, animationName })
meshyJobStatus({ jobId })
```

If the character came from `createCharacter`, it may already be rigged and have `metadata.meshyRigTaskId`; generate animations directly against that rig asset. Verified animation names from the recovered production flow are `idle`, `walk`, `run`, `jump`, and `attack`. `fall` returned `invalid_animation`, so do not present it as a default.

Before generating clips in PublicSummerEngine chat, confirm the rig asset listing/status exposes `hasMeshyRigTask` or `animationsReady:true`. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig again, and retry; this is the post-rig setup catching up, not a reason to send the user to Studio.

After animation jobs complete, import the rig plus child animation assets together and wire them through `import-character`. Do not hand off to Studio unless the user asked for Studio/manual control or the direct chat tools fail.

## When to use this skill

- "Add a walk animation to the goblin."
- "I need an idle, a run, and an attack on this character."
- "Death animation for the enemy when HP hits zero."
- The user has a rigged character and zero animations on it.

## When NOT to use this skill

- The user wants to apply an *existing* animation to a *new* model — use `summer:animation/retarget` instead. Don't regenerate.
- The user wants state-machine wiring (idle → walk → run blend) — generate the clips here, then hand off to `summer:animation/animation-tree`.
- The user wants facial / lipsync animation — that's `summer:animation/facial-and-lipsync`.
- The mesh isn't rigged. Rig first; never call `summer_generate_motion` on a static `.glb`.
- The user wants procedural look-at, IK, foot placement — that's `summer:animation/procedural-animation`.
- The user described a **custom signature move** that isn't on the curated list. Today, route to the manual-authoring fallback below.

## Steps

### 1. Verify the target is a rigged humanoid

```
summer_search_assets(query="", assetType="3d_model", source="my_assets")
```

The result must include `rigAssetId: ` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `summer:asset-pipeline/asset-strategy`.

### 2. Confirm with the user before spending

> I'm about to generate a "run" animation on `goblin_rigged` via meshy-library — about 30s, ~$0.10. OK?

### 3. Call the tool

```
summer_generate_motion(
  rigAssetId: "",
  backend: "meshy-library",   // only option today
  motionName: "run"           // exact name from the curated list — see Reference card
)
```

Returns `animationAssetId`, `durationSeconds`, and `previewUrl`. Resolve the
asset before handoff so you have the stable file/download metadata:

```
summer_get_asset(assetId="")
```

### 4. Attach to the character's AnimationPlayer

```
summer_inspect_node("./World/Goblin")             // confirm it has an AnimationPlayer child
summer_add_node(parent="./World/Goblin", type="AnimationPlayer", name="AnimationPlayer")  // only if missing
summer_set_resource_property(
  nodePath="./World/Goblin/AnimationPlayer",
  resourceProperty="libraries/default",
  subProperty="",
  value=""
)
summer_save_scene
```

If the character will use multiple clips, leave the AnimationPlayer in place — every subsequent generation appends to the same library. State-machine wiring belongs to `summer:animation/animation-tree`, not here.

## Confirmation gates

- **Before generation:** state the motion name and est. cost (~$0.10). Wait for OK.
- **Before attaching:** state which AnimationPlayer and which library slot. Wait for OK.
- **After generation:** if the user hasn't seen the preview, link `previewUrl` and ask "land or regenerate?" before wiring it into the scene.

## Reference card

### Curated motion library — top 30 names (Meshy, exact strings)

`idle`, `idle_alert`, `idle_combat`, `walk`, `walk_strafe_left`, `walk_strafe_right`, `walk_back`, `run`, `run_strafe_left`, `run_strafe_right`, `sprint`, `jump`, `jump_loop`, `jump_land`, `crouch_idle`, `crouch_walk`, `attack_sword`, `attack_punch`, `attack_kick`, `attack_bow`, `attack_cast`, `block`, `dodge_left`, `dodge_right`, `hit_react`, `death`, `death_back`, `wave`, `dance`, `sit_idle`.

The full list is ~70 names. If the user asks for something not on the top-30, try the closest curated name first; if nothing fits, route to the manual-authoring fallback.

### Pitfalls

- **`motionName` typos silently match nothing.** `"run_fast"` is not on the list — the call returns an error. Always check the curated list first. Use exact strings from the list above.
- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. If you're driving root motion in code, set `root_motion_track` correctly or strip the translation in an AnimationPlayer Edit. See the Godot 4.5 root motion docs.
- **Rig pose mismatch.** If your rig was rigged with a non-T-pose reference image, the limbs may bend wrong. Re-rig from a T-pose mannequin (see `summer:asset-pipeline/asset-strategy`) before re-generating.
- **Rig still preparing.** New rigs need ~3 minutes after the rig job completes before the animation library is ready. The MCP route returns 425 "animations_preparing" if you call too early. Wait and retry.

## Anti-patterns

- Calling `summer_generate_motion` on a `.glb` that wasn't rigged — wastes a generation; the API errors but only after 30s.
- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", assetType: "animation", source: "my_assets")`.
- Wiring clips into an AnimationTree inside this skill. That's the next skill's job. Generate, attach, hand off.
- Asking the model to invent a `motionName` that isn't on the list. Quote from the list verbatim, or fall back to manual authoring.

## Edge cases

- **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom prompt-driven backend is on the roadmap but not shipped today. Workarounds: (a) hand-author the clip in the Godot editor's animation panel; (b) record/buy from Mixamo and import as `AnimationLibrary`; (c) compose two curated clips in an `AnimationTree`'s `OneShot` blend.
- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds, hand-author or import a Mixamo-style external library (out of scope for this skill).
- **Character is < 1m tall (child / dwarf).** Library clips assume a ~1.8m humanoid. Apply the clip; the proportions retarget but stride length looks long. Either accept it or tune `playback_speed` on the AnimationPlayer track.
- **Character has wings / tail.** The library ignores the extra bones — they sag. Hand-author additive overlays for the extra bones, or accept the visual hit.

## Fallback (no MCP)

The user can upload to Meshy directly at meshy.ai, generate via the dashboard, download `.glb`, and import as an `AnimationLibrary` in the Godot editor. Slower, but identical output.

## Handoff

- After generating locomotion clips, suggest `summer:animation/animation-tree` to wire idle → walk → run.
- After generating a one-shot (death, hit-react), suggest `summer:ai-and-npcs/design-npc` to fire it from the behavior state machine.
- For first-person hand animations on a player, use this skill on a *hands-only rig* and then `summer:character-controllers/fps-controller` for the wiring.
- If the user wants to apply these clips to a second character, hand off to `summer:animation/retarget`.

## See also

- `references/mcp-tools-reference.md` — `summer_generate_motion` parameter schema, error codes.
- `summer:asset-pipeline/asset-strategy` — how to get a Meshy-rigged character in the first place.
- `summer:animation/animation-tree` — wire the generated clips into a state machine.
- `summer:animation/retarget` — re-use one library across many characters without regenerating.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SummerEngine](https://github.com/SummerEngine)
- **Source:** [SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent)
- **License:** MIT
- **Homepage:** https://summerengine.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-summerengine-summer-engine-agent-generate-motion
- Seller: https://agentstack.voostack.com/s/summerengine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.