---

name: protomotions description: "Use this skill for ProtoMotions 3 humanoid simulation, motion-learning, retargeting, simulator-backend, training, inference, and deployment workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

ProtoMotions

Use this repo skill when a task involves ProtoMotions 3 (protomotions), a Python framework for GPU-accelerated humanoid and character simulation, motion imitation, retargeting, reinforcement-learning experiments, and G1 deployment workflows.

Fast routing

• Install/import/backend issue: read sub-skills/installation-and-backends/SKILL.md, then references/troubleshooting.md if assets or simulator imports fail.
• Simulator, robot, terrain, scene, or tutorial-style construction: read sub-skills/simulator-foundations/SKILL.md.
• Training, inference, experiment configs, checkpoints, domain randomization, SLURM, or GPC/PEFT: read sub-skills/training-and-experiments/SKILL.md.
• MotionLib, AMASS/PHUMA/SEED/Kimodo data conversion, PyRoki retargeting, contacts, FPS, or motion filters: read sub-skills/retargeting-and-motion-data/SKILL.md.
• ONNX export, standalone MuJoCo deployment, G1 real-robot integration, custom robots, MJCF/USD, or tracker input semantics: read sub-skills/deployment-and-robots/SKILL.md.

What to know before acting

1. ProtoMotions intentionally uses separate environments per simulator backend. Do not install all extras into one environment.
2. IsaacGym and IsaacLab must be imported before importing torch; use protomotions.utils.simulator_imports.import_simulator_before_torch() in custom scripts.
3. The wheel/package ships Python modules and most robot assets, but examples, checkpoints, MotionLib data, and some conversion helpers are source-checkout assets. A source checkout with Git LFS is required for packaged examples or pretrained artifacts.
4. SMPL/SMPL-H body-model assets are intentionally excluded from built distributions. Use a complete licensed asset tree and set PROTOMOTIONS_ASSET_ROOT when those assets are missing.
5. resolved_configs.pt and resolved_configs_inference.pt are the source of truth for trained runs; YAML sidecars are human-readable only.
6. Cross-simulator transfer is not automatic. It is expected mainly for policies explicitly trained with transfer-oriented domain randomization, especially the documented G1 deployment tracker.

Minimal install and inspection checks

After selecting a backend environment, run:

protomotions info --json
protomotions train-agent --help
protomotions inference-agent --help

For a Python smoke without starting a simulator:

from protomotions.robot_configs.factory import robot_config
from protomotions.simulator.factory import get_simulator_config_class
from protomotions.components.motion_lib import MotionLibConfig

print(robot_config("g1").number_of_actions)
print(get_simulator_config_class("mujoco").__name__)
print(MotionLibConfig().motion_file)

The bundled script scripts/inspect_protomotions_install.py performs the same checks and emits JSON.

Repo-level references

• references/quick-reference.md: compact command, object, and file-artifact cheat sheet.
• references/install-and-backends.md: backend environment choices and simulator compatibility summary.
• references/cli-and-config.md: train/inference CLI conventions and resolved-config lifecycle.
• references/troubleshooting.md: cross-cutting failures for imports, assets, data, checkpoints, simulator backends, and deployment.
• references/repo-provenance.md: source commit, version, evidence paths, and verification baseline for this generated skill.
• references/repo-routing-metadata.json: structured scenario metadata used by repo-skill import tooling.

Safety and scope boundaries

• Treat full training, simulator rollout, PyRoki retargeting, ONNX deployment, IsaacLab conversion, and real-robot control as hardware/data-dependent operations. Prefer parser/import/config checks before long runs.
• Do not run real-robot commands without explicit human authorization and an emergency-stop plan.
• Do not mutate a user's existing backend environment without permission; create a separate backend-specific environment when dependencies conflict.
• When using a package-only install, do not assume source-checkout examples or large Git LFS assets are present.