---

name: builtin-envs description: "Choose and troubleshoot Gymnasium built-in environment families, optional extras, registry IDs, action masks, and render modes." disable-model-invocation: true metadata: disco-role: operating license: MIT

Gymnasium Built-in Environments

Use this sub-skill when a task involves selecting or using Gymnasium's built-in environment families, deciding which optional extra is needed, inspecting registered environment IDs, handling Toy Text action masks, or diagnosing backend/render/plugin failures.

Start Here

• Choose the smallest environment family and optional extra that matches the task; avoid gymnasium[all] unless a disposable environment explicitly needs every backend. See references/optional-dependencies.md.
• Inspect availability before installing anything: use gym.spec("CartPole-v1"), gym.registry, or gym.pprint_registry(); see references/builtin-environments.md.
• Use versioned IDs exactly, including namespaces such as phys2d/CartPole-v1 or plugin namespaces such as ALE/...; do not guess unversioned names.
• For Taxi action masks and render mode choices, use references/action-masking-and-rendering.md and the bundled scripts/action_mask_smoke.py.
• For missing pygame, Box2D, MuJoCo, ALE/ROMs, shimmy, or media dependencies, use references/troubleshooting.md before broad installs.

Route by Task

Task	Read
Pick a built-in family or verify an env ID	references/builtin-environments.md
Decide the minimal package extra	references/optional-dependencies.md
Use Taxi action masks or render modes	references/action-masking-and-rendering.md
Diagnose backend, plugin, ROM, ID, or compatibility errors	references/troubleshooting.md
Prove Taxi action-mask support locally	scripts/action_mask_smoke.py

Minimum Correct Patterns

import gymnasium as gym

spec = gym.spec("CartPole-v1")
print(spec.id, spec.max_episode_steps, spec.entry_point)

env = gym.make("CartPole-v1")
obs, info = env.reset(seed=123)
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
env.close()

import gymnasium as gym

env = gym.make("Taxi-v4")
obs, info = env.reset(seed=123)
mask = info.get("action_mask")
action = env.action_space.sample(mask) if mask is not None else env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)
env.close()

Scope Boundaries

• Use ../environment-api/SKILL.md for generic Env loops, custom environment classes, registration, check_env, and old Gym reset/step migration.
• Use ../vectorization/SKILL.md for gym.make_vec, vectorized built-in environments, batched actions, vector wrappers, and autoreset behavior.
• Use ../wrappers-recording/SKILL.md for RecordVideo, wrapper chains, recording episode statistics, and media wrapper ordering.
• Use ../spaces-data/SKILL.md for detailed space constructors, contains, flattening, dtypes, and shape debugging.

Keep runtime guidance self-contained. Do not depend on Gymnasium source, tests, examples, documentation paths, or local checkout paths at runtime.