claude-ros2-skills

Contextual packaging of ROS 2 verification tools, workflows, and handoff evidence.

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

Three skills for Claude Code and Codex, targeting Ubuntu 24.04 / ROS 2 Jazzy: develop packages, verify tests and installed behaviour, and diagnose runtime faults.

This repository packages contextual domain guidance, workflows, and executable diagnostics under the Agent Skills standard. Rather than claiming to enhance the intrinsic code generation capabilities of frontier language models, this project explores an engineering hypothesis: packaging environment-specific evidence checks and structured handoff records can reduce verification ambiguity and context-transfer overhead between sessions or collaborators. While individual tool functionality is validated on test fixtures, reduced handoff cost and overall developer productivity gains remain unproven.

Quickstart

Choose your assistant. Automatic skill discovery is supported across environments. For Claude Code, choose either plugin or manual installation.

Codex — native skills for an existing project:

git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git
python3 claude-ros2-skills/scripts/install.py --agent codex --project /path/to/your-workspace
# Alternative: install for this user across all projects
# python3 claude-ros2-skills/scripts/install.py --agent codex --user

The Codex skill locations are <project>/.agents/skills and ~/.agents/skills for these two scopes. Choose one scope to avoid duplicate skill names. Each installed Codex skill includes the shared verification protocol, loaded when that skill is used. Existing AGENTS.md, CLAUDE.md, Codex configuration and unrelated skills are preserved; local edits stop an update. Start a new Codex session in the target workspace. To select a skill explicitly in Codex CLI or the IDE, use $ros2-development or $ros2-troubleshooting. In the desktop skill picker, select the same skill by name.

Live ROS checks also need access to the intended ROS graph. In a restricted Codex environment, a denied ROS log directory can be redirected with ROS_LOG_DIR to a writable workspace directory. Discovered topics with no received messages can reflect sandbox/DDS transport constraints. Keep the workspace's domain and discovery scope; widening discovery to SUBNET is not a general installation fix. Report unavailable observations as inconclusive. See the observed Codex runtime limitations.

Plugin — from a Claude Code session:

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

Start a new session. A SessionStart hook loads the protocol; plugin-root CLAUDE.md is not automatically loaded on its own. The default user scope applies to all projects. Prefer a project install when you want it limited to a ROS workspace.

Claude Code manual — into an existing project:

git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git
python3 claude-ros2-skills/scripts/install.py --project /path/to/your-workspace
# Alternative: install for this user across all projects
# python3 claude-ros2-skills/scripts/install.py --user

The installer copies the skills and .claude/rules/ros2-verification.md. It preserves existing CLAUDE.md files and unrelated skills, refuses to overwrite local edits, and reports retired skill directories for manual review. Restart Claude Code afterwards. ROS, colcon and robot drivers are not installed by this pack; install the dependencies needed by your workspace. For these checks on an existing Jazzy installation:

sudo apt install python3-colcon-common-extensions python3-pytest \
  ros-jazzy-tf2-ros ros-jazzy-sensor-msgs ros-jazzy-nav-msgs
source /opt/ros/jazzy/setup.bash

Prefer Ubuntu/Jazzy's test-tool versions or a separately verified environment. The tested Jazzy launch_testing plugin fails to start with pytest 9; our ROS-sourced checks use Ubuntu's pytest 7.4.4. A runner crash is not evidence that the implementation's assertions failed.

Skills

Both assistants can select a skill automatically from its description. To request it explicitly, mention its name in your task. Examples:

• “Use ros2-development to add a service to this existing Jazzy package. Build its consumers, run the relevant tests, and show that the installed node works.”
• “Use ros2-troubleshooting: /scan publishes, but my node's callback never fires. Find the incompatible endpoints and verify the correction.”
• “The robot is level but its IMU is mounted upside down. Check gravity using the declared TF; distinguish a correct mounting transform from a real error.”

Specify hardware versus simulation and the workspace when known. The agent should establish genuinely missing robot geometry or existing publishers before making assumptions about them.

Verification scripts

Scripts ship with their respective skill. In command examples, ROS2_SKILL_DIR is an illustrative variable set by the agent to the directory containing the loaded skill; it does not require user input. They are plain Python files, not ROS packages to invoke with ros2 run.

Diagnostic exit codes: 0 PASS, 1 FAIL, 2 INCONCLUSIVE or invalid request.

Evidence inspection exit codes: 0 Consistent, 1 Changed, 2 Incomplete.

Missing data, NaN, unavailable IMU fields, insufficient samples (<2), excessive sample variation, unknown QoS, no executed tests and insufficient motion must not become successful verification. The runtime scripts require a sourced Jazzy environment. They do not publish motion commands; the odometry check relies on movement performed outside the script. A check supports only the property it observes; IMU PASS confirms measured +Z gravity in the level base frame after declared TF or an explicit aligned-axis assumption, but cannot prove physical stillness or whole-robot correctness.

The evidence tool strictly separates caller-declared outputs from tool-observed file hashes. It does not execute or re-run user commands, does not guarantee freshness or absence of intermediate changes, and does not claim whole-robot health. See docs/DESIGN.md and references/handoff.md.

How it works

flowchart LR
    A[Development request] --> B[Protocol: verify local facts]
    B --> C[ros2-development: build and test]
    B --> D[ros2-troubleshooting: runtime evidence]
    C --> E[Installed behaviour and observed result]
    D --> E
    E --> F[Correct the defect and repeat the relevant check]

The protocol covers development across packages, Nav2, MoveIt and ros2_control; the focused skills add procedures and tools when those are useful. We do not restore large domain manuals merely to increase the skill count. The ros2-development workflow addresses a concrete gap: a successful test command can report zero tests. In the real package fixture, that command returns 0 while the bundled evidence check returns 2.

Validation and evidence limits

CI checks installation/update preservation, Python and shell code, deterministic verdicts, real Python/CMake and ament test wrappers, synthetic Jazzy pub/sub and TF, and independent acceptance-oracle controls. Commands are in CONTRIBUTING.md.

Real Claude Code Opus 5.5 High sessions completed three targeted workflows under both plugin and manual installation: a namespaced sensor package with installed YAML/launch, meaningful wheel-speed tests, and live IMU/TF diagnosis. Both loading smokes verified protocol delivery and actual bundled-script use. The three baseline sessions also passed: the observed task outcomes were the same. This is one run per method and task, not evidence of a performance gain or equivalent reliability. Follow-up runtime sessions review owned-process cleanup after a focused instruction fix; all attempts and limits are in the release acceptance report.

Codex support is tracked separately in the Codex compatibility report. Its operational evidence covers offline install, discovery, and two project-install workflows with model identity unrecorded; earlier Claude observations are not Codex performance evidence. The Codex installer embeds the protocol on skill activation; it does not install a session-wide hook.

A subsequent interface-migration study tested the frozen 0.1.2 snapshot across three matched variants with Python and C++ consumers using Opus 5.5 High. All six baseline/pack artifacts passed independent clean-build, runtime and regression checks. Verification reports, ambiguous project-rule compliance and process-cleanup limitations are assessed separately. In these runs, pack sessions had higher output token counts and API estimates; lower elapsed wall times were confounded by execution order, prompt caching, and probe backgrounding waits. There is no proven token, total-cost, or speed advantage, and none is claimed. Release 0.2.0 ships opt-in evidence handoff tools alongside targeted IMU fixes; that historical 0.1.2 study does not evaluate the new handoff tool.