ros2-engineering-skills

Source version: 1.5.0. See release notes and release procedure.

Production-oriented ROS 2 engineering guidance for coding agents, with focused references, static validators, regression tests, and multi-distribution CI.

The skill covers workspace and package design, executors, DDS QoS, lifecycle, tf2, ros2_control, Nav2, MoveIt 2, perception, safety, runtime provenance, testing, and deployment. It distinguishes a plausible explanation from observed behavior.

Why this exists

A syntactically correct ROS 2 answer can still be operationally wrong: changing subscriber QoS without inspecting the publisher, editing an unused source YAML, assuming a zero topic command stopped the hardware, or using another distro's API. This skill routes work to relevant references and requires evidence for claims. It is not a robot safety certification or a substitute for an operator.

Before / After

These are illustrative comparisons of the intended workflow, not measured model outputs. Real paired evaluations require the captures described below.

Prompt: "My ROS 2 subscriber isn't receiving any sensor messages. Help me fix it."

# Guess at the fix before inspecting the live endpoints.
from rclpy.qos import qos_profile_sensor_data

sub = node.create_subscription(
    Image, '/camera/image_raw',
    callback, qos_profile_sensor_data)

ros2 topic list
ros2 topic type /camera/image_raw
ros2 topic info /camera/image_raw -v
ros2 node list --no-daemon

# Only after endpoint inspection supports this diagnosis.
from rclpy.qos import qos_profile_sensor_data

sub = node.create_subscription(
    Image, '/camera/image_raw',
    callback, qos_profile_sensor_data)

Prompt: "Create a C++ driver package for my LiDAR sensor."

my_lidar_driver/
├── src/main.cpp
├── CMakeLists.txt
└── package.xml

my_lidar_driver/
├── include/my_lidar_driver/my_lidar_driver_node.hpp
├── src/my_lidar_driver_node.cpp
├── src/main.cpp
├── launch/bringup.launch.py
├── config/params.yaml
├── test/test_driver.cpp
├── test/test_bringup.py
├── CMakeLists.txt
└── package.xml

Installation

Claude Code plugin

claude plugin marketplace add dbwls99706/ros2-engineering-skills
claude plugin install ros2-engineering@ros2-engineering-skills

Inside Claude Code the equivalent commands are:

/plugin marketplace add dbwls99706/ros2-engineering-skills
/plugin install ros2-engineering@ros2-engineering-skills

The plugin uses .claude-plugin/plugin.json, root SKILL.md, and hooks/hooks.json. It provides PreToolUse checks and advisory Stop reports. The hook command requires python3; it does not grant tool permissions.

Knowledge-only skill: Codex, Claude Code, Cursor, Gemini CLI

git clone https://github.com/dbwls99706/ros2-engineering-skills.git
cd ros2-engineering-skills
python3 -m pip install -r requirements.txt

python3 scripts/install_skill.py --client codex --dry-run
python3 scripts/install_skill.py --client codex
# Alternatives: --client claude, --client cursor, --client gemini
# Add --project /path/to/project for project scope.

Use a virtual environment as required by your Python installation. The installer copies a validated bundle, not client settings. Existing skills need --force; it stages the replacement before touching the old installation. It excludes Claude plugin manifests and hook registration intentionally. The portable files and manual validators do not require the Claude plugin.

Codex's optional display and invocation policy live in agents/openai.yaml. Supported discovery paths, explicit invocation, remote-environment caveats, and what has actually been tested are documented in Client compatibility. A documented discovery path is not proof of a successful authenticated model run on every client version.

The original ./install.sh and .\install.ps1 still support full-checkout copy/link installation, force replacement, and dry-run. A full checkout includes the Claude plugin manifest; it is not necessarily a knowledge-only installation when placed in Claude's skill directories. Prefer the new installer for that use.

Verify installation and run tools

python3 scripts/validate_skill.py --check-sources
python3 scripts/validate_skill.py --root /path/to/ros2-engineering-skills --installed --portable
python3 scripts/skill_validate_hook.py --file src/my_node.py
python3 scripts/skill_validate_hook.py --command 'ros2 topic list'
SKILL_WORKSPACE=/path/to/ros2_ws python3 scripts/skill_stop_hook.py

