ROS 2 Engineering Skills

What It Does

ros2-engineering-skills is a single-skill repository that makes coding agents produce production-grade ROS 2 code instead of plausible-looking ROS 2 code. The always-loaded SKILL.md (470 lines) carries a decision router to 25 reference documents (16,333 lines total) covering workspaces, executors, QoS, ros2_control, Nav2, MoveIt 2, perception, real-time behavior, security, micro-ROS, and deployment. Seven Python scripts (5,184 lines) provide static validators: a QoS compatibility checker, a launch-file analyzer, a package scaffolder, a rosbag2 playback checker, two Claude Code hooks, and an eval runner. The user it targets is a robotics engineer or researcher who has an AI agent writing or reviewing ROS 2 code and is tired of catching wrong-distro API calls and executor deadlocks after the fact.

The Good

Test discipline that is rare at any star count, and unheard of at 158. On a fresh clone the full suite runs 707 passed in 17 seconds with zero failures, mypy reports "no issues found in 7 source files", and flake8 is clean when run as CI runs it (from the repo root, where setup.cfg sets a 120-column limit). CI enforces a 90 percent coverage gate across a Python 3.10, 3.11, and 3.12 matrix, exercises the Windows PowerShell installer (asserting that dry-run creates nothing and that force replaces a stale target), installs real Claude Code in a job to run claude plugin validate . --strict plus plugin list and plugin details, and builds integration tests in Docker against five ROS distributions: Humble, Jazzy, Kilted, Lyrical, and Rolling. The suite even enforces self-consistency on itself: one test asserts the checkout directory name matches the frontmatter name, which is how our misnamed review clone became the only red test we saw all day. That failure was the check working, not the repo broken.

The knowledge content is expert-level and safety-first, not a summary of the docs. The skill defines a seven-level verification ladder (L0 static review through L6 supervised field operation) with the rule that "tests pass" and "safe to drive" may not share a sentence, and it repeats that rule in the README. The e-stop reference opens with "Software e-stop is NOT safety-rated", cites ISO 13849 performance levels and IEC 62061 SIL, and builds the architecture around hardware STO (Safe Torque Off) chains with fail-safe "silence stops the robot" heartbeat semantics. The distro feature matrix carries HTML-comment staleness gates (LAST_UPDATED 2026-07-15, NEXT_REVIEW 2027-01-15) with instructions to re-verify EOL dates past six months. A 22-entry "AI pitfalls" table catalogs mistakes agents repeatedly make (generating Foxy-era API for Jazzy, reading zero Twist on cmd_vel as proof the robot stopped, treating a connected TF chain as a correct one) and carries a maintenance rule to append every newly discovered failure. This is content written by someone who has debugged real robots.

The honesty infrastructure is the best we have reviewed. The README's utility table has a Boundary column stating what each tool does not prove (the QoS checker "does not prove delivery quality or semantic correctness"; the launch validator "does not import every plugin or start the graph"). The eval runner's default mode is disclosed as a fixture-integrity check, "not a model benchmark", with a separate document describing what a real skill-on/skill-off comparison would require. The Stop hook's execution log is opt-in via the SKILL_RUNS_LOG environment variable, so a read-only session never writes to the working tree, and the validate hook inspects command strings without executing them. Most skills claim competence; this one documents its own epistemic limits per tool.

Progressive disclosure is done correctly, with numbers to prove it. The always-loaded file is 470 lines and routes 25 task categories to reference files ranging from 194 lines (system-diagnostics) to 1,224 lines (nodes-executors). The ros2 CLI cheat sheet lives in a reference file rather than SKILL.md, with a comment explaining it was "kept out of this always-loaded file to preserve context budget". All 25 router targets resolve to real files; we checked every one.

The Bad

No git tags and no GitHub releases despite otherwise strict versioning. The CHANGELOG documents releases 1.1.0 through 1.3.0, and the version 1.3.0 is consistent across SKILL.md frontmatter, both plugin manifests, and the hook JSON output, but there is no tag to pin, diff, or roll back against. For a skill whose own guidance stresses reproducible pins over floating labels, this is a self-consistency gap.

