ros-robotics

ROS Robotics

When to use

Use this skill when the user's request involves any of the following topics:

• catkin_ws、colcon_ws、src/CMakeLists.txt、package.xml、setup.py
• Creating, porting, building, testing, and debugging ROS 1 / ROS 2 packages
• launch / launch.py, parameter YAML,URDF/Xacro、RViz、TF
• topic / service / action / msg / srv / QoS
• chassis, IMU, LiDAR, camera, localization, SLAM, Navigation2,ros2_control
• Gazebo / Ignition simulation, sensor simulation,ros_gz_bridge
• Docker containerized ROS development,docker-compose multi-node orchestration
• Lifecycle nodes,rclcpp_components componentization, intra-process communication
• rosbag2 recording and playback,mcap, offline diagnostics
• SLAM mapping (Cartographer, SLAM Toolbox, ORB-SLAM)
• DDS / QoS configuration,ROS_DOMAIN_ID, RMW selection, multi-machine networking
• Custom msg / srv / action interface definition and generation
• Multi-robot systems, namespace isolation, cross-machine communication
• MoveIt 2 motion planning, SRDF, kinematics plugins
• ROS 2 CI/CD（GitHub Actions、colcon test、ament_lint）
• Foxglove Studio / PlotJuggler data visualization and offline analysis
• MCU / RTOS / UART / CAN / micro-ROS collaborative development

What to do first

1. Identify the workspace first

python scripts/detect_ros_workspace.py <workspace-path>

2. Then perform a consistency check

python scripts/check_ros_workspace_consistency.py <workspace-path>

3. Load the minimum necessary documentation based on the problem

• ROS 1：references/ros1-catkin.md
• ROS 2：references/ros2-colcon.md
• Mixed / migration:references/interop-and-migration.md
• Model / TF:references/robot-description-and-tf.md
• Navigation:references/navigation2.md
• Control:references/ros2-control.md
• Embedded:references/micro-ros-and-embedded.md
• Simulation:references/gazebo-simulation.md
• Lifecycle / components:references/lifecycle-and-components.md
• DDS / QoS / networking:references/dds-qos-networking.md
• Recording and playback / diagnostics:references/rosbag-diagnostics.md
• SLAM / mapping:references/slam-mapping.md
• Docker：references/docker-ros.md
• Custom interfaces:references/custom-interfaces.md
• Multi-robot:references/multi-robot.md
• MoveIt 2：references/moveit2.md
• CI/CD：references/ros2-cicd.md
• Visualization:references/foxglove-visualization.md
• Troubleshooting:references/debug-playbooks.md
• Review:references/review-checklist.md

Principles that must be followed

• Identify the build system first, then modify the code
• Fix package.xml / CMakeLists.txt consistency first, then talk about refactoring
• Check TF, timestamps, frames, and units first, then blame the algorithm
• Evidence chain first, then modification: build output, topics, TF, parameters, and logs must be verifiable
• For ROS 1 → ROS 2, bridge or layer first; do not tear everything down and start over in one go
• MCU / micro-ROS First determine whether it really needs to enter the ROS graph

How to handle common tasks

Add or fix a package

• Determine the package type first:catkin、ament_cmake、ament_python
• Add dependency declarations first, then build logic, then install rules
• Custom msg / srv / action Prioritize checking the generation order and dependency closure (see references/custom-interfaces.md）

Build failure

• Run rosdep
• then verify package.xml and the build script
• then check whether the environment is sourced correctly
• then check system dependencies, ABI, and distribution compatibility

Runs normally but the robot behaves incorrectly

• Check launch, namespace, remap, and parameters first
• then check topic names, rates, timestamps, units,frame_id
• then check whether TF has a single root and whether static / dynamic are distinguished
• only then suspect the algorithm itself

Nav2 / ros2_control

• For Navigation2, troubleshoot /cmd_vel chain, localization quality, control rate, and chassis units first
• ros2_control Prioritize hardware interface types, controller YAML, read/write cycles, and active status

MCU / micro-ROS

• First determine whether the Linux-side bridge node is sufficient
• If the MCU must enter the ROS 2 graph, then consider micro-ROS
• Strictly check byte order, checksums, timeouts, reconnection, time sources, and loss-of-connection protection

Anti-patterns

• Mixing in the same package catkin and ament
• Only changing CMakeLists.txt without changing package.xml
• Ignoring TF, timestamps, units, and coordinate axis definitions
• Cramming drivers, protocols, filtering, control, and diagnostics all into one large node
• When migrating ROS 1 → ROS 2, only doing API replacement without system verification

Output requirements

When using this skill to handle tasks, prioritize outputting:

1. Judgment of the current workspace and package type
2. Key evidence and assumptions
3. Modification points and reasons
4. Minimal build / test / run commands
5. Risk points and regression checkpoints