claude-ros2-skills

Claude Code Skills for ROS 2 Jazzy Jalisco robotics development.

Skills that transform how AI agents approach ROS 2 development: identify unknown parameters upfront, verify settings against installed packages, and confirm execution through working evidence.

English | 한국어 | 中文 | 日本語 | Español | Français | Deutsch

Skills	Always-loaded protocol	Doc links (CI-checked)	Physical robot checks	Evals: Gazebo A/B
11	26 lines	32	4 scripts	goal reached vs. bringup abort

Contents

• The failures that cost you
• How these skills are built
• What makes this different
• Evals
• Quickstart
• Skills
• Verification scripts
• How it works
• Updating
• Roadmap
• Contributing
• License

The failures that cost you

The most costly errors in AI-generated ROS 2 code are rarely syntax mistakes. Instead, they are subtle issues that appear correct at first glance:

Neither compilers, linters, nor log analyses detect these hidden issues. Resolving each error requires an extra feedback cycle: reviewing output, diagnosing the cause, explaining the fix, and re-generating code.

How these skills are built

Four design rules govern every skill in this repository:

1. Identify unknown variables upfront. Key operational details often do not exist in documentation — such as whether the environment is real hardware or simulation, whether to extend an existing workspace or create a new one, which node already publishes a transform, or the robot's precise geometry. CLAUDE.md instructs the agent to clarify these unknowns before generating code. Domain-specific skills manage targeted parameters; for example, ros2-dev requests the robot footprint, drive kinematics, and localization source before configuring any Nav2 parameters.

2. Execute a structured loop with clear exit criteria. Every skill follows a verify → write → prove cycle: inspect system defaults on the installed environment, apply incremental changes, and confirm execution. A task completes only when supported by observed evidence — such as a successful build, active data on ros2 topic echo, or a passing verification script — rather than simply producing code files.

3. Prioritize structured failure tables over long descriptions. Structured tables mapping symptoms → root causes → corrective actions provide clear, durable guidance that official documentation often lacks and that remains reliable across release versions:

[ is GZ→ROS, ] is ROS→GZ · 16UC1 is millimeters, 32FC1 is meters · joint_state_broadcaster is not spawned automatically · raytrace_max_range ≤ obstacle_max_range means obstacles never clear · rclc does not auto-allocate unbounded message fields

4. Optimize context usage with a three-layer architecture. Each skill balances context efficiency: skill descriptions remain in context, skill bodies load when invoked, and deep reference files in references/ load only on demand. Large symbol catalogs and detailed parameter tuning tables reside in references/, ensuring context is preserved and debugging targeted components (like AMCL) does not load unnecessary documentation (like behavior-tree nodes).

What makes this different

Most robotics skill packs embed static API knowledge directly inside skill files. While initial usage is easy, this approach breaks when the underlying packages update — leaving outdated snippets that silently fail. This repository takes a dynamic, documentation-driven approach:

This repository optimizes for a single outcome: minimizing the risk of generating plausible-looking code that fails to run on ROS 2 Jazzy.

Evals

Every result below comes from a measured A/B pair: the identical prompt run in fresh, headless Claude Code sessions — once without these skills, once with them — using the same model in both cells. Outputs were graded symbol-by-symbol against pinned upstream Jazzy sources, then against a live /opt/ros/jazzy installation, then by loading both outputs into a live Gazebo simulation, and finally by executing the generated nodes against running publishers. Every task in the suite now has a live-install measurement. Full transcripts, generated code, and run logs are committed under evals/runs/, and the harness that produces the pairs is in evals/harness/, so anyone can re-grade or re-run without trusting us.

Sample size is n=1 per cell and the runs were graded by the same project that publishes them; grading is mechanical wherever possible (does the symbol exist in the install? does the command succeed?) so it can be checked independently.

Nav2 MPPI configuration — Haiku, live Jazzy install

