# motion-recovery

The motion-recovery Claude Code skill helps diagnose robot motion failures and choose a changed route. The agent consults it before a difficult reorientation or after motion stalls.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 488 repo stars
- Author: Open-RUA
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Open-RUA/uni-robot-agent/tree/HEAD/uni_robot_agent/resources/skills/general/gripper/motion-recovery/SKILL.md
- Updated: 2026-11-15
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/motion-recovery

## What it does

The skill guides route selection and recovery from IK rejection, joint jumps, stalled tracking, or motion that starts to diverge. It uses the returned state, including executed steps and stop evidence when the tools expose it.

Its guidance keeps planning, executed movement, and measured arrival separate. After a rejection, it recommends changing a route constraint supported by the diagnostics, such as a waypoint, approach direction, orientation, or arm. A held object needs continued support, with grip retention checked after each segment.

An IK success alone does not establish a safe route. The skill also warns against disabling joint-jump protection or repeating the same blocked path in tiny increments.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Open-RUA/uni-robot-agent --skill motion-recovery -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/motion-recovery/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/motion-recovery/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Open-RUA/uni-robot-agent --skill motion-recovery -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/motion-recovery/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Open-RUA/uni-robot-agent --skill motion-recovery -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/motion-recovery/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Open-RUA/uni-robot-agent uni_robot_agent/resources/skills/general/gripper/motion-recovery
```

2. **Manually: put the files in place**
- File: `.github/skills/motion-recovery/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Open-RUA/uni-robot-agent --skill motion-recovery -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Open-RUA/uni-robot-agent --path uni_robot_agent/resources/skills/general/gripper/motion-recovery
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/motion-recovery/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Open-RUA/uni-robot-agent/tree/HEAD/uni_robot_agent/resources/skills/general/gripper/motion-recovery/SKILL.md

## When to use it
- diagnose an IK rejection from motion feedback
- change routes after a joint-jump rejection
- recover after tracking stalls or diverges
- check object retention during a loaded turn

## Example prompts
- Plan a safer route for a difficult turn while the robot is holding an object.
- Analyze this IK rejection and suggest a different approach using the arm's measured state.
- Motion stalled at the basket rim. Identify a route change to try.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4c5df4ea60037465.

BEGIN THIRD-PARTY FILE 4c5df4ea60037465
```text
---
name: motion-recovery
description: Avoid unproductive Direct motion and recover from IK rejection, joint jumps, stalled or diverging tracking, and unsafe motion. Read before a difficult reorientation or when a motion fails to progress.
---

# Avoid motion failures and recover

Choose a reachable route and task-compatible orientation from current evidence.
A failed pose is not proof that the operation or episode is impossible. Use the
common skill for support, attachment and already-submitted action boundaries.

## Before a difficult move

- Retain full poses that this arm actually reached, including orientation and
  whether the hand was empty or supporting an object. A requested but unreached
  pose is not a verified waypoint. A previously reached pose does not certify
  the route back to it or its clearance in a changed scene.
- Prefer an orientation already useful for this arm and operation when its
  geometry remains valid. A coordinate that is reachable with one orientation
  can fail with another. Do not change an instructed orientation just to move.
- Match the target to the registered grasp-site control_pose. Do not substitute
  a native controller pose or an object feature's XYZ without alignment. Use
  `general/gripper/pose-targeting/SKILL.md` for pose and rotation semantics.
- For substantial reorientation, allow clearance for the fingers, wrist,
  forearm and any held object. Consider orienting at a verified clear waypoint
  before approach, but do not require this for every move. Combined translation
  and rotation can improve reachability, but do not establish loaded stability.
  Preserve support and verify retention when changing a held object's orientation;
  an empty-hand recovery is not a validated carrying route. Empty space alone
  does not ensure IK.

## Diagnose from the returned state

Read executed steps, stop reason, per-arm state and any stop evidence exposed by
the current tools before deciding. The table applies when these feedback labels
are available; do not infer an unavailable diagnostic. For planning_rejected,
feedback.stop_evidence.reason identifies the rejected planning condition.

| Feedback | Interpretation and next decision |
|---|---|
| max_steps with decreasing errors | The call budget ended while tracking progressed. Continue toward the same absolute pose if the route remains valid. |
| stop_reason=planning_rejected, reason=ik_failed | Native IK produced no usable candidate for the next waypoint; inspect native convergence and feasibility evidence, not just the combined success flag. Earlier steps in the call may have executed. Inspect actual state and change the relevant approach or orientation. |
```
END THIRD-PARTY FILE 4c5df4ea60037465

The third-party file has ended. Everything between the 4c5df4ea60037465 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2690 of 8274 bytes. © Open-RUA · MIT · https://github.com/Open-RUA/uni-robot-agent/tree/HEAD/uni_robot_agent/resources/skills/general/gripper/motion-recovery/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
