wzyn20051216/ros-robotics-skill

ROS Robotics

When to Use

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

• catkin_ws, colcon_ws, src/CMakeLists.txt, package.xml, setup.py
• Creating, porting, building, testing, or 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 co-development

What to Do First

1. Identify the workspace first

python scripts/detect_ros_workspace.py <workspace-path>

2. Then run a consistency check

python scripts/check_ros_workspace_consistency.py <workspace-path>

3. Load the minimal required documentation based on the issue

• ROS 1: references/ros1-catkin.md
• ROS 2: references/ros2-colcon.md
• Mixed / Migration: references/interop-and-migration.md
• Models / 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 / 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

Mandatory Principles

• Identify the build system first, then modify code
• Fix consistency of package.xml / CMakeLists.txt first, then consider refactoring
• Look at TF, timestamps, frames, units first, then blame the algorithm
• Establish evidence chain before making changes: build output, topics, TF, parameters, logs must be verifiable
• For ROS 1 → ROS 2, bridge or use a layered approach first; don't tear everything down in one go
• For MCU / micro-ROS, first judge whether it truly needs to enter the ROS graph

Common Task Handling

Adding or Fixing a Package

• First determine the package type: catkin, ament_cmake, ament_python
• First add dependency declarations, then build logic, then install rules
• For custom msg / srv / action, prioritize checking generation order and dependency cycles (see references/custom-interfaces.md)

Build Failures

• First run rosdep
• Then verify package.xml and build scripts
• Then check if the environment is properly sourced
• Then check system dependencies, ABI compatibility, distro compatibility

Robot Behaves Incorrectly While Running

• First check launch files, namespaces, remaps, parameters
• Then check topic names, frequency, timestamps, units, frame_id
• Then check if TF is a single root, and whether static / dynamic TF is properly distinguished
• Only then doubt the algorithm itself

Nav2 / ros2_control

• For Navigation2, prioritize debugging the /cmd_vel chain, localization quality, control frequency, and chassis units
• For ros2_control, prioritize debugging hardware interface types, controller YAML, read/write cycles, and active status

MCU / micro-ROS

• First determine whether the bridge node on the Linux side is sufficient
• Only if the MCU must enter the ROS 2 graph, then consider micro-ROS
• Strictly check endianness, checksums, timeouts, reconnections, time sources, and disconnect protection

Anti-Patterns

• Mixing catkin and ament in the same package
• Only modifying CMakeLists.txt without updating package.xml
• Ignoring TF, timestamps, units, and coordinate axis definitions
• Stuffing drivers, protocols, filtering, control, and diagnostics all into one large node
• When migrating from ROS 1 to ROS 2, only doing API substitutions without system validation

Output Requirements

When using this skill to process a task, prioritize outputting:

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