Prompt: set up Nav2 with the MPPI controller for a differential-drive robot on Jazzy and produce the controller server YAML.

A package that must actually run — Haiku, in-container

Prompt: create a Python package demo_pkg publishing std_msgs/msg/String on /greeting at 1 Hz with a launch file; build it and show ros2 topic echo /greeting.

Sensor subscription — Haiku, both nodes executed against a live publisher

Prompt: write a Jazzy Python node that subscribes to /scan and logs the minimum range once per second. Both generated nodes were then run for 6 s against a BEST_EFFORT /scan publisher.

An earlier round of this same pair is what produced the fix: both nodes then filtered only inf, so the with-skills node reported 0.020 m — connected, but confidently wrong. ros2-core gained the bounds rule and the shutdown pattern, and the re-run above is the verification that the patch changed the output. Both tables are in evals/RESULTS.md.

Asking before writing — Haiku, inverted LiDAR mount

Prompt: my LiDAR is mounted upside-down on the back, facing backward; write the static TF and tell me how to confirm it.

What the skills do not fix

Reported because leaving it out would make the rest less trustworthy:

• A rule only exists if the router loads the file it lives in. On the QoS-diagnosis task, two runs of the identical prompt routed to different skills — ros2-core once, ros2-perception the next. ros2-perception's examples are exclusively C++, and it is the only skill with no Python content; asked for a Python fix with nothing but rclcpp:: in context, the answer came back using rclcpp.qos in Python, which raises ModuleNotFoundError. The baseline, with no skill loaded at all, got that API right. This is the one measured case of the pack making output worse, and the cause is skill content, not the model.
• Hallucination moves, it does not stop. Every measured round has contained invented symbols in with-skills output — a non-existent package for this repo's own script, a wrong default durability, missing range bounds, a Python module that doesn't exist. Routing to docs raises the floor; it does not make the model correct.
• On problems the model already knows cold, skills cost more and buy little. For the classic QoS-mismatch diagnosis, both conditions were right in one turn and the with-skills side cost ~1.4× while adding an error.
• Skills change what the agent asks, more reliably than what it checks. Across four with-skills cells on that task, with a live reproduction running and Bash allowed, none ran the ros2 topic info -v they recommended. The verify-before-writing half does fire — on Task 1 the agent ran ros2 interface show first — but "prove it afterwards" does not reach diagnosis answers.

The pattern across every pair

No baseline cell in any run verified against the installed packages or the docs before writing, even when WebFetch, Read, and Bash were explicitly allowed — and one baseline reported a fully working build for a package ros2 run cannot find. With-skills cells asked the pre-write gate questions in every run where the task had unknowns, and their claims matched independent re-execution. The verification scripts have now been exercised on live data in both directions: check_qos_compat.py produced its first real [FAIL] against a genuine BEST_EFFORT/RELIABLE mismatch, and check_tf_tree.py flagged an inverted sensor while leaving a correctly-mounted one alone.

Review full evaluation tables, test environments, and individual run analyses in evals/RESULTS.md. For details on the evaluation protocol, task checklists, and container setup, see evals/README.md. Pull requests containing additional graded transcripts are welcome.

Quickstart

Option A — Plugin Marketplace (Recommended):

/plugin marketplace add Leehyunbin0131/claude-ros2-skills
/plugin install claude-ros2-skills@claude-ros2-skills

Update installed plugins anytime with /plugin marketplace update.

Option B — Manual Installation:

git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git

