Ros2 troubleshooting
Skill Leehyunbin0131/claude-ros2-skills/skills/ros2-troubleshooting
Diagnose ROS 2 Jazzy faults that reading the code cannot settle: QoS mismatch, sensor-mount and frame errors (REP 103/105), and odometry calibrated against CAD instead of the floor. Ships four runnable pass/fail checks.From its SKILL.md
npx -y skills add Leehyunbin0131/claude-ros2-skills --skill ros2-troubleshootingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.3 KB, as published. Nobody here has run it
ROS 2 troubleshooting
Most of this skill is scripts that turn a suspicion into an exit code. Run one before reasoning about the symptom.
Bundled checks
scripts/ sits next to this file — resolve the path from this skill's own
directory, not the user's CWD. Under a plugin install that is
${CLAUDE_PLUGIN_ROOT}/skills/ros2-troubleshooting/scripts/.
They are plain scripts: invoke with python3 and a real path. There is no
package to ros2 run, and inventing one is a known failure mode. Exit code
0 = PASS, 1 = FAIL, 2 = no data. Tell the user the command you ran.
source /opt/ros/jazzy/setup.bash
python3 <this-skill>/scripts/check_qos_compat.py --topic /scan
| Script | Answers |
|---|---|
check_qos_compat.py --topic /scan | Why a healthy publisher delivers nothing to this subscriber |
check_tf_tree.py --sensors laser_frame,imu_link | Does map->odom->base_link resolve, and does each sensor's mount RPY match the hardware |
check_imu_gravity.py [--topic /imu/data] | Is the IMU mounted the way the URDF claims — gravity ~+9.81 on +Z at rest |
check_odom_direction.py [--topic /odom] | Does odometry agree with the direction the robot physically moved |
check_tf_tree.py prints VERIFY PHYSICALLY for any ~180° roll or yaw even
when that mounting is deliberate. It asks for a comparison against the
hardware; it is not a verdict. Report it that way.
References
Load the one the symptom points at.
references/frames.md— REP 103/105 axis conventions, and the misalignment symptoms that follow from getting them wrong.CLAUDE.mdtreats this file as ground truth for any frame or TF question.references/runtime.md— what a QoS mismatch actually looks like on Jazzy, the two other policies that fail the same way, and whyros2 topic echocannot detect any of them.references/calibration.md— correctingdiff_drive_controllerwheel radius and separation against a tape measure, in the order that works. Read when odometry is consistent but wrong by a ratio.
What ships with it: 8 files
31.7 KB alongside SKILL.md, 5 of them executable
references/
- calibration.md1.9 KB
- frames.md2.4 KB
- runtime.md2.3 KB
scripts/
- check_imu_gravity.pyruns4.1 KB
- check_odom_direction.pyruns4.9 KB
- check_qos_compat.pyruns5.3 KB
- check_tf_tree.pyruns5.2 KB
- test_checks.pyruns5.5 KB
Gives 0 of the 12 instructions most debug triage skills give
Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06
- Find root cause before attempting any fixin 134 of 1020, across 118 files
- Create a failing test case before implementing a fixin 109 of 1020, across 95 files
- Read error messages and stack traces completelyin 102 of 1020, across 88 files
- Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
- Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
- Trace data flow backward to find the sourcein 84 of 1020, across 70 files
- Form a single hypothesis before testingin 78 of 1020, across 64 files
- Implement only one fix at a timein 76 of 1020, across 63 files
- Question the architecture if three fixes failin 73 of 1020, across 59 files
- Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
- Compare broken code against working examplesin 68 of 1020, across 57 files
- Write a regression test before applying the fixin 62 of 1020, across 55 files
Said here and by no other author read
- Run bundled scripts before reasoning about symptoms
- Resolve script paths from the skill directory
- Invoke scripts using python3
- Source the ROS 2 Jazzy setup file
- Report the exact command executed to the user
- Treat frame verification output as a physical check
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.