⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
ros2-development
Implement or change ROS 2 Jazzy packages, nodes, interfaces, launch files and configuration in a colcon workspace. Use for building and validating a development change, including tests that report success without running. For a live QoS, TF, IMU or odometry fault, use ros2-troubleshooting.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Contextual packaging of ROS 2 verification tools, workflows, and handoff evidence.
English | 한국어 | 中文 | 日本語 | Español | Français | Deutsch
Three skills for Claude Code and Codex, targeting Ubuntu 24.04 / ROS 2 Jazzy: develop packages, verify tests and installed behaviour, and diagnose runtime faults.
This repository packages contextual domain guidance, workflows, and executable diagnostics under the Agent Skills standard. Rather than claiming to enhance the intrinsic code generation capabilities of frontier language models, this project explores an engineering hypothesis: packaging environment-specific evidence checks and structured handoff records can reduce verification ambiguity and context-transfer overhead between sessions or collaborators. While individual tool functionality is validated on test fixtures, reduced handoff cost and overall developer productivity gains remain unproven.
Quickstart
Choose your assistant. Automatic skill discovery is supported across environments. For Claude Code, choose either plugin or manual installation.
Codex — native skills for an existing project:
git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git
python3 claude-ros2-skills/scripts/install.py --agent codex --project /path/to/your-workspace
# Alternative: install for this user across all projects
# python3 claude-ros2-skills/scripts/install.py --agent codex --user
The Codex skill locations are
<project>/.agents/skills and ~/.agents/skills for these two scopes. Choose one
scope to avoid duplicate skill names. Each installed Codex skill includes the
shared verification protocol, loaded when that skill is used.
Existing AGENTS.md, CLAUDE.md, Codex configuration and unrelated skills are preserved;
local edits stop an update. Start a new Codex session in the target workspace. To select a skill explicitly
in Codex CLI or the IDE, use $ros2-development or $ros2-troubleshooting.
In the desktop skill picker, select the same skill by name.
Live ROS checks also need access to the intended ROS graph. In a restricted
Codex environment, a denied ROS log directory can be redirected with
ROS_LOG_DIR to a writable workspace directory. Discovered topics with no
received messages can reflect sandbox/DDS transport constraints. Keep the
workspace's domain and discovery scope; widening discovery to SUBNET is not a
general installation fix. Report unavailable observations as inconclusive.
See the observed Codex runtime limitations.
Plugin — from a Claude Code session:
/plugin marketplace add Leehyunbin0131/claude-ros2-skills
/plugin install claude-ros2-skills@claude-ros2-skills
Start a new session. A SessionStart hook loads the protocol;
plugin-root CLAUDE.md is not automatically loaded on its own. The default user
scope applies to all projects. Prefer a project install when you want it limited
to a ROS workspace.
Claude Code manual — into an existing project:
git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git
python3 claude-ros2-skills/scripts/install.py --project /path/to/your-workspace
# Alternative: install for this user across all projects
# python3 claude-ros2-skills/scripts/install.py --user
The installer copies the skills and .claude/rules/ros2-verification.md.
It preserves existing CLAUDE.md files and unrelated skills, refuses to overwrite
local edits, and reports retired skill directories for manual review. Restart
Claude Code afterwards. ROS, colcon and robot drivers are not installed by this
pack; install the dependencies needed by your workspace. For these checks on an
existing Jazzy installation:
sudo apt install python3-colcon-common-extensions python3-pytest \
ros-jazzy-tf2-ros ros-jazzy-sensor-msgs ros-jazzy-nav-msgs
source /opt/ros/jazzy/setup.bash
Prefer Ubuntu/Jazzy's test-tool versions or a separately verified environment.
The tested Jazzy launch_testing plugin fails to start with pytest 9; our
ROS-sourced checks use Ubuntu's pytest 7.4.4. A runner crash is not evidence that
the implementation's assertions failed.
Skills
| Skill | When it helps | What it adds |
|---|---|---|
| ros2-development | Creating or modifying packages, nodes, interfaces, launch/config and tests | Dependency-aware builds, installed-artifact verification, a check that rejects empty test runs, and an optional evidence tracking tool for task handoff |
| ros2-troubleshooting | A live publisher, callback, TF, IMU or odometry behaves incorrectly | Four executable diagnostics and focused frame, runtime and calibration references |
| ros2-microros | MCU transport, agent, rclc or message memory work | Source pointers and troubleshooting guidance; not MCU-validated |
Both assistants can select a skill automatically from its description. To request it explicitly, mention its name in your task. Examples:
- “Use ros2-development to add a service to this existing Jazzy package. Build its consumers, run the relevant tests, and show that the installed node works.”
- “Use ros2-troubleshooting:
/scanpublishes, but my node's callback never fires. Find the incompatible endpoints and verify the correction.” - “The robot is level but its IMU is mounted upside down. Check gravity using the declared TF; distinguish a correct mounting transform from a real error.”
Specify hardware versus simulation and the workspace when known. The agent should establish genuinely missing robot geometry or existing publishers before making assumptions about them.
Verification scripts
Scripts ship with their respective skill. In command examples, ROS2_SKILL_DIR is an illustrative
variable set by the agent to the directory containing the loaded skill; it does not require user input.
They are plain Python files, not ROS packages to invoke with ros2 run.
| Script | Evidence it checks |
|---|---|
ros2-development/scripts/check_test_results.py <results> --packages <name> | Check executed, passing cases in fresh colcon reports; use --require-test PACKAGE::test_name for the changed behaviour, since linters alone can otherwise pass |
ros2-development/scripts/evidence.py begin / finish / inspect | Opt-in workflow: Records caller-declared command metadata and inspects watched file hashes and selected environment values for handoff |
ros2-troubleshooting/scripts/check_qos_compat.py --topic /scan | Native Jazzy QoS compatibility for discovered publisher/subscriber pairs |
ros2-troubleshooting/scripts/check_tf_tree.py --sensors laser_frame,imu_link | TF connectivity and mounting RPY for physical comparison; an unusual angle is an advisory |
ros2-troubleshooting/scripts/check_imu_gravity.py --topic /imu/data | Measured gravity on +Z in --base base_link after declared TF or --assume-aligned; requires ≥2 samples; RMS sample variation >1.5 m/s² (adjustable via --max-variation) or missing TF is inconclusive; neither mode proves physical stillness, and gravity cannot establish yaw |
ros2-troubleshooting/scripts/check_odom_direction.py --topic /odom | Fresh odometry before and after an externally observed movement; direction only, not distance calibration |
**Diagnostic exit codes: 0 PASS, 1 FAIL, 2 INCONCLUSIVE or inv
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/ros2-development/SKILL.md5.9 KBupstream ↗
--- name: ros2-development description: "Implement or change ROS 2 Jazzy packages, nodes, interfaces, launch files and configuration in a colcon workspace. Use for building and validating a development change, including tests that report success without running. For a live QoS, TF, IMU or odometry fault, use ros2-troubleshooting." --- # ROS 2 development Work from the workspace's actual package graph and installed artifacts. This skill supplies a development workflow, a check for empty test runs, and an optional evidence tracking tool for task handoff. It does not prescribe a new workspace layout or replace the project's build conventions. ## Build the affected package graph Use `colcon list` to identify package names and build types. Build the changed package and its workspace dependencies with `colcon build --packages-up-to <package>`. `--packages-select` alone does not build its dependencies. For a message or public API change, include affected consumers in the build and tests. Preserve the project's existing build/install flags and dependency versions. Build in a shell with the intended underlay, not the workspace's old overlay. Use a separate shell to source the resulting `install/setup.bash` and inspect `ros2 pkg prefix <package>`: otherwise an older installed copy can appear to validate the source change. ## Require tests to have run `colcon test` and `colcon test-result` can both succeed with zero tests. Use a fresh result directory so a previous passing report cannot satisfy this run: The variable `ROS2_SKILL_DIR` in the examples below represents the absolute path to the loaded skill directory. The agent sets this path internally based on where the skill was discovered and loaded; do not ask the user for this path. ```bash # After building, in the workspace root. Replace my_package with actual names. # For pytest packages; omit --python-testing pytest for other test frameworks. ROS2_SKILL_DIR="/absolute/path/to/ros2-development" # Set by agent to loaded skill directory. results="$(mktemp -d /tmp/ros2-test-results.XXXXXX)" colcon test --packages-select my_package --return-code-on-test-failure \ --python-testing pytest --test-result-base "$results" && python3 "${ROS2_SKILL_DIR}/scripts/check_test_results.py" "$results" \ --packages my_package --require-test my_package::test_changed_behavior ``` Replace `test_changed_behavior` with the actual regression test for the change; repeat `--require-test PACKAGE::ID` when more than one test is needed. It matches a full JUnit `classname.name` or a dot-delimited suffix, or a CTest name. Omitting a pytest `[parameter]` suffix selects that test's parameter group and requires at least one non-skipped case. The output lists observed test IDs and states. For ament CMake tests, the checker follows the current CTest wrapper's recorded JUnit path and checks the inner cases, even if that path was configured in the build directory. A passed wrapper cannot substitute for all-skipped inner tests. The bundled check uses installed `colcon test-result` and requires at least one non-skipped test in **each named package**, plus the requested tests. Exit **0** means those reports contain executed, passing tests; **1** means a recorded test or test-process failure/error; **2** means missing, empty or unparseable evidence. An ament CTest crash/timeout is a recorded failure. Colcon's Python `pytest.missing_result` placeholder alone is inconclusive: inspect the test log to distinguish a runner problem from a crash before editing the implementation. Without `--require-test`, even linters alone can satisfy the check. A test name does not establish assertion quality: choose a regression that would reject the reported defect, or exercise the changed behaviour with a runtime probe. Do not describe style checks or a vacuous smoke test as functional verification. It reads reports and sends no ROS commands. Keep the printed result directory when reporting a failure. Inspect `colcon test`'s own exit status and diagnostics as well; reports cannot clear an invocation error. A package intentionally without tests is not a failed implementation; state the missing coverage and verify its changed behaviour. For a Python package that uses pytest, pass `--python-testing pytest` to `colcon test` (or use the workspace's explicit equivalent). Do not rely on `setup.py`'s `tests_require` to select the runner: newer setuptools can ignore that field and colcon can select a different framework, collecting no tests. ## Verify the installed behaviour Choose the smallest runtime check that exercises the change. A successful build does not prove that a launch file, parameter file or executable was installed. Use [verification.md](references/verification.md) for the relevant artifact: Python/C++ nodes, interfaces, launch/config, or lifecycle and sensor behaviour. Check the observable result again after a correction; keep a failed probe separate from a confirmed defect in the implementation. ## Optional evidence tracking and handoff When handing off a task to another agent session or collaborator, the optional `evidence.py` tool can record snapshots and verify whether the recorded context remains unchanged at handoff time. See [references/handoff.md](references/handoff.md) for instructions on `begin`, `finish`, and `inspect`. This tool records artifact hashes and declared execution metadata; it does not run user commands and does not guarantee that the generated code is correct. ## Evidence The result checker is tested against passing, failing, empty and skipped reports, including fresh-directory separation in real Python and CMake colcon fixtures. This workflow provides diagnostic checks; an agent comparison has **not** established a performance gain from its prose. Official semantics: [package selection](https://colcon.readthedocs.io/en/released/reference/package-selection-arguments.html), [test](https://colcon.readthedocs.io/en/released/reference/verb/test.html), [test results](https://colcon.readthedocs.io/en/released/reference/verb/test-result.html).README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/leehyunbin0131-claude-ros2-skills-skills-ros2-development.md