⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.2.0

ros2-development

leehyunbin0131@leehyunbin0131⭐ 20 stars· last commit 9d ago· 0 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 20 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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

ROS 2 Ubuntu License

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

SkillWhen it helpsWhat it adds
ros2-developmentCreating or modifying packages, nodes, interfaces, launch/config and testsDependency-aware builds, installed-artifact verification, a check that rejects empty test runs, and an optional evidence tracking tool for task handoff
ros2-troubleshootingA live publisher, callback, TF, IMU or odometry behaves incorrectlyFour executable diagnostics and focused frame, runtime and calibration references
ros2-microrosMCU transport, agent, rclc or message memory workSource 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.

ScriptEvidence 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 / inspectOpt-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 /scanNative Jazzy QoS compatibility for discovered publisher/subscriber pairs
ros2-troubleshooting/scripts/check_tf_tree.py --sensors laser_frame,imu_linkTF connectivity and mounting RPY for physical comparison; an unusual angle is an advisory
ros2-troubleshooting/scripts/check_imu_gravity.py --topic /imu/dataMeasured 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 /odomFresh 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

// REPO STATS

20 stars
0 open issues
Last commit: 9d ago