gazebo-operator

name	gazebo-operator
description	Use when the user wants Codex CLI to inspect or control a running Gazebo simulation with natural language. Codex should act as the decision layer and must route execution through the bundled scripts instead of composing raw gz commands directly.

Gazebo Operator

Use this skill when the user wants natural-language control over a running Gazebo simulation from Codex CLI.

Workflow

1. Inspect first and read the current interfaces plus capabilities snapshot.
2. Convert the user request into one supported action object. Prefer the fixed actions when they fit. Otherwise use invoke_interface with an explicit interface card and payload.
3. Do not compose raw gz commands in the model output.
4. If the request mentions a natural-language target alias, call scripts/resolve_target.py --query "<text>" to retrieve ranked candidate cards.
5. Candidate cards include fields such as name, score, aliases, pose, has_cmd_vel, and has_odometry.
6. Use candidate cards plus interface cards to decide the final target and the final topic / service in the model. Do not let the script auto-pick weak matches.
7. After the target or interface is decided, prefer scripts/run_action.py as the single execution entrypoint. It performs inspect, execute, and verify internally.
8. When the request is already in natural language and maps to a known semantic pattern, scripts/run_action.py --request-text "<text>" may plan the action internally by selecting an interface and generating a payload.
9. For gz.msgs.* payload generation, prefer the local schema registry in references/gz_msg_registry.json. It is generated from the workspace gz-msgs proto sources and indexed by message type, token, and field path.
10. If there is no hand-written payload generator for the selected interface, fall back to registry-driven field matching against the schema field_paths.
11. Use --verbose only when you need the full inspect / execute / verify payloads for debugging.
12. Report a single concise execution line and the final success / failure outcome unless the user asks for detail.

Supported Actions

Read references/actions.md when you need the exact action shapes.

• pause_sim
• resume_sim
• step_sim
• list_entities
• get_entity_state
• set_pose
• set_velocity
• invoke_interface

Safety

Read references/safety.md when the request could be destructive or ambiguous.

Hard rules:

• Always inspect before planning.
• Always retrieve and decide the target before moving or driving an entity.
• For generic requests, prefer selecting a concrete interface card before execution.
• Never execute a raw gz command directly when a bundled script can do it.
• Ask for clarification when target resolution is ambiguous.
• Ask for confirmation before resets, deletes, or bulk moves. Those actions are intentionally not implemented in v1.
• Always verify after pause_sim, resume_sim, step_sim, set_pose, set_velocity, and invoke_interface.

Execution Notes

• Run the scripts from the Gazebo project root when possible.
• If the project root is not the current working directory, set GZ_OPERATOR_PROJECT_ROOT.
• The scripts auto-detect install/setup.bash and install/bin/gz.
• For normal user-facing interactions, prefer one run_action.py invocation over multiple lower-level script calls.