# ros2-development

Adopt this skill: https://proskills.md/skills/other/leehyunbin0131-claude-ros2-skills-skills-ros2-development

Page: https://proskills.md/skills/other/leehyunbin0131-claude-ros2-skills-skills-ros2-development
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/ros2-development/SKILL.md
size: 6086
upstream: https://github.com/leehyunbin0131/claude-ros2-skills/blob/main/skills/ros2-development/SKILL.md

````text
---
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).
````

## File: README.md
upstream: https://github.com/leehyunbin0131/claude-ros2-skills/blob/main/README.md

````text
<div align="center">

<img src="assets/hero.png" alt="ROS 2 Jazzy skills for Claude Code and Codex" width="100%"/>

**Contextual packaging of ROS 2 verification tools, workflows, and handoff evidence.**

![ROS 2](https://img.shields.io/badge/ROS%202-Jazzy-22314E?logo=ros&logoColor=white)
![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04%20LTS-E95420?logo=ubuntu&logoColor=white)
![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)

**English** | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md)

</div>

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](https://agentskills.io/home). 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:**

```bash
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](https://learn.chatgpt.com/docs/build-skills) 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](CLAUDE.md), 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](evals/CODEX.md).

**Plugin — from a Claude Code session:**

```text
/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](CLAUDE.md);
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:**

```bash
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:

```bash
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](skills/ros2-development/SKILL.md) | 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](skills/ros2-troubleshooting/SKILL.md) | A live publisher, callback, TF, IMU or odometry behaves incorrectly | Four executable diagnostics and focused frame, runtime and calibration references |
| [ros2-microros](skills/ros2-microros/SKILL.md) | 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: `/scan` publishes, 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
````
