ROS 2 Engineering Skills
Single responsibility: This skill is an API reference & code template guide for ROS 2 development. It tells you how to use ROS 2 APIs correctly and what mistakes to avoid. It does NOT do CI/CD orchestration, incident response, data analysis, or deployment automation — those are separate skill categories.
A progressive-disclosure skill for ROS 2 development — from first workspace to
production fleet deployment. Each section below gives you the essential decision
framework; detailed patterns, code templates, and anti-patterns live in the
references/ directory. Read the relevant reference file before writing code.
How to use this skill
Progressive disclosure — do NOT read everything at once. This skill is structured in layers. Only load what you need for the current task:
- This file (SKILL.md) — always loaded. Contains decision routing, core principles, pitfalls, and anti-patterns. Sufficient for answering quick questions and making architectural decisions.
references/*.md— load on demand. Use the Decision Router below to pick the 1–2 files relevant to the user's current task. Do NOT read all 20 reference files — that wastes context and causes confusion.scripts/— run only when the user needs code generation, QoS checking, or launch validation. These are tools, not reading material.
Steps:
- If
.skill-runs.logexists in the workspace, read the last few lines to understand what was done and what issues occurred in previous sessions. - Identify what the user is building (see Decision Router below).
- Read only the matching
references/*.mdfile(s) for detailed guidance. - Check the AI pitfalls table before generating any code.
- Apply the Core Engineering Principles in every artifact you produce.
- When multiple domains intersect (e.g. Nav2 + ros2_control), read both files but favor safety > determinism > simplicity when recommendations conflict.
Execution log: The Stop hook automatically appends a session summary to
.skill-runs.log in the workspace. This lets you see what was validated last
time and what issues were found — check it to avoid repeating past mistakes.
Decision router
| User is doing... | Read |
|---|---|
| Creating a workspace, package, or build config | references/workspace-build.md |
| Writing nodes, executors, callback groups | references/nodes-executors.md |
| Topics, services, actions, custom interfaces, QoS | references/communication.md |
| Lifecycle nodes, component loading, composition | references/lifecycle-components.md |
| Launch files, conditional logic, event handlers | references/launch-system.md |
| tf2, URDF, xacro, robot_state_publisher | references/tf2-urdf.md |
| ros2_control, hardware interfaces, controllers | references/hardware-interface.md |
| Real-time constraints, PREEMPT_RT, memory, jitter | references/realtime.md |
| Nav2, SLAM, costmaps, behavior trees | references/navigation.md |
| MoveIt 2, planning scene, grasp pipelines | references/manipulation.md |
| Camera, LiDAR, PCL, cv_bridge, depth processing | references/perception.md |
| Unit tests, integration tests, launch_testing, CI | references/testing.md |
| ros2 doctor, tracing, profiling, rosbag2, CLI cheat sheet | references/debugging.md |
| Docker, cross-compile, fleet deployment, OTA | references/deployment.md |
| Gazebo, Isaac Sim, sim-to-real, use_sim_time | references/simulation.md |
| SROS2, DDS security, certificates, supply chain | references/security.md |
| micro-ROS, MCU/RTOS, XRCE-DDS, rclc | references/micro-ros.md |
| Multi-robot fleet, Open-RMF, DDS discovery scale | references/multi-robot.md |
| Message types, units, covariance, frame conventions | references/message-types.md |
| ROS 1 migration, ros1_bridge, hybrid operation | references/migration-ros1.md |
Cross-cutting concerns: Security, error handling, and QoS are not isolated to single reference files — apply them whenever the data path crosses a trust boundary, a node owns hardware, or communication reliability matters. Use your judgment about which cross-cutting concerns apply to the user's specific situation.
Core engineering principles
These apply to every ROS 2 artifact you produce, regardless of domain.
1. Distro awareness
<!-- LAST_UPDATED: 2026-03-30 — Review this table every 6 months or when a new distro is released. --> <!-- NEXT_REVIEW: 2026-09-30 -->Staleness warning: The table below was last verified on 2026-03-30. If the current date is more than 6 months past that, re-verify EOL dates and feature support against https://docs.ros.org/en/rolling/Releases.html before relying on this table. When you update it, change both
LAST_UPDATEDandNEXT_REVIEWcomments above.
Always ask which ROS 2 distribution the user targets. Key differences:
| Feature | Foxy (EOL) | Humble (LTS) | Jazzy (LTS) | Kilted (non-LTS) | Rolling |
|---|---|---|---|---|---|
| EOL | Jun 2023 (ended) | May 2027 | May 2029 | Nov 2025 | Rolling |
| Ubuntu | 20.04 | 22.04 | 24.04 | 24.04 | Latest |
| Default DDS | Fast DDS | Fast DDS | Fast DDS | Fast DDS | Fast DDS |
| Zenoh support | — | — | — | Tier 1 | Tier 1 |
| Type description support | No | No | Yes | Yes | Yes |
| Service introspection | No | No | Yes | Yes | Yes |
| EventsExecutor | No | No | Experimental | Stable (+ rclpy) | Stable (+ rclpy) |
| Default bag format | sqlite3 | sqlite3 | MCAP | MCAP | MCAP |
| ros2_control interface | N/A (separate) | 2.x | 4.x | 4.x | Latest |
| CMake recommendation | ament_target_deps | ament_target_deps | either | target_link_libs | target_link_libs |
When the user does not specify, default to the latest LTS (Jazzy). Pin the exact distro in Dockerfile, CI, and documentation so builds are reproducible.
2. C++ vs Python decision
Choose the language based on the node's role, not personal preference.
Use rclcpp (C++) when:
- The node sits in a control loop running ≥100 Hz
- Deterministic memory allocation matters (real-time path)
- The node is a hardware driver or controller plugin
- Intra-process zero-copy communication is required
Use rclpy (Python) when:
- The node is orchestration, monitoring, or parameter management
- Rapid prototyping with frequent iteration
- Heavy use of ML frameworks (PyTorch, TensorFlow) that are Python-native
- The node does not sit in a latency-critical path
Mixed stacks are normal. A typical robot has C++ drivers/controllers and Python
orchestration/monitoring. Note: component_container (composition) only loads
C++ components via pluginlib. Python nodes run as separate processes, but can
share a launch file and communicate via zero-overhead intra-host DDS.
Intra-process communication works for any