SkillAgentSearch skills...

mujoco

MuJoCo physics simulation for robotics: writing and debugging MJCF models, importing URDF, simulating, controlling and rendering from Python, tuning contacts, and running batched GPU simulation.

Install / Use

npx skills add arpitg1304/robotics-agent-skills --skill mujoco

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Our assessment of mujoco

mujoco scores 89/100 on our quality scale, 468th of 1,148 Content & Media skills we index (top 41%).

Its SKILL.md is 20 KB long, well organised into 13 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.

It has 405 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
11/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 3 days ago, so mujoco is actively maintained.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.

Automated pattern scan on 2026-11-22. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

mujoco compared with similar skills

All 4 of these similar skills score higher than mujoco; compare them before choosing.

SkillScoreStarsUpdatedFormat
mujoco (this skill)by arpitg1304894053d agoSKILL.md
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
headroomby headroomlabs-ai10080.5ktodayCLAUDE.md
Scraplingby D4Vinci100104.9k5d agoMCP Server
crawl4aiby unclecode10087.7k2d agoMCP Server

Frequently asked questions

How do I install mujoco?
Run npx skills add arpitg1304/robotics-agent-skills --skill mujoco. The install tabs above show the steps for each supported agent.
Which AI agents does mujoco work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is mujoco safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is mujoco still maintained?
The repository was last updated 3 days ago, so mujoco is actively maintained.

name: mujoco description: > MuJoCo physics simulation for robotics: writing and debugging MJCF models, importing URDF, simulating, controlling and rendering from Python, tuning contacts, and running batched GPU simulation. Use this skill when the user mentions MuJoCo, MJCF, mujoco.MjModel / MjData, mj_step, MjSpec, mujoco.Renderer, MUJOCO_GL, EGL/OSMesa headless rendering, the passive viewer or MuJoCo Studio, MuJoCo Menagerie (Franka, UR5e, SO-100/SO-101, ALOHA, G1), MJX, MuJoCo Warp (mujoco_warp), MuJoCo Playground, dm_control, or Gymnasium MuJoCo envs. Also trigger for contact tuning (solref, solimp, condim, friction, impratio, noslip), exploding or jittering simulations, objects sinking or grasps slipping, position actuator kp/kv, joint armature and damping, contype/conaffinity collision filtering, keyframes, integrator and timestep choice, and system identification or domain randomisation of MuJoCo model fields for sim-to-real.

MuJoCo Skill

Verified against MuJoCo 4.0.1, 2026-11-18. Examples were executed with mujoco==4.0.1, mujoco-mjx==4.0.1 (JAX 0.12.1, CPU), mujoco-warp==4.0.1 (Warp 1.19.0, CPU device) and gymnasium==1.4.0 on Python 3.12, macOS arm64.

MuJoCo moves fast (4.0.0 shipped 2026-11-06 with breaking changes; a new discrete integrator and speculative contacts landed in autumn 2026). Before relying on a detail that is not in this skill, check the installed docs: pip install mujoco bundles the Sphinx manual and Google's own agent skills under pathlib.Path(mujoco.__file__).parent / "doc" (doc/skills/python, rendering, accelerated, spec_editing, ...). Grep there for the literal .. _option-integrator:-style anchor of an attribute.

When to Use This Skill

  • Writing or fixing an MJCF scene: bodies, joints, actuators, sensors, defaults, keyframes
  • Converting a URDF to MJCF and making it simulate well
  • Writing a Python control loop, reading sensors, resetting episodes, saving state
  • Rendering RGB / depth / segmentation offscreen, including on headless Linux
  • Diagnosing exploding, jittering, sinking, tunneling or slipping simulations
  • Choosing between CPU MuJoCo, mujoco.batch, MJX and MuJoCo Warp for parallel rollouts
  • Identifying actuator gains, armature and friction from hardware logs; randomising model fields

Out of scope here: RL algorithms, reward design and sim-to-real theory (robot-reinforcement-learning); Isaac Sim / Isaac Lab (isaac-sim); LeRobot datasets and policies (lerobot, imitation-learning).

Ecosystem Map