The command string above is inspected, never executed. Python 3.10+ is required; the CI matrix targets 3.10 through 3.14. Consult the run for the exact revision's results. Runtime dependencies are in requirements.txt; development dependencies are separate. Build and runtime checks additionally require the target ROS stack.

What is included

The selected SKILL.md contains a short operating contract and task router. Detailed tables and the 22 recurring pitfalls are retained in references/engineering-principles.md, loaded only when relevant. The context budget separates byte/line limits from measured, named-tokenizer counts.

The decision router in SKILL.md selects among 26 task-specific references plus cross-cutting engineering principles. Metadata is advertised before activation; the selected body and needed references supply the workflow. See Skill contract for scope, permission boundaries, protocol behavior, and context-budget limitations.

The JSON version emitted by the two validation hooks is the hook-report contract version, not the source bundle version. It changes only when that report contract changes; standalone utility versions follow the same independent-interface rule.

Verification levels

The canonical L0–L6 ladder defines evidence and preconditions from static review through supervised field operation. A passing software suite does not establish that a robot is safe to drive.

CI scope

CI retains lint/type checks, the full unit suite, Markdown lint, generated-package builds, installer tests, Claude plugin structure/component discovery, and Docker jobs for Humble, Jazzy, Kilted, Lyrical, and Rolling. It adds individual validator coverage floors, portable Windows installation, protocol integration, source-date checks, preregistered-suite checks, and a controlled QoS mismatch/repair experiment. Dependency vulnerability auditing is blocking, not advisory. The Required test gates summary rejects any required job that did not succeed.

ROS image construction and test execution are separate. Every run executes the suite in a fresh, network-isolated container; a cached image is not a test pass. Build/runtime logs, container state, and installed package versions are retained as workflow artifacts. The local command uses the same runner:

bash tests/run_ros2_tests.sh humble

See ROS CI and failure diagnosis.

Rolling retains its documented RMW runtime exclusions. A successful Rolling build is not a successful DDS runtime test. The stable-distribution QoS experiment runs without external networking or hardware in the built container. See QoS case study and quality gates. None of these jobs proves actuator safety, timing guarantees, or field behavior.

Independent local ROS acceptance

See local runtime validation for the transferable Humble environment and the independently executed package, lifecycle, component, QoS, callback-group, and parameter-provenance tasks. These are real software-runtime checks, not a claim of measured cross-model improvement or hardware safety.

Evaluation scope

Capture schema 2 retains timeouts, failed runs, empty answers, and missed skill activation instead of discarding unfavorable attempts. Capture integrity is not answer correctness; see the capture contract.

The default eval_runner.py checks whether expected-answer fixtures cover their declared criteria. It is not a model benchmark. Lexical coverage is not semantic correctness, and a fixture cannot substitute for an unmodified model capture.

evals/trigger_cases.json defines 33 activation cases: 17 implicit positives, 12 implicit negatives, and explicit invocation for four clients. evals/benchmark_suite.json defines seven quality cases with three trials and paired skill-on/off runs: 21 pairs, 42 fresh sessions per experiment. No fabricated captures or improvement percentages are included.

python3 scripts/verify_eval_capture.py /path/to/capture.json --suite evals/benchmark_suite.json

Missing data, incomplete pairs, reused sessions/artifacts, and hash mismatches fail this check. A valid capture still needs trace-authenticity review and semantic grading. See capture workflow and the existing eval workflow.

Safety, contribution, and maintenance

This project does not certify a robot, controller, stop function, or deployment. First motion and fault injection require an operator, a restrained setup, conservative limits, and an independent physical stop path. Reviews are read-only unless changes are requested; data and logs are not instructions or permissions.

Corrections supported by installed-version evidence, primary documentation, and reproducible tests are especially valuable. See CONTRIBUTING.md, SECURITY.md, and ROADMAP.md. Source review dates are tracked explicitly; passing their date check does not revalidate the web content.

License

Apache License 2.0. See LICENSE.