claude-ros2-skills

Claude Code Skills for ROS 2 Jazzy Jalisco robotics development.

Anti-hallucination reference skills — every skill routes to official docs instead of guessing API names.

English | 한국어 | 中文 | 日本語 | Español | Français | Deutsch

Skills	Always-loaded router	Doc links (CI-checked)	Robot ground-truth checks	Evals: hallucinated params
11	30 lines	101	4 scripts	21 → 0

Contents

• Why this exists
• What makes this different
• Evals
• Quickstart
• Skills
• Verification scripts
• How it works
• Updating
• Contributing
• License

Why this exists

Logs prove a system is consistent, never that it's correct — and an agent has no default reason to distrust a consistent story. Two failure modes keep coming up:

Both come from trusting something that looks authoritative instead of checking ground truth. ros2-troubleshooting forces physical checks (push the robot, echo the raw TF, confirm IMU gravity) before trusting a topic. Every other skill applies the same rule to code: verify class names, messages, and flags against official Jazzy docs or /opt/ros/jazzy/ — never from memory.

What makes this different

Most robotics skill packs bake API knowledge into the skill files. That works until the ecosystem moves — then every baked-in snippet is a fact that can silently rot. This repo makes the opposite bet:

The trade-off, stated plainly: for topics where official docs are thin (DDS vendor tuning, PREEMPT_RT internals), a content-heavy pack can serve you better. This repo optimizes for one thing — the lowest probability of plausible-looking code that doesn't run on Jazzy.

Evals

Measured, not claimed — with one disclosed caveat: the runs were executed and graded by the repo author's own agent session, not an independent party. Every artifact is committed for third-party re-grading. Identical prompts ran in fresh headless Claude Code sessions with and without the skills installed (same model per pair); outputs were graded symbol-by-symbol against the pinned Jazzy sources.

Full grading tables, conditions, and every generated artifact: evals/RESULTS.md · protocol and checklists: evals/README.md — n=1 per cell so far; PRs adding graded transcripts are welcome.

Two patterns worth naming: with a strong model the skills turn "probably right" into "verified right"; with a smaller model they're the difference between a config that cannot start and the correct one. And in a run where verification tools were unavailable, the with-skills agent refused to emit unverified parameters rather than guess — the baseline never noticed it hadn't checked anything.

Quickstart

Option A — plugin marketplace (recommended):

/plugin marketplace add Leehyunbin0131/claude-ros2-skills
/plugin install claude-ros2-skills@claude-ros2-skills

Updates land with /plugin marketplace update.

Option B — manual copy:

git clone https://github.com/Leehyunbin0131/claude-ros2-skills.git

# Project-level (this project only)
mkdir -p your-project/.claude/skills
cp -r claude-ros2-skills/skills/* your-project/.claude/skills/
cp claude-ros2-skills/CLAUDE.md your-project/

# OR user-level (all projects)
mkdir -p ~/.claude/skills
cp -r claude-ros2-skills/skills/* ~/.claude/skills/

Restart Claude Code (or start a new session) to pick up the skills.

Skills

Verification scripts

scripts/ turns the physical checks into runnable pass/fail facts (needs a sourced ROS 2 env; each exits 0 = PASS, 1 = FAIL, 2 = no data):

The pure decision logic is unit-tested without ROS (python3 scripts/test_checks.py) and runs in CI on every push.

How it works

flowchart LR
    A["your request"] --> B["CLAUDE.md<br/>30-line router,<br/>no API details"]
    B --> C["skills/&lt;name&gt;/SKILL.md<br/>doc links +<br/>verified symbol names"]
    C --> D["official Jazzy docs<br/>or /opt/ros/jazzy/"]
    D --> E["code"]

CLAUDE.md never inlines API details — it just routes. Each SKILL.md is a thin catalog of official documentation links plus the exact class/message/param names, so Claude verifies instead of guessing. See CLAUDE.md.

Updating

cd claude-ros2-skills
git pull
cp -r skills/* ~/.claude/skills/   # or your project's .claude/skills/

Contributing

Short version — skills stay doc-link catalogs (not tutorials), every symbol gets verified against Jazzy docs or /opt/ros/jazzy/, scripts keep their pure logic unit-testable without ROS. Full rules, the skill/script checklists, and issue templates: CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.