Full component table and Menagerie model list: references/ecosystem.md.

  • Core: pip install mujoco (4.0.1), Python >= 3.11. Since 4.0 mujoco is a metapackage: mujoco-core (numpy only; headless servers, RL workers) + mujoco-studio + glfw/pyopengl.
  • CPU batch: from mujoco import batch, rollout; multi-threaded, float64, all solvers/plugins.
  • MJX (pip install mujoco-mjx, from mujoco import mjx): impl="jax" (default; any XLA device; differentiable) or impl="warp" (NVIDIA; not differentiable).
  • MuJoCo Warp (pip install mujoco-warp, import mujoco_warp as mjw): NVIDIA GPU, highest-throughput batches, PyTorch training; not differentiable.
  • MuJoCo Playground (pip install playground, 1.0.1): rewritten as PyTorch tasks on reaf-sim + MuJoCo Warp with RSL-RL training and real-robot deploy. The original JAX/MJX envs live in the repo's rss2025/ directory.
  • Menagerie: curated MJCF robots (pip install mujoco-menagerie); never hand-write a common arm. SO-101: robotstudio_so101/so101.xml. Some models ship *_mjx.xml variants.
  • dm_control 1.0.52 requires mujoco>=4.0.1; for new procedural models use mujoco.MjSpec, not PyMJCF. Gymnasium 1.4.0: *-v5 envs only; -v2/-v3 raise a mujoco-py error.
  • Viewers: mujoco.viewer (managed/passive) and MuJoCo Studio (python -m mujoco.studio.viewer --model=x.xml, --gfx=web), the successor of simulate.
  • 4.0 changes noted in this skill: metapackage split; saturated actuators contribute no implicit damping; the composite/cable plugin was removed (use 1D flexcomp); speculative contacts are new.

Choosing a backend (heuristic): one env or real-time loop -> CPU mujoco; tens to a few thousand envs on a many-core box, or you need noslip/PGS/plugins/float64 -> mujoco.batch; thousands of envs on an NVIDIA GPU -> MuJoCo Warp (or MJX with impl="warp" inside JAX); gradients through dynamics, TPU, AMD or Apple GPU -> MJX-JAX.

MJCF Essentials

This model (executed, see the loop below) shows the patterns that matter: explicit angle units, implicitfast, a default class tree that separates visual and collision geoms, armature and damping on joints, a force-limited critically damped position servo, sensors and a keyframe.

<mujoco model="one_link_arm">
  <compiler angle="radian" autolimits="true"/>
  <option timestep="0.002" integrator="implicitfast" cone="elliptic" impratio="10"/>

  <default>
    <joint damping="0.1" armature="0.01"/>
    <position kp="20" dampratio="1" forcerange="-5 5"/>
    <default class="visual">
      <geom contype="0" conaffinity="0" group="2"/>
    </default>
    <default class="collision">
      <geom group="3"/>
    </default>
  </default>

  <worldbody>
    <light pos="0 0 2"/>
    <geom name="floor" type="plane" size="1 1 0.1"/>
    <camera name="side" pos="0 -1.2 0.4" xyaxes="1 0 0 0 0.3 1"/>
    <body name="link" pos="0 0 0.3">
      <joint name="shoulder" type="hinge" axis="0 1 0" range="-1.57 1.57"/>
      <geom class="collision" type="capsule" fromto="0 0 0 0.3 0 0" size="0.02" mass="0.5"/>
      <geom class="visual" type="capsule" fromto="0 0 0 0.3 0 0" size="0.025"/>
      <site name="tip" pos="0.3 0 0"/>
    </body>
  </worldbody>

  <actuator>
    <position name="shoulder" joint="shoulder" ctrlrange="-1.5 1.5"/>
  </actuator>

  <sensor>
    <jointpos name="shoulder_pos" joint="shoulder"/>
    <jointvel name="shoulder_vel" joint="shoulder"/>
    <framepos name="tip_pos" objtype="site" objname="tip"/>
  </sensor>

  <keyframe>
    <key name="home" qpos="0" ctrl="0"/>
  </keyframe>
</mujoco>

Rules that prevent most modelling bugs (full text: references/mjcf-reference.md, last section; attribute tables with verified defaults are in the same file):

  • Angles: compiler/angle defaults to "degree" for MJCF (always radian for URDF). Set it.
  • Mass: every geom in inertiagrouprange (default "0 5") adds inferred mass, including visual geoms with contype=conaffinity=0; a duplicated visual geom doubled the mass (verified). Use explicit <inertial>, inertiagrouprange, or mass="0"/density="0".
  • Joints: armature and damping default to 0 and should almost never be 0 on a geared joint. In MjSpec, damping/stiffness take a 3-vector (a scalar raises TypeError).
  • Actuators: position has kp default 1, kv 0; it compiles to gainprm[0]=kp, biasprm[1:3]=[-kp, -kv]. Always set forcerange; keep ctrlrange inside the joint range except on grippers.
  • Collision filtering: collide iff (contype1 & conaffinity2) || (contype2 & conaffinity1); same-body and parent-child pairs are excluded; use <exclude> and <pair>.
  • Keyframes: qpos is positional; re-record after adding or removing joints. Mocap fields are mpos/mquat.
  • Sensors: observe through data.sensordata and <contact> sensors, not data.contact. Sensor noise does not affect simulation; add noise yourself.