The Python 3.10 floor is enforced unevenly, and one script crashes rudely. qos_checker.py dies on Python 3.9 with a raw SyntaxError traceback (line 498, the list | None union annotation requires 3.10) rather than a clean version check with an actionable message. Meanwhile skill_validate_hook.py, create_package.py, and launch_validator.py all ran fine on our 3.9 system Python, so the declared floor is honest for one script and conservative for three. Also, skill_stop_hook.py accepts no --help; invoking it with unknown flags runs the hook and emits a JSON verdict instead. Both are small, but a fresh user on an old Python hits the worst version of this.

Install docs stop at Claude Code and manual clone. The README documents the Claude Code plugin path and a git clone into ~/.agents/skills. It never mentions the universal skills CLI or Hermes/OpenClaw by name, even though npx skills add dbwls99706/ros2-engineering-skills --agent hermes-agent --copy --yes worked first try in our test and landed the complete repository (25 references, 7 scripts, all docs) with a byte-identical SKILL.md. The hooks are also Claude Code-specific by design; on every other platform the validators must be run by hand, which the SKILL.md does document with exact commands.

Single contributor, 158 stars, and factual claims not yet broadly audited. One author (YuJin Hong) has written all the content; the pitfall catalog and distro matrix reflect one practitioner's experience rather than a community-vetted corpus. The ROADMAP itself lists "distribution-sensitive factual audits" as planned future work, which is the right instinct and also an accurate confession that it has not happened yet.

Smoke Test Results

Hands-on host test on macOS 26.5.2 (aarch64), Python 3.11.14 in a venv for the with-deps run, system Python 3.9.6 for the fresh run. Full logs are in the sandbox folder.

Run A. Fresh host, no dev dependencies installed

$ git clone --depth 1 https://github.com/dbwls99706/ros2-engineering-skills
✅ SKILL.md, references/ (25 files), scripts/ (7 files) land; 2.0 MB
$ python3 --version
✅ Python 3.9.6 (below the documented 3.10 validator floor; recorded)
$ python3 scripts/qos_checker.py --pub reliable,volatile,keep_last,10 --sub reliable,volatile,keep_last,10
❌ SyntaxError: list | None at line 498 (PEP 604 needs 3.10; documented floor, raw traceback)
$ python3 scripts/skill_validate_hook.py --file good_node.py
✅ JSON emitted: status "pass", issues_count 0 (runs on 3.9)
$ python3 scripts/create_package.py demo_pkg --type python
✅ package.xml scaffolded (runs on 3.9)
$ python3 scripts/launch_validator.py ok.launch.py
✅ exit 0, no issues (runs on 3.9)
$ ./install.sh --target <dir> --dry-run
✅ target never created; dry-run is side-effect free

Pass rate: 6 of 7. The single failure is the declared Python 3.10 floor doing its job, though with a raw traceback instead of a version message; three of four validators happen to run on 3.9 regardless.

Full sandbox log →

Run B. With deps preinstalled (venv + requirements-dev.txt)

$ python3.11 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
✅ pytest 9.x, PyYAML, hypothesis resolve with bounded major ranges
$ .venv/bin/python -m pytest tests/ -q
✅ 707 passed in 17.05s (706 from a misnamed clone dir; the 707th is the name-consistency test)
$ .venv/bin/python -m flake8 scripts/ tests/
✅ clean from repo root (setup.cfg: max-line-length 120)
$ .venv/bin/python -m mypy scripts/ --ignore-missing-imports
✅ Success: no issues found in 7 source files
$ .venv/bin/python scripts/qos_checker.py --help (and the other six CLIs)
✅ 7 of 7 respond; skill_stop_hook emits its JSON verdict
$ SKILL_WORKSPACE=<dir> .venv/bin/python scripts/skill_stop_hook.py
✅ {"hook": "ros2-engineering-skills:stop", "status": "pass"}
$ .venv/bin/python scripts/eval_runner.py --mode structural
✅ eval fixtures consistent with eval.yaml criteria
$ ./install.sh --target <dir>
✅ installed SKILL.md byte-identical to repo copy (diff clean)
$ python -c "json.load(plugin.json)['version']" (and marketplace.json)
✅ 1.3.0 consistent across SKILL.md, plugin.json, marketplace.json, hook output
$ frontmatter parse + description length check
✅ name matches directory; description 496 chars including explicit
 negative scoping ("Do not use for..."), under the 1024 limit

Pass rate: 10 of 10. Everything the CI runs locally reproduced green on the first try, with the flake8 caveat that it must be run from the repo root so setup.cfg applies.

Full sandbox log →

Run C. Functional verification

$ python scripts/qos_checker.py --pub reliable,volatile,keep_last,10 --sub reliable,volatile,keep_last,10
✅ exit 0, pair compatible (positive case)
$ python scripts/qos_checker.py --pub best_effort,volatile,keep_last,5 --sub reliable,volatile,keep_last,10
✅ exit 1, pair rejected (negative case: publisher cannot satisfy subscriber)
$ python scripts/qos_checker.py --preset safety_heartbeat
✅ preset evaluates (RELIABLE, 500 ms deadline, 1 s lifespan)
$ python scripts/skill_validate_hook.py --file good_node.py
✅ JSON: status "pass", issues_count 0
$ python scripts/skill_validate_hook.py --file bad_node.py # time.sleep in rclpy callback
✅ JSON: issues_count 1, "Avoid time.sleep() in ROS 2 nodes: use create_wall_timer() instead"
$ python scripts/launch_validator.py dup.launch.py # two nodes named driver in /robot
✅ exit 1, ERROR: Duplicate node name 'driver' in namespace '/robot' (first defined at line 6)
$ python scripts/launch_validator.py hard.launch.py # executable='/opt/ros/humble/...' + '/.../params.yaml'
✅ exit 0 with 2 WARNINGs: hardcoded absolute executable path + hardcoded file path (advisory by design)
$ python scripts/launch_validator.py broken.launch.py # syntax error
✅ exit 1, Syntax error reported (negative case)
$ python scripts/create_package.py my_arm_driver --type cpp --lifecycle
✅ package.xml + CMakeLists.txt + lifecycle node scaffold generated
$ npx skills add dbwls99706/ros2-engineering-skills --agent hermes-agent --copy --yes
✅ full repo lands in ./.hermes/skills (25 refs, 7 scripts), SKILL.md byte-identical
$ grep -o 'references/[a-z0-9-]*\.md' SKILL.md | sort -u | while read f; do test -f "$f"; done
✅ all 25 decision-router targets exist on disk
$ ls evals/prompts evals/expected
✅ 14 prompts, 14 expected answers, eval.yaml covers all 14

Functional pass rate: 14 of 14. Positive and negative cases asserted for both headline validators; verdicts parsed from JSON or exit codes, not eyeballed.

Full functional log →

What the runs tell you

The tooling installs and runs correctly everywhere the docs say it will, and the validators give structured, correct verdicts on both sides of every rule we probed. What this host test cannot reach is the thing the skill is ultimately for: behavior inside a live ROS 2 graph. The repo's own five-distro Docker CI covers that layer, and the skill is explicit that its static checks are L0-L2 evidence, which is the honest framing a robotics shop needs.

Setup Walkthrough

1. Install via the path that matches your agent. For Claude Code: claude plugin marketplace add dbwls99706/ros2-engineering-skills then claude plugin install ros2-engineering@ros2-engineering-skills. For Hermes or any skills-CLI-compatible agent: npx skills add dbwls99706/ros2-engineering-skills --agent hermes-agent --copy --yes (verified working, undocumented in the README).
2. If you want the validators and test suite, clone the repo and create a Python 3.10+ venv: git clone https://github.com/dbwls99706/ros2-engineering-skills && cd ros2-engineering-skills && python3.11 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt.
3. Verify with .venv/bin/python -m pytest tests/ -q (707 passed for us) or run any validator directly: python scripts/qos_checker.py --help.
4. On non-Claude platforms, wire the hooks in manually if you want them: the SKILL.md documents the exact environment variables and flags (SKILL_WORKSPACE= python3 scripts/skill_stop_hook.py).

Post-install gotchas: the hooks only fire in Claude Code; on other agents the validators are manual commands. Python 3.9 hosts will crash on qos_checker with a traceback rather than a version message, so check your interpreter first.

Alternatives

1. Official upstream docs (docs.ros.org, Nav2, MoveIt 2, ros2_control docs) - authoritative and always current, but not agent-shaped: no decision router, no AI-pitfall catalog, no static validators, and no verification-level discipline for reports.
2. anthropics/skills - the flagship general pack (document tools, artifacts), high quality, with zero robotics content; complementary rather than competing.
3. A hand-written CLAUDE.md or AGENTS.md rules file - cheap and local, and many teams start here, but you inherit the maintenance burden this repo has already paid: a distro matrix that goes stale, rules with no tests, and no guard rails that fire at edit time.