What is the Mujoco skill?
Mujoco is a coding skill by arpitg1304 for Claude Code, Cursor, Codex and other AI coding agents. 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.
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.
What the SKILL.md covers
- When to Use This Skill
- Ecosystem Map
- MJCF Essentials
- Python Simulation Loop
- Rendering
- Contacts and Stability
- GPU and Batched Simulation
- Sim-to-Real for MuJoCo Models
- Anti-Patterns
- Checklist
- Author
- arpitg1304
- Pack
- arpitg1304/robotics-agent-skills (17 skills)
- Category
- Coding, #1192 of 1777
- Alyn Score
- 60 / 99
- Files
- 7, includes references
- License
- Apache-2.0
- Last updated
- 2 days ago
- Works with
- Claude Code, Claude, Cursor, Codex, Gemini CLI, Copilot
Mujoco compared to similar skills
| Skill | Alyn Score | GitHub stars | Updated |
|---|---|---|---|
| Mujoco · arpitg1304 | 60 | 403 | 2 days ago |
| PR · Matt Pocock | 94 | 328k | 3 days ago |
| Writing Plans · Jesse Vincent | 88 | 322k | 17 days ago |
| Writing Fragments · vinvcn | 68 | 5.9k | 4 days ago |
Install Mujoco
Pick your agent. Every command is ready to paste.
npx alyn-cli add mujocoDetects your agents (Claude Code, Cursor, Codex and 70+ more) and installs to the right folder. Add -g to install globally.
npx skills add arpitg1304/robotics-agent-skills --skill mujocoOr use the open skills CLI directly.
01
Install it
Run the command above, or upload the folder in Claude.
02
Ask naturally
Describe the task. Your agent loads mujoco when the request matches its description.
03
Name it if needed
If it does not trigger, say “use the mujoco skill”. In Codex, type $mujoco.
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.0mujocois 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) orimpl="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 onreaf-sim+ MuJoCo Warp with RSL-RL training and real-robot deploy. The original JAX/MJX envs live in the repo'srss2025/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.xmlvariants. - dm_control 1.0.52 requires
mujoco>=4.0.1; for new procedural models usemujoco.MjSpec, not PyMJCF. Gymnasium 1.4.0:*-v5envs only;-v2/-v3raise a mujoco-py error. - Viewers:
mujoco.viewer(managed/passive) and MuJoCo Studio (python -m mujoco.studio.viewer --model=x.xml,--gfx=web), the successor ofsimulate. - 4.0 changes noted in this skill: metapackage split; saturated actuators contribute no
implicit damping; the
composite/cableplugin was removed (use 1Dflexcomp);speculativecontacts 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/angledefaults to"degree"for MJCF (always radian for URDF). Set it. - Mass: every geom in
inertiagrouprange(default"0 5") adds inferred mass, including visual geoms withcontype=conaffinity=0; a duplicated visual geom doubled the mass (verified). Use explicit<inertial>,inertiagrouprange, ormass="0"/density="0". - Joints:
armatureanddampingdefault to 0 and should almost never be 0 on a geared joint. InMjSpec,damping/stiffnesstake a 3-vector (a scalar raisesTypeError). - Actuators:
positionhaskpdefault 1,kv0; it compiles togainprm[0]=kp,biasprm[1:3]=[-kp, -kv]. Always setforcerange; keepctrlrangeinside the jointrangeexcept on grippers. - Collision filtering: collide iff
(contype1 & conaffinity2) || (contype2 & conaffinity1); same-body and parent-child pairs are excluded; use<exclude>and<pair>. - Keyframes:
qposis positional; re-record after adding or removing joints. Mocap fields arempos/mquat. - Sensors: observe through
data.sensordataand<contact>sensors, notdata.contact. Sensornoisedoes 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 behindqpos. Callmj_forwardbefore reading if you need them consistent withqpos, or usemj_step1/ setctrl/mj_step2. mj_forwardcomputes everything without integrating. Call it after editingqpos,qvel,mocap_posor 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
qposis 7 numbers butqvelis 6, sonq != nv: use named access orjnt_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.95, realistic masses |
| Objects hover above surfaces | margin without matching gap; mesh hull larger than visual |
Remove margin; check collision group rendering |
| Grasped object slips or rotates out | Pyramidal cone, condim 3, low normal force (servo stops at contact), friction mixing picking the low value | Elliptic + impratio=10, condim=4/6, command past contact, priority, noslip_iterations |
| High-frequency jitter at rest | High gains vs armature, stick-slip, explicit damping | Add armature, implicitfast, lower kp or add dampratio=1, smaller timestep |
| Thin parts pass through each other | Tunneling within one step | speculative flag, thicker collision geoms |
| Mug/bowl behaves like a solid | Convex hull of a concave mesh | Convex decomposition |
| Actuator does nothing | ctrlrange in degrees vs radians, kp left at default 1, gear sign |
Inspect model.actuator_gainprm, actuator_ctrlrange |
The autoreset flag (on by default) resets the state when it detects numerical problems,
so a diverged run can look merely wrong rather than crash. In RL pipelines treat any
BADQACC/BADQPOS warning count increase or non-finite qpos as a terminal, invalid
transition rather than letting the reset hand the policy a teleported state.
GPU and Batched Simulation
Device data structures need static sizes, which is the root of most surprises. Executed MJX
and MuJoCo Warp examples (rollouts, domain randomisation via in_axes / batch_sizes) and
the full list of differences from CPU: references/gpu-batched-sim.md.
- float32 on device vs float64 on CPU: stiff models that are fine on CPU can drift or NaN.
- No
PGSon any GPU path. MJX-JAX silently ignoresnoslip_iterations > 0(verified in 4.0.1) and rejectsintegrator="discrete"atmjx.step. - MJX-JAX allocates contact slots for every geom pair that could collide: prune with
contype/conaffinity,excludeand<pair>s. - MuJoCo Warp sizes buffers with
nconmax/naconmax/njmaxper world (<size>in XML is ignored); excess contacts are dropped and flagged ind.overflow. Check it. - A GPU step is slower than a CPU step; GPUs win on throughput.
Sim-to-Real for MuJoCo Models
Identify before you randomise: randomising around a wrong nominal model only teaches the
policy to be robust to the wrong robot. Identify joint armature, actuator kp/kv and
forcerange, frictionloss/damping, latency and payload masses with mujoco.sysid
(pip install "mujoco[sysid]"); model latency natively with actuator/sensor delay +
nsample. After changing mass, inertia or armature on a compiled model call mj_setConst
then mj_resetData; keep a position servo's biasprm consistent with a randomised kp.
Details, the executed DR example and the runtime-modifiable field table:
references/sim-to-real-model-fields.md. Randomisation ranges and curricula are algorithm
design: see robot-reinforcement-learning.
Anti-Patterns
- Leaving the physics defaults: Euler + pyramidal cone +
solref 0.02+ zero armature is the most common source of jitter and slip. Set option and top-level defaults once. - Degrees by accident: forgetting
<compiler angle="radian"/>with radian ranges. - Visual meshes that collide and add mass:
contype="0" conaffinity="0"stops collision but not inertia inference; also use explicit<inertial>,inertiagrouprange, ormass="0"/density="0"on one of the two geom sets. - Raw indices:
data.qpos[7]breaks when a joint is added. Use named access,jnt_qposadr, orbind. - Reading
sensordataright aftermj_stepand assuming it matchesqpos: it is one step behind. Usemj_forwardormj_step1/mj_step2. - Using
data.contactas an observation: variable length and order; use contact sensors. - Trusting
noise=on sensors: it is metadata only. - Creating a
Rendererper frame: leaks GL contexts and is slow; create once, close it. - Setting
MUJOCO_GLafterimport mujoco(or after importing dm_control/gymnasium). - Randomising
kpwithout updatingbiasprm[1]: the servo then has a spring to the wrong setpoint. - Ignoring
BADQACC/ auto-reset in RL rollouts. - Hand-tuning gains by eye when
mujoco.sysidand a 2-minute excitation log exist. - Porting a CPU model to MJX unchanged: dense mesh scenes crawl, unsupported features
raise at
put_modelorstep, andnoslipis silently dropped. Make an_mjx.xmlvariant with primitives and pruned pairs, then compare CPU and GPU rollouts. - Using
mujoco_py,mujoco.load_model_from_path, or Gymnasium-v2/-v3envs: legacy APIs; usemujoco.MjModel.from_xml_pathand-v5. - Old tutorials'
composite/cableplugin: removed in 4.0; use 1Dflexcomp.
Checklist
-
<compiler angle="radian">set (or all angles verified as degrees);meshdircorrect -
<option>:integrator="implicitfast",timestepchosen deliberately, elliptic cone +impratiofor manipulation - Visual and collision geoms in separate default classes; collision uses primitives or
convex parts;
maxhullvertcapped - Masses and inertias plausible (render inertia boxes); no ratios beyond ~1000:1
- Every geared joint has
armatureanddamping; actuators haveforcerange -
ctrlrangeinside jointrange(except grippers); servo gains documented with source - No interpenetration at
qpos0and every keyframe (data.nconand contact distances aftermj_forward) - Control loop: substeps computed from
timestep,mj_forwardafter resets, named access - Observations from sensors, copied; contact sensors for touch/force
-
BADQACC/ non-finite state checked and treated as failure - Determinism test: two rollouts from the same keyframe and controls match exactly
- Headless runs set
MUJOCO_GLbefore import;offwidth/offheightlarge enough - GPU port:
put_modelsucceeds,nconmax/njmaxsized from measured peaks, overflow checked at episode boundaries, CPU vs GPU rollouts compared - Sim-to-real: armature, gains, friction and latency identified from logs before DR
- MuJoCo version pinned (Menagerie READMEs state minimum versions; 4.0 changed behaviour)
Related Skills
robot-reinforcement-learning: RL algorithms, reward design, DR ranges, sim-to-real theoryisaac-sim: the alternative GPU simulator stack (Isaac Sim / Isaac Lab)lerobot: SO-100/SO-101 hardware, datasets, and policies that pair with Menagerie modelsimitation-learning: policies trained from demonstrations collected in MuJoCorobot-data-quality: validating logged trajectories used for sysid and trainingrobotics-testing: simulation tests, determinism and golden-trajectory regression testsros2: bridging a MuJoCo sim to ROS 2 topics and controllers
Reference Files
Load on demand:
references/ecosystem.md: when picking a package or Menagerie model; full component table with install names and status, and the Menagerie arm list.references/mjcf-reference.md: when writing or reviewing MJCF in detail; attribute tables with verified defaults, actuator shortcut mappings, sensor list, URDF conversion recipe, and the full modelling-rules text.references/python-examples.md: when writing Python beyond the minimal loop; full loop semantics, reset andmj_getState/mj_setState, the passive viewer, the executed RGB/depth/segmentation example andMUJOCO_GLdetails, URDF import pitfalls andMjSpecediting.references/contacts-debugging.md: when a sim explodes, jitters, sinks, tunnels or slips, or when tuning a grasp; the ten-step tuning guide, collision geometry, the full symptom table, divergence detection and energy checks.references/gpu-batched-sim.md: when porting to MJX or MuJoCo Warp, sizing contact buffers, writing batched resets/DR, or reading Playground/rss2025 env code; includes the executed MJX and Warp examples.references/sim-to-real-model-fields.md: when randomising model fields at runtime, runningmujoco.sysid, or adding latency and noise models; includes the executed DR example.
Primary sources: mujoco.readthedocs.io (XML reference, Modeling > Model tuning, Computation,
Python, MJX, MuJoCo Warp), github.com/google-deepmind/mujoco (doc/changelog.rst,
doc/skills/), mujoco_menagerie, mujoco_playground, mujoco_warp.
Tips for Mujoco
- • Start a fresh session after installing so your agent picks up the new skill.
- • It bundles reference files. The agent reads them only when needed, so they cost no context until then.
- • It is part of a pack with 17 skills. Install only the ones you need with --skill to keep triggers precise.
- • If two skills overlap, mention the one you want by name.
Questions about Mujoco
What does the Mujoco skill do?
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.
How do I install Mujoco?
Run "npx alyn-cli add mujoco" in your project. The Alyn CLI installs it for Claude Code, Cursor, Codex and 70+ other agents. In Claude on the web, upload the skill folder as a ZIP under Customize > Skills.
Does Mujoco work in Cursor and Codex?
Yes. Mujoco uses the open SKILL.md format, so it works in Claude Code, Claude, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot and other agents that support agent skills.
What is inside the Mujoco skill?
The SKILL.md covers When to Use This Skill, Ecosystem Map, MJCF Essentials, Python Simulation Loop, Rendering, Contacts and Stability, and the skill folder has 7 files.
What is a good alternative to Mujoco?
PR by Matt Pocock is the highest-ranked similar skill from another creator, with an Alyn Score of 94 compared to 60 for Mujoco.
Is Mujoco free?
Mujoco is open source on GitHub under the Apache-2.0 license. It is free to install; check the license before commercial use.
Who made Mujoco?
Mujoco is published by arpitg1304 in the arpitg1304/robotics-agent-skills repository, together with 16 other skills.


