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. Detailed patterns and code templates live in
references/; read the relevant file before writing code.

How to use this skill

Progressive disclosure — do NOT read everything at once. This always-loaded
file carries routing, core principles, pitfalls, and anti-patterns; that is
enough for quick questions and architectural decisions. references/*.md load
on demand — use the Decision Router to pick the 1–2 files matching the task,
never all of them. scripts/ are tools to run (scaffolding, QoS checking,
launch validation), not reading material.

Steps:

1. Identify what the user is building (see Decision Router below).
2. Read only the matching references/*.md file(s) for detailed guidance.
3. Check the AI pitfalls table before generating any code.
4. Apply the Core Engineering Principles in every artifact you produce.
5. When multiple domains intersect (e.g. Nav2 + ros2_control), read both files
   but favor safety > determinism > simplicity when recommendations conflict.

Execution log (opt-in): When the Stop hook runs (Claude Code only) and
the SKILL_RUNS_LOG environment variable is set, a session summary is
appended to .skill-runs.log. If that file exists in the workspace, read the
last few lines to avoid repeating past mistakes. Without the opt-in — and on
platforms without hooks — the file is never created, so a read-only session
leaves the working tree untouched.

Platform support: SKILL.md and references/ are platform-neutral
knowledge documents. scripts/ can be run manually on any platform whose
environment has Python and the repository dependencies. The hook wiring
(automatic execution) and .skill-runs.log are Claude Code-specific; on
other platforms run the validators manually from the skill root:
SKILL_WORKSPACE=<dir> python3 scripts/skill_stop_hook.py and
python3 scripts/skill_validate_hook.py --file <src> / --command '<cmd>'
(the command string is inspected only, never executed; without those flags
the validate hook expects a Claude Code PreToolUse payload and checks
nothing on its own).

Decision router

Cross-cutting concerns: Security, error handling, and QoS are not isolated to single
reference files — use your judgment and apply them whenever the data path crosses a
trust boundary, a node owns hardware, or communication reliability matters.

Core engineering principles

These apply to every ROS 2 artifact you produce, regardless of domain.

1. Distro awareness

<!-- LAST_UPDATED: 2026-07-15 — Review this table every 6 months or when a new distro is released. -->
<!-- NEXT_REVIEW: 2027-01-15 -->
> Staleness warning: The table below was last verified on 2026-07-15.
> 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_UPDATED and
> NEXT_REVIEW comments above.

Always ask which ROS 2 distribution the user targets. Key differences:

Foxy (EOL June 2023, Ubuntu 20.04, ros2_control not bundled) is a migration
reference only — see the migration notes below. The pre-Lyrical
EventsExecutor lives in the rclcpp::experimental namespace on every
release that ships it; Lyrical adds the separate, non-experimental
rclcpp::executors::EventsCBGExecutor.

When the user does not specify, default to the latest LTS — Lyrical Luth
(Ubuntu 26.04); use Jazzy when the target platform is Ubuntu 24.04.
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.
rclcpp (C++): control loops ≥100 Hz, deterministic memory allocation
(real-time path), hardware drivers and controller plugins, intra-process
zero-copy. rclpy (Python): orchestration, monitoring, parameter
management, rapid prototyping, Python-native ML frameworks — anything off
the 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 and
communicate over intra-host DDS — not zero-overhead by default: the
standard inter-process transport pays serialization, copies, and transport
bandwidth, and splitting work into another process does not by itself remove
encoding costs. Copy avoidance has three distinct mechanisms with different
preconditions: (1) the rclcpp intra-process path
(use_intra_process_comms(true), same process) avoids copies only depending
on publish ownership (unique_ptr), callback type, subscriber count, and
QoS; (2) loaned messages / vendor shared memory (SHM/PSMX) are RMW- and
vendor-dependent and can avoid some or all copies when their preconditions
hold; (3) separate processes on the standard DDS transport get no copy
avoidance — crossing processes without copies requires the vendor
mechanisms in (2). Details: references/nodes-executors.md.

3. Package structure conventions

Follow the standard layout — package.xml (format 3, explicit <depend>
tags), config/params.yaml, launch/*.launch.py, src/ +
include/<pkg>/ for C++ or <pkg>/ for Python, and test/. Keep custom
msg/srv/action definitions in a dedicated *_interfaces package so
downstream packages can depend on interfaces without the implementation.
Full annotated layout: references/workspace-build.md.

4. Parameter discipline

• Declare every parameter with a type, description, range, and default
  in the node constructor — never use undeclared parameters.
• Use ParameterDescriptor with FloatingPointRange or IntegerRange
  for numeric bounds. The parameter server rejects out-of-range values at set time.
• Group related parameters under a namespace prefix:
  controller.kp, controller.ki, controller.kd.
• Load defaults from a config/params.yaml; allow launch-time overrides.
• For dynamic reconfiguration, register a set_parameters_callback and
  validate new values atomically before accepting.

5. Error handling philosophy

• Nodes must not silently swallow errors. Log at the appropriate severity,
  then take a safe action (stop motion, request help, transition to error state).
• Prefer lifecycle node error transitions over ad-hoc boolean flags.
• When calling a service, always handle the "service not available" and
  "future timed out" cases explicitly.
• For hardware drivers, distinguish transient errors (retry with backoff)
  from fatal errors (transition to FINALIZED and alert the operator).

6. Quality of Service defaults

Start from these profiles and adjust per use case:

QoS mismatches are the #1 cause of "I published but nobody receives."
Always check compatibility with ros2 topic info -v when debugging.

DEADLINE and LIFESPAN are critical for safety-critical systems. DEADLINE fires an
event when no message arrives within the specified period (detect stale data). LIFESPAN
discards messages older than the specified duration before delivery (prevent acting on
stale data). See references/communication.md section 9 for full API and examples.

7. Naming conventions

8. Thread safety and callbacks

• A MutuallyExclusiveCallbackGroup serializes its callbacks — safe for
  shared state without locks, but limits throughput.
• A ReentrantCallbackGroup allows parallel execution — you must protect
  shared state with std::mutex (C++) or threading.Lock (Python).
• Calling a service from a callback: If the callback registers the
  request asynchronously — rclcpp: async_send_request(request, response_callback);
  rclpy: future = client.call_async(request) then
  future.add_done_callback(...) — and returns without waiting for the
  result, the same MutuallyExclusiveCallbackGroup does not deadlock.
  Deadlock comes from waiting synchronously inside the callback —
  rclcpp: calling get()/wait()/wait_for() on a not-yet-complete
  future from the initiating callback, or spin_until_future_complete
  (inside the response callback the future is already complete, so get()
  there is safe — the examples use exactly that); rclpy: synchronous
  Client.call(), spin_until_future_complete, or a loop that blocks
  until future.done(). (rclpy's future.result() by itself does not
  block — it immediately returns whatever result is currently stored,
  which may be unset.) A synchronous wait needs the
  client in a different callback group or a ReentrantCallbackGroup, plus
  a matching executor configuration (e.g. MultiThreadedExecutor). Do not assume plain-executor
  async def callback patterns are safe until tested with your executor;
  Lyrical's rclpy.experimental.AsyncNode is a separate execution model
  that officially supports await client.call(...) inside callbacks.
• Never do blocking work (file I/O, long computation, sleep) inside a
  timer or subscription callback on the default executor. Offload to a
  dedicated thread or use a MultiThreadedExecutor with a reentrant group.
• In rclcpp, prefer std::shared_ptr<const MessageT> in subscription
  callbacks to avoid unnecessary copies; whether intra-process delivery is
  actually copy-free additionally depends on publish ownership, subscriber
  count, and QoS (Principle 2).

9. Lifecycle-first design

Default to lifecycle (managed) nodes for anything that owns resources:
hardware drivers, sensor pipelines, planners, controllers. The managed
state machine (unconfigured → inactive → active, with cleanup,
shutdown, and error transitions) gives the system manager explicit
control over when resources are allocated, when processing starts, and how
shutdown proceeds — and makes error recovery predictable. Configure-only
transitions also enable hardware-safe config validation
(references/testing.md section 4). Full state diagram and callbacks:
references/lifecycle-components.md.

10. Build and CI hygiene

• Use colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo for
  development; Release for deployment.
• Enable -Wall -Wextra -Wpedantic and treat warnings as errors in CI.
• Run colcon test with --event-handlers console_cohesion+ so test
  output groups by package.
• Pin rosdep keys in rosdep.yaml for reproducible dependency resolution.
• Cache /opt/ros/, .ccache/, and build//install/ in CI to cut build
  times by 60–80%.

11. Source-first behavior verification

Distro labels are not enough when exact behavior matters — patch releases
change parameter names, plugin behavior, and defaults. Before asserting how
an installed stack behaves, identify the installed version (ros2 pkg xml,
dpkg-query -W) and read what ships with it: reference configs, headers,
and the source tag matching that version. Worked Nav2 procedure:
references/navigation.md section 6.

12. Motion-safety defaults

Never generate configs that can move an unvalidated robot. Motion
recoveries (Spin/BackUp) stay opt-in until robot geometry, locomotion
response, and clearance are validated — actuation-free recovery comes
first. Velocity limits come from the safe operational ceiling, never the
SDK/API maximum. For hardware checks, prefer configure-only lifecycle
validation with hardware isolation (references/testing.md section 4).
Details: references/navigation.md sections 7 and 10.

Common anti-patterns

AI pitfalls — traps this skill has learned from

These are mistakes AI agents repeatedly make when generating ROS 2 code.
Add a new line here every time a failure is discovered in practice.

> Maintenance rule: When you encounter a new AI failure pattern while using this
> skill, append it to this table with the next sequential number. The pitfall list
> is the single most valuable section for preventing repeated mistakes.

Distro-specific migration notes

<!-- LAST_UPDATED: 2026-03-30 — Keep in sync with the distro table in Principle 1. -->
When upgrading between distributions, check these breaking changes first:

• Foxy → Humble: complete API overhaul (lifecycle, actions stabilized in Humble);
  ros2_control was not bundled in Foxy; Nav2 renamed recoveries_server →
  behavior_server and nav2_recoveries/ → nav2_behaviors/ (Galactic → Humble
  migration — pre-Humble recovery naming does not exist on Humble). Plan a rework,
  not a port.
• Humble → Jazzy: ros2_control 2.x → 4.x — interface exports auto-generated,
  get_value() → get_optional<T>(), spawner uses --param-file, all <ros2_control>
  joints must exist in the URDF (details: references/hardware-interface.md); default
  bag format sqlite3 → MCAP (storage_id='mcap'); ROS_AUTOMATIC_DISCOVERY_RANGE
  replaces ROS_LOCALHOST_ONLY; launch_ros parameter handling changed — retest
  launch files.
• Jazzy → Kilted (non-LTS): Zenoh Tier 1 (RMW_IMPLEMENTATION=rmw_zenoh_cpp);
  experimental EventsExecutor gains an rclpy port (still rclcpp::experimental);
  ament_target_dependencies() deprecated — use target_link_libraries() with modern
  CMake targets; Gazebo pairing is Ionic (Harmonic was Jazzy); multi-bag replay in
  ros2 bag play.
• Kilted → Lyrical (LTS): primary platform moves to Ubuntu 26.04; default RMW
  stays rmw_fastrtps_cpp; new non-experimental rclcpp::executors::EventsCBGExecutor
  (distinct from the experimental EventsExecutor); ros2_control moves to the 6.x
  series — verify per-package changes against the installed versions (Principle 11).
• ROS 1 → ROS 2: see references/migration-ros1.md for a step-by-step strategy.

Quick reference — ros2 CLI

See references/debugging.md §10 "Quick CLI reference" for the full
command cheat sheet (workspace, introspection, ros2_control, debugging,
lifecycle). Kept out of this always-loaded file to preserve context budget.