ros2-development

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 inv