--- name: mujoco-audit description: >- Audits, validates, and remediates MuJoCo 3D assets (MJCF model.xml, .mjz archives, or mjSpec models) using the 7-point static/PBR/mesh hygiene checker (--static_only), the 10-scenario physical test suite (audit_scenarios.py with --scenarios and --thresholds_json), and Before-vs-After comparison sheets. Use only when the user explicitly names MuJoCo, MJCF, .mjz, or mjSpec to audit, validate, or fix a MuJoCo asset. Don't use for non-MuJoCo 3D mesh/CAD/USD linters. metadata: publisher: google --- # MuJoCo Asset Audit, Verification & Remediation Skill Use this skill whenever you need to **audit, triage, validate, or remediate** a MuJoCo MJCF asset (`model.xml` or `.mjz` archive)—whether running a read-only diagnostic check, performing a fast or deep remediation of an existing asset, or verifying a newly created asset from [`blender-creation/SKILL.md`](../blender-creation/SKILL.md). For the canonical MJCF authoring rules referenced below (§1–§8: coordinate frames, naming, groups `2`/`3`/`4`, hand-authored convex hulls & analytic primitives vs. `coacd` fallback, mass/inertia, contacts/joints, and PBR materials), consult [`rules/mujoco_asset_standards.md`][asset-standards]. > [!IMPORTANT] > > **Protect Your Context Window**: > * Read **only this `mujoco-audit/SKILL.md` upfront** (`1` `read_file` call). Do **NOT** read all of [`rules/mujoco_asset_standards.md`][asset-standards] upfront—first run `audit_scenarios.py` (§2) and consult [`rules/mujoco_asset_standards.md`][asset-standards] **only on demand** for the specific section(s) that fail. > * Do **NOT** read the `.py` implementation source of [`scripts/audit_scenarios.py`](scripts/audit_scenarios.py) or [`../mujoco-showcase-shot/scripts/render_showcase_shot.py`](../mujoco-showcase-shot/scripts/render_showcase_shot.py)—all CLI flags and Python return schemas are documented below. -------------------------------------------------------------------------------- ## 0. Subagent Orchestration & Audit Configuration ### Canonical User Prompt Template Users invoke this skill with the **Zero-Jump, Paste-at-the-End** configuration block (all defaults are pre-filled above; the user pastes their target asset path and any optional notes on the last line, and any overrides written on that last line take precedence over the defaults above): ```markdown Audit and remediate MuJoCo MJCF asset using mujoco-audit: - Action: Audit & Fix # or: Read-Only Triage - Depth: Full # or: Fast - Articulations: Keep # or: Rigid-Only | Skip Passive Variant Target(s) & optional notes: ``` ### Orchestration Rules (Parent Conversation vs. Worker Subagent) 1. **If you are the top-level / parent conversation**: * Spawn a `self` subagent (`Model: "inherit"`) via `invoke_subagent` to execute this skill on the target asset(s), passing all user-specified knobs (`Action`, `Depth`, `Articulations`, `Passive Mechanism Variant`, and `Known Issues / Custom Focus`), your `Parent Conversation ID: `, and instructing the subagent to read this `mujoco-audit/SKILL.md` first (consulting [`rules/mujoco_asset_standards.md`][asset-standards] only on demand if a check fails). * **When the subagent finishes**: Present the remediated asset path (or triage verdict), a concise summary of the findings/fixes, and the verification renders/videos to the user. 2. **If you are already the spawned subagent (or running inside a Blender creation check)**: * Do **not** spawn a nested subagent—execute the audit/remediation directly. * **Scratch Hygiene**: Place all temporary scripts and intermediate files in `/scratch/` (never inside the repository working tree). -------------------------------------------------------------------------------- ## 1. Prompt-Knob Mapping & Pathway Selection **Do not treat every audit as a one-size-fits-all pipeline.** Map the user's prompt options (or natural-language instructions) directly to your execution: * **`Action`**: * **`Audit & Fix`** *(default)*: Diagnose all static and dynamic defects, remediate the asset in place (or in the requested output directory), verify the fix by re-running `audit_scenarios.py`, and render Before vs. After comparison panels. * **`Read-Only Triage`**: **Do not modify any asset files.** Run `audit_scenarios.py`, inspect both the `.json` scorecard and `.png` contact sheet alongside `model.xml`, and return a structured report stating: (1) Overall verdict (`PASS / Clean` vs. `NEEDS REMEDIATION`), (2) True modeling/physics defects, and (3) Disregarded geometry-expected flags. * **`Depth`**: * **`Full`** *(default)*: Evaluate all 7 static criteria (§3), run **all 10 physics scenarios (`--scenarios=all`)** Before and After remediation (plus any custom `MjSpec` mechanism probes via `uv run`), render a 6-view visual/collision inspection sheet + Before vs. After comparison sheet, and (when `Action == Audit & Fix`) render a 360° Filament PBR turntable video via [`mujoco-showcase-shot/SKILL.md`](../mujoco-showcase-shot/SKILL.md). * **`Fast`**: Prioritize speed and minimal iterations. Check the 7 static criteria (§3, or run `--static_only` for an instant `<0.5s` check) and run **only the 1–3 scenarios matching the object's geometry** via `--scenarios=...` (e.g., `--scenarios=1,3` for a solid prop, `--scenarios=1,4` for a container/loop, `--scenarios=1,6` for a hinged tool) so simulation finishes in `~1–2 s`. Render a single Before vs. After visual & collision overlay sheet, and **skip** `_mechanical` variants and **skip** `showcase_shot` turntable videos. * **`Articulations`**: * **`Keep / Upgrade`** *(default)*: Preserve/fix existing joints, or split welded movable parts (drawers, doors, hinges, casters) into articulated child bodies per [`rules/mujoco_asset_standards.md`][asset-standards] §7.2. * **`Rigid-Only (0 DoF)`**: Treat the asset as a single rigid body (`0` internal DoF). Consolidate/bake any internal child bodies or unwanted joints into the single root `` at `pos="0 0 0" quat="1 0 0 0"` while preserving world-space geom poses. Skip Scenario 6 and skip `_mechanical/`. * **`Passive Mechanism Variant`**: * **`Auto`** *(default)*: If the object has an important coupled passive mechanism (ratchet, release trigger, spring clutch) and `Depth != Fast` and `Articulations != Rigid-Only`, keep the clean direct-joint baseline in `/` and create `_mechanical/` per [`rules/mujoco_asset_standards.md`][asset-standards] §7.2. * **`Skip`**: Only build/remediate the primary `/` bundle. * **`Known Issues / Custom Focus`**: * Whenever the user specifies a symptom, target mass/dimension, or focus area (e.g., *"tongs don't pinch"*, *"hollow out mug"*), prioritize running the matching scenario(s) (`--scenarios=6`, `--scenarios=4`, etc.) and writing a targeted `MjSpec` probe for that exact requirement first. > **CRITICAL — Two-Tier Telemetry (`FAIL` vs. `INFO`) & Engineering Judgment**: > [`scripts/audit_scenarios.py`](scripts/audit_scenarios.py) uses a strict > two-tier design: > > * **Tier 1 — Genuine Unconditional `FAIL`s**: Only emit `FAIL` (or > `passed=False`) for unambiguous simulation/structural bugs: `NaN`/`Inf` > instability, high-speed thin-slab tunneling (`Scenario 10`), severe > resting hover or floor sink (`> max(3 mm, 3% min_span)` in `Scenario 1`), > missing component colliders or gross frame/scale mismatch > (`collision_alignment`), static XML/PBR/UV errors > (`static_and_mesh_hygiene`), compile-time `maxhullvert="64"` vertex > truncation (`maxhullvert_truncated_geoms`), broken articulation mechanics > (`Scenario 6`), or ``s placed in collision `group="3"` > (`Scenario 9`). > * **Tier 2 — Diagnostic `INFO` Telemetry (Interpret with Physical > Intuition)**: Context-dependent metrics (`c2v`/`v2c` millimeter > percentiles, `z_band_mass_density`, `com_height_pct_of_z_span`, > `hull_density_cv`, tilt slip/tip angles, roll settle time, cavity/ray > counts, grasp slip, cliff overhang %, and twin self-stack ratio) are > reported with `status: "INFO"` so you evaluate them against the object's > real-world geometry and materials rather than gaming arbitrary pass/fail > cutoffs: > * **Multi-material & composite objects** (e.g., a potted plant with a > dense pot base and airy upper foliage hulls, a weighted lamp, or a > metal-head tool with a plastic handle): Inspect `z_band_mass_density` > (`lower_third`, `mid_third`, `upper_third`) and > `com_height_pct_of_z_span` in `asset_info` / `Scenario 3`, and assign > physically realistic per-region densities (so `CoM_z` sits inside the > weighted base/pot) rather than forcing `hull_density_cv = 0` across > disparate materials. > * **Clean semantic convex hulls vs. sub-mm `c2v`/`v2c` chasing**: Once > your semantic convex hulls cleanly match the 6-view visual/collision > overlay (tightly following the silhouette with zero visual protrusion > and unobstructed functional cavities/openings), **stop iterating**—do > not burn extra script iterations chasing sub-millimeter chord or > percentile differences. > * **Spheres & Cylinders** (balls, cans, cylinders on their side) > naturally roll at small tilt angles on the tilt table (`Scenario 2`), > roll long distances (`Scenario 3`), roll off a cliff edge early > (`Scenario 7`), and slide off each other in a twin self-stack > (`Scenario 8`). > > Always inspect the JSON telemetry and the `.png` contact sheet together to > decide whether a metric reflects a **true modeling defect** or **expected > physics for that object**. -------------------------------------------------------------------------------- ## 2. Running the Static & Dynamic Audit Suite (`audit_scenarios.py`) Resolve `SKILL_DIR` to the directory containing this `SKILL.md` file. Bundled [`scripts/audit_scenarios.py`](scripts/audit_scenarios.py) declares its Python dependencies (`mujoco`, `trimesh`, `scipy`, `numpy`, `Pillow`, `absl-py`) via a PEP 723 `# /// script` header, so `uv run` automatically provisions and caches an isolated environment on first use: ```bash SKILL_DIR="/path/to/skills/mujoco-audit" # Fast (<0.3s) static XML, PBR material scalar-vs-layer, and .obj mesh/UV hygiene check: uv run "$SKILL_DIR/scripts/audit_scenarios.py" \ --xml_path=/path/to/model.xml \ --static_only # Run all 10 scenarios (default for deep audits or blind triage): uv run "$SKILL_DIR/scripts/audit_scenarios.py" \ --xml_path=/path/to/model.xml \ --out_dir=/audit_out \ --label= # Or run only a fast/targeted subset of scenarios (e.g. Scenarios 1 and 4): uv run "$SKILL_DIR/scripts/audit_scenarios.py" \ --xml_path=/path/to/model.xml \ --out_dir=/audit_out \ --label= \ --scenarios=1,4 ``` ### Customizing Thresholds (`--thresholds_json`) `DEFAULT_THRESHOLDS` in `audit_scenarios.py` are **configurable CLI heuristic defaults, not universal physical laws**. Override any threshold or scaling ratio via `--thresholds_json` whenever physically warranted for small, large, multi-material, or compliant/elastomeric objects: ```bash --thresholds_json='{ "hull_density_cv_tol": 0.30, "hover_tol_mm": 1.5, "bounce_ratio_tol": 0.45 }' ``` * **Configurable `DEFAULT_THRESHOLDS` CLI defaults**: `hover_tol_mm` (`2.0`), `min_flat_slip_deg` (`8.0`), `hull_density_cv_tol` (`0.15`), `max_residual_ang_speed_rad_s` (`0.25`), `plugged_cavity_rays_tol` (`12`), `plugged_cavity_deficit_mm_tol` (`8.0`), `plugged_through_holes_tol` (`3`), `grasp_lift_slip_mm_tol` (`25.0`), `grasp_shake_slip_mm_tol` (`20.0`), `ledge_overhang_diff_pct_tol` (`25.0`), `high_speed_drop_scale` (`6.0`), `thin_slab_min_dim_ratio` (`0.20`), `bounce_ratio_tol` (`0.35`). * **Never game `--thresholds_json` to mask collider defects**: Only adjust thresholds when justified by the real object's scale, material compliance, or multi-material composition. Never raise `plugged_through_holes_tol` or `plugged_cavity_rays_tol` to silence a `CHECK` on a functional handle opening, clip loop, or container cavity—fix the collision hulls (e.g., by decomposing a U-shaped clip or handle into clean left-arm, right-arm, and crossbar convex hulls) so the opening is genuinely unobstructed. * You can also add `"$SKILL_DIR/scripts"` to `sys.path` and call `audit_scenarios.validate_static_and_mesh_hygiene(xml_path)` or `audit_scenarios.run_all_scenarios_for_asset(xml_path, out_dir, label, thresholds={...}, scenarios="1,4")` directly inside any scratch Python script run via `uv run`. -------------------------------------------------------------------------------- ## 3. The 7-Point Static & Structural Audit Checklist Alongside dynamic simulation, verify these 7 structural rules from [`rules/mujoco_asset_standards.md`][asset-standards] (many of which are automatically checked by `audit_scenarios.validate_static_and_mesh_hygiene(xml_path)`): 1. **Model & root body naming + zero transform ([`rules/mujoco_asset_standards.md`][asset-standards] §2.2 & §3.2)**: Verify `spec.modelname` is a descriptive `snake_case` name (never `untitled` or a raw number), and verify there is a single top-level asset body in `spec.worldbody.bodies` with a descriptive `snake_case` name (never `root`, `blender_export`, `model`, `object`, `body`), zero position (`pos == [0, 0, 0]`), identity orientation (`quat == [1, 0, 0, 0]`), and no `` in the reusable `model.xml`. 2. **Canonical orientation, real-world dimensions (``), sensible origin & bidirectional collision alignment (`UP_POSZ_FORWARD_POSX_RIGHT_NEGY`, [`rules/mujoco_asset_standards.md`][asset-standards] §3.1 & §6.1)**: * **Real-world visual & dimension due diligence (reference product image, specs & `search_web`)**: * **Visual Comparison against Reference Photo**: Whenever a real-world reference photo or product image is provided, you **MUST visually compare** the rendered 6-view sheet of the updated asset against the **reference photo** to verify that the asset's **silhouette/shape, aspect ratio, primary & secondary colors/tint, surface markings/labels, transparency/opacity, and component structure** match the real physical object. Explicitly flag any color mismatch (e.g., red vs. orange, green vs. blue), wrong object substitution (e.g., lime vs. plastic egg), missing label/cap, or material/opacity discrepancy! * **Dimension & Spec Cross-Check (Guard Against "Similar Object" Web Overwrites!)**: Always cross-check `vis_span_cm` against reference product specs, `` metadata, and the reference photo. * **When to use `search_web` & rescale (``)**: Use `search_web` when you can identify the **exact brand/SKU/model** shown in the reference photo, **or** to check whether the asset has an obvious unit or capture scale bug (e.g., a `2×` scale error like a `45 cm` dinner plate or `13.5 cm` stress ball, or a `10×`/`100×`/`1000×` cm/mm-to-m unit error). * **NEVER overwrite a physically plausible real scan using a "similar" web listing**: When auditing a real physical object whose exact SKU/manufacturer cannot be confirmed, **do NOT rescale an already physically plausible asset** (e.g., changing a `14 cm` bowl to `18 cm` or applying non-uniform `sx != sy != sz` aspect distortion) just to match a generic or merely *similar* product found online—the physical scan and reference image are the primary ground truth! * **Function-First Collision Philosophy (Hand-Authored Convex Hulls & Primitives First, `coacd` Fallback When Needed)**: * **The collision geometry must serve the physical function of the asset**: Open containers must accept dropped objects, handle/clip loops must stay unobstructed for grasping, resting bases must sit flush without wobble, rollers must roll smoothly, and articulated links must clear each other across their full joint range. * **Prefer hand-authored convex hulls and analytic primitives first**: Decompose each rigid link by hand into clean analytic primitives (`sphere`, `capsule`, `cylinder`, `box`, `ellipsoid`) or per-part $\le 64$-vertex convex hulls (`bmu.export_convex_hull_col` or semantic sub-mesh slicing in `trimesh`). * **Fall back to `coacd` and tune its parameters when hand decomposition is too complex**: If an organic or intricately contoured mesh is too difficult to decompose by hand, run `coacd` (e.g., `uv run --with coacd --with trimesh python3 ...`) and actively tune `threshold`, `max_convex_hull`, `preprocess_mode` (`"auto"` vs. `"off"`), and `` until the hulls match the asset's function without plugging cavities or shattering closed walls. * Verify `+Z` is up, `+X` is front, `-Y` is right, the origin `(0, 0, 0)` sits sensibly at the base, centroid, or pivot, and inspect `asset_info["collision_alignment"]` in `