---

name: custom-components description: "Use RL Baselines3 Zoo custom Gymnasium registrations, wrappers, callbacks, schedules, and algorithm registry patches safely." disable-model-invocation: true metadata: disco-role: operating license: MIT

custom-components

Use this sub-skill when a future Researcher needs to register custom Gymnasium environments, validate wrapper/callback/policy import strings, use RL Zoo's bundled wrappers and callbacks, configure linear schedules, or patch the in-process algorithm registry for SBX or another Stable-Baselines3-compatible algorithm class.

Start here

1. Decide what kind of component is involved:

   • Custom environment package or env id: read custom envs, wrappers, and callbacks.
   • env_wrapper, vec_env_wrapper, callback, policy, or schedule entries: read custom envs, wrappers, and callbacks.
   • API signatures and constraints: read API reference.
   • Failure diagnosis: read troubleshooting.

2. Validate import strings before launching training:

   python scripts/component_import_checker.py \
     --wrapper rl_zoo3.wrappers.HistoryWrapper \
     --callback rl_zoo3.callbacks.RawStatisticsCallback \
     --policy stable_baselines3.ppo.MlpPolicy
   

3. If components are declared in a YAML hyperparameter file, list and validate them without creating an environment:

   python scripts/component_import_checker.py \
     --config ./my_hyperparams.yml --env CartPole-v1
   

Operating checklist

• Import custom Gymnasium registration modules before RL Zoo checks gym.envs.registry; for installed-package training this is normally python -m rl_zoo3.train --gym-packages my_env_package ... or rl_zoo3 train --gym-packages my_env_package ....
• Keep custom registration modules import-only: their top-level code should call Gymnasium register(...) and avoid training, network calls, credentials, or heavy initialization.
• Validate every dotted import string as module.submodule.ClassName. Exact case matters, and the module must be importable in the same Python environment that runs RL Zoo.
• For wrappers, verify constructor kwargs and environment-space requirements before training. HistoryWrapper, action wrappers, and MaskVelocityWrapper assert on observation/action-space shape or supported env ids.
• For callbacks, verify constructor kwargs and runtime prerequisites. RawStatisticsCallback needs TensorBoard logging; ParallelTrainCallback is limited to SAC/TQC models.
• Treat SBX/JAX and external simulator packages as optional dependency surfaces; confirm they are installed before proposing commands that depend on them.

Boundaries and routes

• Full YAML/Python hyperparameter-file grammar, indentation rules beyond wrapper/callback examples, --conf-file, and --hyperparams: route to ../config-hyperparams/SKILL.md.
• Actual training/resume/evaluation command execution after components are validated: route to ../training-cli/SKILL.md.
• Hyperparameter-optimization callbacks and Optuna trial behavior: route to ../tuning-optimization/SKILL.md.
• Package install, console-entry optional plotting import behavior, and optional simulator dependencies: route to ../../references/install-and-environment.md.

Minimal safe workflow

# 1) Validate component imports and constructor kwargs only.
python scripts/component_import_checker.py \
  --config ./my_hyperparams.yml --env MyEnv-v0 --gym-package my_envs

# 2) If validation passes, hand off the actual run to training-cli.
python -m rl_zoo3.train --algo ppo --env MyEnv-v0 \
  --gym-packages my_envs --conf-file ./my_hyperparams.yml \
  --n-timesteps 1000 --log-folder ./runs/rl-zoo --device cpu

Do not train from this sub-skill unless the caller explicitly asks to execute the validated training workflow; otherwise hand off to ../training-cli/SKILL.md.