workspace-overlays

Name: workspace-overlays
Availability: InStock
Author: wimble

Explain ROS 2 workspace overlay precedence and environment path chaining.

18|2|Updated Apr 20, 2026

Search Tags:#workspace #environment #ros2 #overlay #ament_prefix_path

Ready to run

npx skills add https://github.com/wimblerobotics/ros2-copilot-skills --skill workspace-overlays

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: workspace-overlays
Source: https://github.com/wimblerobotics/ros2-copilot-skills/tree/main/workspace-overlays
Command: npx skills add https://github.com/wimblerobotics/ros2-copilot-skills --skill workspace-overlays

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ROS 2 projects commonly rely on layered workspaces where overlays take precedence over underlays. This skill guides understanding, debugging, and managing overlay chains to ensure predictable package resolution and environment configuration.

Core Features & Use Cases

Understands overlay priority and how setup.bash affects AMENT_PREFIX_PATH, PATH, and PYTHONPATH.
Provides two- and three-layer workflow examples to reproduce and resolve conflicts between overlays and underlays.
Use cases include overriding system packages with local workspaces, debugging build orders, and validating environment chains across terminals.

Quick Start

Source the underlay, build your overlays, and source your application workspace to verify the overlay chain.

Frequently Asked Questions about workspace-overlays

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do ROS 2 workspace overlays control package resolution?▼

ROS 2 workspace overlays control package resolution by chaining sourcing sequences that modify environment variables like AMENT_PREFIX_PATH, PATH, and PYTHONPATH, ensuring overlays take precedence over underlays for predictable package discovery.

How do I set up a multi-layer ROS 2 workspace overlay chain?▼

To set up a multi-layer ROS 2 workspace overlay chain, source the underlay first, build your overlays, and then source the application workspace to validate the precedence and verify the environment path chaining.

Why does sourcing order affect AMENT_PREFIX_PATH in ROS 2?▼

Sourcing order affects AMENT_PREFIX_PATH because executing setup.bash sequentially appends new workspace paths, directly controlling which overlay packages override the existing underlay packages in the resolution chain.

Can I override system packages with a local ROS 2 overlay?▼

Yes, you can override system packages with a local ROS 2 overlay by sourcing the local workspace setup.bash after the system underlay, which prioritizes local packages in the environment paths and package resolution.

Why are my ROS 2 overlay packages not overriding the underlay?▼

ROS 2 overlay packages fail to override underlays when sourcing order is incorrect, meaning the underlay setup.bash was sourced after the overlay, breaking the intended AMENT_PREFIX_PATH precedence chain.

How do I debug ROS 2 build order conflicts across overlay workspaces?▼

Debug ROS 2 build order conflicts by validating the sourcing sequence across terminals and checking environment variable effects like AMENT_PREFIX_PATH, PYTHONPATH, and PATH to ensure correct overlay precedence.