ros2-engineering

ros2-engineering-skills

Source version: 1.7.1. 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)

Assumes the publisher exists, the type is correct, and QoS is the mismatch.

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)

Checks graph, type, namespace, and offered/requested QoS before changing code.

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

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

A bare node without explicit configuration, test, resource, or shutdown contracts.

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

Chooses Node or LifecycleNode from resource ownership and supervision; declares QoS, frames, timestamps, limits, dependencies, and distro-compatible tests.

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.

Every installation records INSTALL_PROVENANCE.json: the source version and Git commit, the installer version, and a SHA-256 digest of each installed file. python3 scripts/install_skill.py --verify --client codex reports whether the installation still matches that manifest (exit 0 only when clean). --force refuses to replace an installation that differs from its manifest or has none; add --force --discard-local-changes to replace it anyway. The manifest is an installation snapshot for detecting accidental or local drift, not a signed attestation: it cannot prove the absence of deliberate tampering, because the manifest and the files can be edited together. The installer never searches for custom installation locations; name them with --target.

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. They write no provenance manifest, and they refuse to replace a target that is a symbolic link or reparse point, so a link shared by several clients is never split into a separate copy; pass the resolved path instead. 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/install_skill.py --verify --client codex
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.

Where the guidance lives

Path	Role
SKILL.md, references/, docs/	The guidance itself: router, task references, contracts
scripts/	User-facing static checkers and helpers (table below)
.claude-plugin/, hooks/, agents/, install.sh, install.ps1	Client and installation integration
tests/, evals/, .github/	Development and verification of this repository

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 27 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.

Utility	Purpose	Boundary
create_package.py	Generate package scaffolds	Build in the target distribution
qos_checker.py	Compare offered/requested QoS	Compatibility is not delivery quality
qos_audit.py	Pair QoS declarations across a package by topic and type	Static; unresolved values are never guessed
rosbag2_qos_checker.py	Inspect bag metadata QoS	Static metadata analysis
launch_validator.py	Detect selected Python launch defects	Does not start a graph
launch_supervisor.py	Run an authorized launch with owned SIGINT handling	POSIX; starts processes, not a hardware stop
skill_validate_hook.py	Inspect source and command strings	Best-effort guard, not a security boundary
skill_stop_hook.py	Check changed launch/package/Nav2 files	Advisory, not a complete build
claude_hook.py	Adapt reports to Claude hook transport	Never grants permissions or blocks Stop
validate_skill.py	Validate metadata, local paths, packaging, source dates	Static checks, not client activation
install_skill.py	Stage and validate knowledge-only installations	No settings changes or hook registration
eval_runner.py	Check fixtures or lexically score supplied text	Does not invoke a model or prove semantics
verify_eval_capture.py	Require complete paired captures with hashes	Integrity, not authenticity or quality
benchmark_capture.py	Fill the paired manifest, fix run order, build blinded grading sheets, score pairs	Orchestration only; runs no model and grades nothing
measure_context.py	Count the selected body with named tokenizers	Excludes client wrappers and on-demand references

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.