URDF import (MjSpec.from_file("robot.urdf"): nu == 0, package:// paths, discarded visuals, fused links) and MjSpec editing: references/python-examples.md, with the conversion recipe in references/mjcf-reference.md.

Python Simulation Loop

import mujoco
import numpy as np

model = mujoco.MjModel.from_xml_string(XML)     # or from_xml_path / MjSpec(...).compile()
data = mujoco.MjData(model)

CONTROL_HZ = 50
n_substeps = round(1.0 / (CONTROL_HZ * model.opt.timestep))   # 10 physics steps per action
assert abs(n_substeps * model.opt.timestep - 1.0 / CONTROL_HZ) < 1e-9

mujoco.mj_resetDataKeyframe(model, data, model.key("home").id)
mujoco.mj_forward(model, data)          # kinematics + sensors at t=0, time not advanced

act = data.actuator("shoulder")         # named views, no index bookkeeping
for k in range(100):
    act.ctrl[0] = 0.8 * np.sin(2 * np.pi * 0.5 * data.time)
    mujoco.mj_step(model, data, nstep=n_substeps)   # ctrl held (zero-order hold)

q = data.sensor("shoulder_pos").data[0]
tip = data.sensor("tip_pos").data.copy()            # copy: views are overwritten in place
assert np.isfinite(data.qpos).all()

Key semantics (full list, state save/restore and the passive viewer: references/python-examples.md):

  • After mj_step, sensordata, xpos, contacts etc. describe the state at the start of that step, one step behind qpos. Call mj_forward before reading if you need them consistent with qpos, or use mj_step1 / set ctrl / mj_step2.
  • mj_forward computes everything without integrating. Call it after editing qpos, qvel, mocap_pos or after a reset, before reading positions or sensors.
  • Never write xpos, xquat, sensordata: they are outputs.
  • Quaternions are scalar-first [w, x, y, z]; SciPy and ROS are scalar-last.
  • Free-joint qpos is 7 numbers but qvel is 6, so nq != nv: use named access or jnt_qposadr / jnt_dofadr.

Reset with mujoco.mj_resetData or mj_resetDataKeyframe; checkpoint with mj_getState / mj_setState and mjSTATE_INTEGRATION (bit-identical continuation).

Determinism: the same binary, model, initial state and control sequence reproduce bit-identical trajectories on CPU (asserted in the executed example; mujoco.batch is documented as bit-identical to serial stepping). Things that break it: resetting by writing qpos/qvel/time instead of calling mj_resetData (solver warm-start carries over; measured 3e-6 divergence after 300 contact steps, versus bit-identical with mj_resetData), different library versions or builds, GPU float32 backends, and unseeded Python randomness.

Rendering

Create mujoco.Renderer(model, height, width) once (as a context manager) and reuse it: update_scene(data, camera="name") then render() gives (H, W, 3) uint8; enable_depth_rendering() gives float32 metres and enable_segmentation_rendering() gives [obj id, mjtObj type]. Set MUJOCO_GL (egl, osmesa, ...) before import mujoco. Width/height cannot exceed <visual><global offwidth offheight/> (default 640x480). Render at the policy rate, not every substep. Executed example, all MUJOCO_GL values, cameras, and the Filament and Warp renderers: references/python-examples.md.

Contacts and Stability

MuJoCo contacts are soft constraints. Tune in this order: fix modelling bugs (initial interpenetration, concave meshes collided as hulls, bad inertias, units) -> implicitfast -> timestep -> cone="elliptic" + impratio -> solref -> solimp -> condim/friction -> noslip. The full guide with defaults and starting values, collision geometry, the grasp recipe and the executed divergence example: references/contacts-debugging.md.

Most common symptoms (full table in the reference):

| Symptom | Likely cause | Fix | |---|---|---| | Sim explodes / mjWARN_BADQACC / state silently resets | Timestep too large for stiffness; explicit kv or damping under Euler; light link with no armature; initial penetration | implicitfast, smaller timestep, add armature, remove initial overlaps, bound forcerange | | Explodes only when the actuator saturates | Saturated actuators contribute no implicit damping (4.0 change) | Joint armature + passive damping, or smaller timestep | | Objects sink into the floor or each other | solref too soft, mass ratio > 1000:1, solimp dmin low | solref 0.004-0.01, solimp 0.

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars405
CategoryContent
Updated3d ago
Forks51

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions