ros2-engineering-skills

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

Where the guidance lives

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.

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.

The separate diagnostic review suite preregisters
four synthetic offline-analysis cases with three paired trials each. Its controls,
artifact-lineage questions, and state-semantics counterexample are evaluation
inputs, not measured model improvements or a replay of a production recording.

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.

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "ros2-engineering-skills",
  "description": "ROS 2 engineering plugins maintained by dbwls99706",
  "owner": {
    "name": "YuJin Hong",
    "email": "yujinhong3@gmail.com"
  },
  "plugins": [
    {
      "name": "ros2-engineering",
      "version": "1.6.2",
      "description": "Production-grade ROS 2 engineering guidance and validation tools",
      "author": {
        "name": "YuJin Hong",
        "email": "yujinhong3@gmail.com"
      },
      "source": "./",
      "category": "development",
      "homepage": "https://github.com/dbwls99706/ros2-engineering-skills#readme",
      "keywords": [
        "ros2",
        "robotics",
        "agent-skills",
        "nav2",
        "ros2-control"
      ]
    }
  ]
}