| name | new_ros2_workspace |
| description | Bootstrap a complete ROS 2 colcon workspace from scratch — directory layout, .gitignore, top-level README, this .claude/ config, an interfaces package and a first Clean Architecture package, and a bringup package. Trigger when the user asks to create a new workspace / start a new ROS 2 project from zero. |
Bootstrapping a complete ROS 2 workspace
Use this when there is no workspace yet (the new_ros2_package skill
assumes one already exists). The goal is a ready-to-build colcon
workspace that already carries this template's .claude/ config, so
every later /new-* command works immediately.
Target layout
<workspace>/
├── .claude/ # this template's config (rules, skills, commands, agents)
├── .gitignore # ignores build/ install/ log/
├── README.md # how to build & run
├── src/
│ ├── <project>_interfaces/ # msgs/srvs/actions (ament_cmake), created first
│ ├── <project>_core/ # first Clean Architecture package
│ └── <project>_bringup/ # launch + params aggregator (ament_python)
├── build/ install/ log/ # generated by colcon (git-ignored)
Steps
1 — Create the workspace root + src/
mkdir -p <workspace>/src
cd <workspace>
git init
2 — Drop in the .claude/ config
Copy the template config so the workspace is self-documenting and the
slash commands are available:
cp -r <path-to>/ros2-claude-code-template/.claude <workspace>/.claude
If the user is inside the template repo already, this step is a no-op.
3 — .gitignore
build/
install/
log/
__pycache__/
*.pyc
4 — Top-level README.md
Include the canonical bring-up commands:
colcon build --symlink-install
source install/setup.bash
colcon test && colcon test-result --all
5 — Seed packages (use the package skill / /new-package)
Create them in dependency order:
<project>_interfaces — only if custom msgs/srvs/actions are
needed. ament_cmake + rosidl_default_generators (see
rules/ros2_communication.md). Create this first.<project>_core — the first real package, full Clean Architecture
layout (domain/application/infrastructure/presentation). Delegate to
the new_ros2_package skill or /new-package <name> <py|cpp>.<project>_bringup — ament_python, holds top-level launch/
and config/ that compose the system (see ros2_launch_config).
6 — First build
cd <workspace>
colcon build --symlink-install
source install/setup.bash
Do not run the build automatically unless the user asks — print the
commands instead.
Decisions to confirm with the user
- Workspace name / path (e.g.
~/my_robot_ws).
- Project prefix for package names (e.g.
acme).
- Domains needed — if the project is a fleet bridge, a controller
suite, a behavior-tree app, etc., point them at the matching
command afterwards (
/new-vda5050-connector, /new-controller,
/new-bt-node, /new-nav2-plugin, …).
- ROS distro — affects nothing in the layout but note it in the README.
After bootstrap
The workspace now supports the full command set. Typical next steps:
| Goal | Command |
|---|
| Add a package | /new-package <name> <py|cpp> |
| Add a node | /new-node <pkg> <name> <kind> <lang> |
| Add a launch file | /new-launch <pkg> <name> |
| Add a Nav 2 plugin | /new-nav2-plugin <kind> <Class> |
| Add a ros2_control controller / hardware | /new-controller / /new-hardware |
| Add a behavior-tree node | /new-bt-node |
| Add a VDA 5050 connector | /new-vda5050-connector |
Extend the .claude/ config itself | /new-skill, /new-command, /new-agent (skill extending_claude_config) |
Keep domain/ ROS-free, lifecycle by default for resource owners, and
declare_parameter for every parameter — the rules in .claude/rules/
apply from the first commit.