# Project-level installation (applies to the current project only)
mkdir -p your-project/.claude/skills
cp -r claude-ros2-skills/skills/* your-project/.claude/skills/
cp claude-ros2-skills/CLAUDE.md your-project/

# User-level installation (applies across all projects)
mkdir -p ~/.claude/skills
cp -r claude-ros2-skills/skills/* ~/.claude/skills/

Restart Claude Code (or start a new session) to apply the installed skills.

Skills

Verification scripts

These verification scripts are bundled within the ros2-troubleshooting skill (skills/ros2-troubleshooting/scripts/) and are included with every installation. They convert physical hardware checks into executable pass/fail verification steps (requires a sourced ROS 2 environment; return codes: 0 = PASS, 1 = FAIL, 2 = NO DATA):

The core decision logic is unit-tested independently of ROS (python3 skills/ros2-troubleshooting/scripts/test_checks.py) and runs via continuous integration (CI) on every push.

How it works

flowchart LR
    A["your request"] --> B["CLAUDE.md<br/>protocol + gates,<br/>no API details"]
    B --> C["skills/&lt;name&gt;/SKILL.md<br/>gates, loop,<br/>failure tables"]
    C --> D["/opt/ros/jazzy/<br/>or official Jazzy docs"]
    C -.only if needed.-> R["references/<br/>symbol catalogs,<br/>tuning tables"]
    D --> E["code, then proof it ran"]
    R --> E

CLAUDE.md contains no specific API details. Instead, it establishes the operational protocol and requires clarifying questions to be answered before writing code. Each SKILL.md file manages domain-specific decisions: identifying unknown variables, executing the verify-write-prove loop, and referencing failure tables. Detailed reference materials are stored separately in the references/ directory. See CLAUDE.md for details.

Updating

cd claude-ros2-skills
git pull
cp -r skills/* ~/.claude/skills/   # or your project's .claude/skills/

Roadmap

1. Automate evaluation pairs inside ros:jazzy containers — done (2026-07-25): Task 4 re-run against a live /opt/ros/jazzy install; results in evals/RESULTS.md.
2. Publish Task 5 evaluation results — done (2026-07-25): binary build/run/echo outcome measured in-container; results in evals/RESULTS.md.
3. Extend live-install evaluations to Tasks 1–3 — done (2026-07-26): run against a native ros-jazzy-ros-base install, with both generated nodes executed against live publishers; harness in evals/harness/, results in evals/RESULTS.md.
4. Fix the defects those runs exposed — done (2026-07-26): ros2-troubleshooting now states the literal script invocation (the model was inventing a package for it) and that check_tf_tree.py always flags a ~180° mount for physical confirmation; ros2-core gained the range_min/range_max bounds rule and a clean-shutdown pattern. The eval tables measure the skills as they were before these fixes.
5. Re-run Tasks 1–3 against the patched skills — done (2026-07-26): two of three defects corrected near-verbatim and Task 1 now reports the right minimum at runtime; the third task regressed for a traceable reason (see item 6).
6. Duplicate the client-library guardrail across skills. rclpy is mentioned in exactly 1 of 11 skills, so a Python question routed anywhere else has only C++ examples in context. Either state the C++/Python separation locally in every skill that shows client-library code, or promote it into CLAUDE.md where routing cannot miss it. ros2-perception also needs Python cv_bridge examples, not only C++ ones.
7. Measure the routing distribution. Which skill gets selected varies between identical runs, and at n=1 that variance sits underneath every number in the eval tables.
8. Make Task 3 discriminating — require the QoS diagnosis to be demonstrated against live endpoints, not recommended, since both conditions currently answer it correctly from memory.
9. Track "corrections-to-completion" as a core metric — measuring the number of feedback iterations required before code runs successfully.
10. Implement deterministic references/ lookups to ensure detailed reference documents load whenever relevant.
11. Expand the body/references split to ros2-core and gazebo-sim, optimizing context efficiency for high-frequency skills with substantial reference documentation.

Contributing

Summary: Skill files must focus on decision logic (validation gates, loop steps, and failure tables), while detailed documentation stays in references/. Every API symbol must be verified against official Jazzy documentation or /opt/ros/jazzy/ installations. Verification scripts must maintain pure logic that can be unit-tested without ROS dependencies. For full guidelines, skill and script checklists, and issue templates, see CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.