---

name: contribution-maintenance description: "Contributor and maintainer workflow guidance for MuJoCo Menagerie checks, formatting, license regeneration, gallery updates, and safe test selection." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Contribution Maintenance

Use this sub-skill when the user is preparing, reviewing, or repairing a MuJoCo Menagerie contribution and needs the repo's maintainer checks, generated-file workflows, or contribution policy. Keep this sub-skill focused on contribution hygiene and CI-equivalent validation.

Route boundaries

• Route model choice, directory anatomy, category selection, MJX availability, and catalog questions to model-catalog.
• Route direct XML loading, mujoco.viewer, robot_descriptions, compile errors, and short simulation smoke tests to model-loading.
• Route MJCF composition, attachment sites, PD gains, keyframes, mirrored hands, and other advanced editing plans to model-editing.
• Stay here for make install, make check, make test, make gallery, make all, pre-commit hooks, XML formatting, top-level license regeneration, README gallery maintenance, changelog/contributor/CLA policy, and choosing an efficient validation subset from changed paths.

Inputs to collect

1. Repo root or exported Menagerie checkout to validate.
2. Changed paths, or a Git base/ref from which changed paths can be computed.
3. Whether writes are allowed for formatting, license regeneration, or gallery rendering.
4. Test budget: targeted checks only, full local make all, or gallery render as well.
5. Contribution type: existing model edit, new model directory, tooling/test change, docs-only change, or license/contributor update.

Fast decision table

Change type	Minimum local checks	Escalate when
One or more *.xml files	Run the Menagerie XML formatter in --check or --write mode, then run structural/layout checks for the affected model directory and a selected compile/step smoke through model-loading.	Scene XML, asset references, actuator definitions, or includes changed; run full make test if many directories changed.
A model LICENSE changed or a model directory was added/removed	Regenerate or check the top-level LICENSE; run make check; run structural tests.	The generated top-level license diff is unexpected, a base license cannot be found, or several model licenses changed.
New model directory	Confirm README.md, LICENSE, CHANGELOG.md, one or more *.xml, and normally scene*.xml; update changelog/contributors; update gallery model map when it should appear in the README gallery; run make all.	Sensor-only or non-standalone assets may not need scene*.xml; route catalog/layout judgment to model-catalog.
Gallery entry, category, preview, or thumbnail changed	Run make gallery when writes are allowed; inspect README.md and assets/*.png diffs; then run selected loading checks for affected XMLs.	Rendering dependencies or MuJoCo/OpenGL fail; route loading/runtime errors to model-loading.
Tooling, tests, Makefile, or pre-commit config changed	Run make check and make test (make all); compare with the GitHub workflow command.	CI differs from local output, pytest parallelism changes, or hook configuration changed.
Changelog or contributors changed	Ensure the proper global or per-model changelog was updated; keep contributors sorted alphabetically by first name; run pytest test/model_dir_test.py::ContributorsTest -q when contributors changed.	Contribution ownership or CLA status is unclear; the user must resolve CLA outside the repo.

Commands to know

From a Menagerie checkout root:

make install   # one-time: install pre-commit and the git hook via uv
make check     # pre-commit run --all-files: lint, format, license, XML checks
make test      # manual pre-commit pytest hook over model + structural tests
make gallery   # render thumbnails and update README gallery
make all       # make check followed by make test

Bundled helpers in this sub-skill:

python scripts/menagerie_checklist.py path/to/changed.xml path/to/LICENSE
python scripts/format_mjcf_xml.py --check path/to/file.xml
python scripts/format_mjcf_xml.py --write path/to/file.xml
python scripts/check_menagerie_license.py --root /path/to/checkout --check
python scripts/check_menagerie_license.py --root /path/to/checkout --write

Use the repo's own format_xml.py, regenerate_license.py, and generate_gallery.py when operating inside a current checkout; use the bundled helpers when you need portable behavior or a scoped plan outside the source checkout.

Required references

• Contributor setup, make/pre-commit/CI mapping, changelog/contributor/CLA rules, and check selection: references/contributor-workflows.md
• XML style, formatter behavior, and safe formatting commands: references/xml-formatting.md
• Gallery generation, model map expectations, and write-heavy rendering cautions: references/gallery-workflow.md
• Common maintainer workflow failures and fixes: references/troubleshooting.md

Validation pattern

1. Run the checklist helper on changed paths to choose the smallest adequate checks.
2. If writes are allowed, apply formatter/license/gallery regeneration before running checks; otherwise use --check modes and report exact commands needed to fix generated files.
3. For model XML compile/step validation, route to model-loading and request a selected smoke rather than running the full model suite by default.
4. Before declaring ready, report which of make check, make test, make all, selected structural tests, selected loading smoke, license check, and gallery render were run or intentionally skipped.

Two difficult usability cases

• Edited one model XML and license: format only the changed XML, check/regenerate the top-level LICENSE, run structural tests for the model directory, then route one selected scene compile/step smoke to model-loading; do not run make gallery unless the gallery-facing XML, thumbnail, category, or README gallery changed.
• Added a new model directory: require README.md, LICENSE, CHANGELOG.md, model XML, normally scene*.xml, assets/meshes as referenced, per-model changelog and contributor entry, top-level LICENSE regeneration, gallery MODEL_MAP/category/preview updates when it should be listed, and full make all before PR readiness.