Agent skill

MoveIt SRDF Authoring

by earthtojake in earthtojake/text-to-cad

Authors and validates MoveIt2 SRDF files on top of an existing URDF: planning groups, end effectors, group states, passive joints and disabled collisions.

MITAuto-check passedDevelopment

Install MoveIt SRDF Authoring

skills CLI
$ npx skills add earthtojake/text-to-cad --skill srdf -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install earthtojake/text-to-cad srdf --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/earthtojake/text-to-cad.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/srdf .claude/skills/srdf && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
srdf
GitHub stars
19k
Token cost
~2.8k tokens
SKILL.md length
1,541 words
Files
9 (incl. references)
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

Authors and validates MoveIt2 SRDF files on top of an existing URDF: planning groups, end effectors, group states, passive joints and disabled collisions.

  • Works in 12 steps: Start from a valid URDF. Author or fix… → Extract the URDF table. Before writing… → Identify the planning task. Record… → …
  • Creating or editing a MoveIt SRDF for an existing URDF
  • SKILL.md covers Setup, Format boundary, Show the model and Required workflow, plus 4 more sections
  • Calls uvx and git

What it does

SRDF holds MoveIt planning semantics on top of an existing valid URDF: virtual joints, passive joints, planning groups, group states, end effectors and disabled collision pairs. The `.srdf` XML is the source of truth and is edited directly, since there is no generator. URDF keeps physical structure and SDF keeps simulator content, so geometry, inertials, joint origins, limits, transmissions and `ros2_control` interfaces stay out of SRDF.

The skill treats correctness as a planning-semantics problem: the usual failure is a plausible file that gives MoveIt the wrong group, tool link or default state, or an unsafe disabled-collision matrix. The agent therefore derives these from the URDF topology, Setup Assistant output, sampled collision analysis or your explicit data, extracts the link and joint table first and copies names from it rather than typing from memory. It runs the `cadgen` tool through uv, shows you each file it writes, and reference notes cover the authoring contract, disabled collisions, end effectors, validation and the planning ledger.

When your agent uses it

  • Creating or editing a MoveIt SRDF for an existing URDF
  • Defining planning groups, end effectors and group states for a robot arm
  • Reviewing a disabled-collision matrix for safety
  • Validating an SRDF before handing it off for review

Example prompts

  • “Write an SRDF for this URDF with an arm planning group and a gripper end effector.”
  • “Check whether the disabled collision pairs in my SRDF are safe.”
  • “Add a home group state to the manipulator group in robot.srdf.”

Requirements

  • uv, to run the cadgen tool
  • A valid URDF for the robot

Workflow steps

12 steps, taken from the first numbered list in SKILL.md.

  1. Start from a valid URDF. Author or fix the URDF first with $urdf and validate it. The SRDF pairs with that URDF by colocation and robot…
  2. Extract the URDF table. Before writing any SRDF XML, list the URDF's robot name, links, joints (with type, parent, child, limits, mimic…
  3. Identify the planning task. Record whether the goal is arm IK, gripper control, mobile base planning, dual-arm planning, tool use, or…
  4. Create or update the planning ledger. Use references/planning-ledger.md before writing XML; keep a compact copy as a comment block in the…
  5. Pair with the URDF by colocation. Save the .srdf in the same folder as its .urdf, with the same — that is the only linking mechanism. The…
  6. Define virtual and passive joints deliberately. Use them when needed by the robot model.
  7. Define planning groups from URDF topology. Prefer chain groups for serial manipulators when base/tip form a real parent-to-child path in…
  8. Define end effectors after group membership is known. Avoid overlap between an end-effector group and its parent group. Record the actual…
  9. Define group states in URDF-native units. Revolute and continuous values are radians; prismatic values are meters. Do not store degrees in…
  10. Generate disabled collisions from evidence. Use adjacency derived from the URDF joint table, MoveIt Setup Assistant sampling, or explicit…
  11. Validate every created or modified .srdf with cadgen srdf validate; it cross-validates all names, chains, states, and pairs against the…
  12. Run MoveIt smoke tests when available. Use MoveIt Setup Assistant or a project MoveIt launch directly.

What it can do on your machine

Read from SKILL.md and the folder at commit b48ff49. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • uvx
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • docs.astral.sh

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

MoveIt SRDF Authoring loads about 2.8k tokens when it runs, and up to ~7.4k if it reads all its reference files. Until then it costs about 115 tokens; SKILL.md has 1,541 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~115
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~7.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from earthtojake/text-to-cad at commit b48ff49, republished under its MIT licence (© earthtojake). 1,541 words, ~2,836 tokens.

Download SKILL.mdSave it as .claude/skills/srdf/SKILL.md (or your agent's skills folder). This skill also uses 8 other files; get the full folder from GitHub.
name
srdf
description
MoveIt2 SRDF authoring, validation, and planning-semantics workflow. Use when creating, editing, inspecting, or validating `.srdf` files, MoveIt planning groups, virtual joints, passive joints, end effectors, group states, disabled collisions, URDF-paired planning semantics, or SRDF handoff for live review. Use the URDF skill for robot structure and the SDF skill for simulator descriptions. Open and visually review existing SRDF files in CAD Viewer.
license
MIT

SRDF

Provenance: maintained in earthtojake/text-to-cad. Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.

Use this skill for MoveIt semantic robot descriptions on top of an existing valid URDF. SRDF defines planning semantics; it does not define physical robot structure. The .srdf file is the source of truth: author and edit the XML directly. There is no gen_srdf() contract.

SRDF correctness is a planning semantics problem. The common failure is not invalid XML; it is a plausible SRDF that gives MoveIt the wrong planning group, wrong tool link, wrong default state, unsafe disabled-collision matrix, or wrong joint units. Because language models are weak at spatial and kinematic reasoning, derive planning groups, end effectors, group states, and disabled collisions from the URDF topology, MoveIt Setup Assistant output, sampled collision analysis, or explicit user data. Do not infer them from visual theme alone — and do not type any link or joint name from memory: extract the URDF's link/joint table first and copy names from it.

Setup

Run cadgen through uv, so this skill's commands share one installation, and its warm build daemon, with the CAD app's server:

  • cadgen below means uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.20 cadgen
  • python below means uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.20 python

The first run downloads that installation and the first snapshot its headless browser; later runs reuse both.

Format boundary

  • URDF owns physical robot structure: links, joints, geometry, inertials, limits, mimic joints, transmissions, and robot-state publishing.
  • SRDF owns MoveIt semantics: virtual joints, passive joints, planning groups, group states, end effectors, and disabled collision pairs.
  • SDF owns simulator/world semantics: physics, sensors, lights, plugins, worlds, and simulation-specific metadata.

Do not place geometry, inertials, joint origins, link poses, mesh references, physical joint limits, transmissions, or ros2_control interfaces in SRDF.

Show the model

Show the user each file you create or change, and any they ask to see. Snapshots and validation don't replace this.

  • If your tools include cad_show (your host may prefix it), use it with the file's absolute path, and follow its description for when to call it again. cad_view reads what the user selected; cad_screenshot shows you what they see. Neither is a review of your own work.

  • Otherwise run the CAD Viewer, from any folder:

    bash
    cadgen viewer --host 127.0.0.1 --json --detach

    --detach returns once the viewer answers requests and leaves it running in the background: always pass it, since a foreground viewer never exits (and piping its output through tail can hide the URL for good). It starts this machine's one viewer, or reuses it. Read url from its one JSON line (never guess the port), and for each file return url?file=<its URL-encoded absolute path>. If it fails to launch, say so.

Keep the SRDF beside its uniquely matching URDF (same robot name). Review planning groups, named states and joints; visual review does not prove planning correctness.

Required workflow

  1. Start from a valid URDF. Author or fix the URDF first with $urdf and validate it. The SRDF pairs with that URDF by colocation and robot name, and every name in the SRDF must exist in it.
  2. Extract the URDF table. Before writing any SRDF XML, list the URDF's robot name, links, joints (with type, parent, child, limits, mimic flags). Copy names from this table only; never type them from memory. See references/srdf-workflow.md.
  3. Identify the planning task. Record whether the goal is arm IK, gripper control, mobile base planning, dual-arm planning, tool use, or local smoke testing.
  4. Create or update the planning ledger. Use references/planning-ledger.md before writing XML; keep a compact copy as a comment block in the .srdf.
  5. Pair with the URDF by colocation. Save the .srdf in the same folder as its .urdf, with the same <robot name> — that is the only linking mechanism. The validator and the viewer both resolve the pairing by scanning the folder for the URDF whose robot name matches; exactly one URDF per robot name per folder. No metadata element links the files. See references/authoring-contract.md.
  6. Define virtual and passive joints deliberately. Use them when needed by the robot model.
  7. Define planning groups from URDF topology. Prefer chain groups for serial manipulators when base/tip form a real parent-to-child path in the URDF tree (the validator verifies this). Use joint/link/subgroup definitions only when they are deliberate.
  8. Define end effectors after group membership is known. Avoid overlap between an end-effector group and its parent group. Record the actual target/TCP link.
  9. Define group states in URDF-native units. Revolute and continuous values are radians; prismatic values are meters. Do not store degrees in SRDF. Values must lie within URDF limits and must not set fixed or mimic joints.
  10. Generate disabled collisions from evidence. Use adjacency derived from the URDF joint table, MoveIt Setup Assistant sampling, or explicit user-provided collision matrices. Do not invent broad disable lists. See references/disabled-collisions.md.
  11. Validate every created or modified .srdf with cadgen srdf validate; it cross-validates all names, chains, states, and pairs against the paired URDF. Fix findings and re-validate until clean.
  12. Run MoveIt smoke tests when available. Use MoveIt Setup Assistant or a project MoveIt launch directly.
  13. Report assumptions and skipped checks. Include incomplete validation, missing MoveIt environment, manually reasoned collision disables, and inferred target links.
Show full SKILL.md (663 more words)Show less

Commands

Run cadgen as Setup defines it. cadgen doctor <skill-dir> reports the installation in use and checks that it is the one this skill pins — docs drift silently on another. Validation itself needs nothing beyond the Python standard library; only snapshots need the browser. Use cadgen <verb> --help for the complete current interface.

The validator shape is:

bash
cadgen srdf validate path/to/robot.srdf
cadgen srdf validate path/to/robot.srdf --strict
cadgen srdf validate path/to/robot.srdf --json

The validator parses the SRDF, resolves the paired URDF (the same-folder .urdf whose robot name matches; none, several, or an invalid one is an error), and cross-validates: group/joint/link/subgroup name existence, chain path resolvability, subgroup cycles, virtual/passive joints, end-effector topology, group-state membership/limits/completeness, disabled-collision pairs (including Adjacent-reason truthfulness), and misspelled elements. Each phase collects all its findings in one pass (severity, code, XML path), but a structural error stops the cross-file phase — re-run after every fix. One run validates ONE file: --strict treats warnings as failures and --json prints one line of {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}, where element is the XML path. It exits nonzero if the target fails. Relative targets resolve from the current working directory.

Hard rules

  • The SRDF lives in the same folder as its URDF and shares its <robot name>; that colocation-plus-name match is the only pairing mechanism, and exactly one URDF per robot name may exist in the folder.
  • Every link, joint, group, and subgroup name must come from the URDF table or a group defined in the same file.
  • Group states use URDF-native units: radians for revolute/continuous, meters for prismatic.
  • Disabled collision pairs require truthful reasons and provenance.
  • End-effector groups should not share links with their parent planning group.
  • Visual rendering review is useful but cannot prove planning correctness.

Snapshot Tool

cadgen snapshot renders the robot to a PNG still, using the same shared CLI and headless browser runtime every rendering skill uses — so a snapshot matches what the CAD Viewer shows.

bash
cadgen snapshot path/to/robot.srdf review.png

Hand it the .srdf; it routes by suffix and renders the paired URDF's geometry — the same-folder .urdf whose <robot name> matches, exactly as cadgen srdf validate pairs them. No match, or more than one, is refused before anything renders, naming the robot name it looked for and the .urdf files it found. Pose the robot with --joint-values — {joint: degrees} JSON, joints you do not name staying where the CAD Viewer opens the robot: each at its default, then this SRDF's home group state if it declares one (the "jointValues" job field is the same thing in a packet). The snapshot draws the robot with the viewer's own scene, so it shows what the viewer shows, and a link mesh that cannot be loaded fails it rather than leaving the link out. Robots are authored in metres and are framed on the robot scene scale automatically.

A normal snapshot uses the Solid preset and Light appearance; omitted groups inherit preset defaults. Pass --display render for the shared photographic scene. Inline display JSON and JSON files use grouped settings such as lighting, background, and floor; appearance is light (default) or dark. Projection and focal length belong in display.camera. Top-level --camera and --joint-values remain active in every display mode. The display modes are solid and render: edges, clip, exploded, the xray, hidden-line and wireframe modes and the hidden/off surface styles describe a STEP model's CAD edges, parts and solids, and are refused by name here.

Link meshes are resolved relative to the description, so they must be present: an unhydrated Git LFS pointer fails as "No link mesh loaded for robot". Run git lfs checkout <mesh dir> first.

An SRDF's geometry comes from its paired URDF, so it has no snapshot door of its own; the polymorphic cadgen snapshot routes one by suffix. The grammar is cadgen snapshot TARGET [OUT] [flags], the same one every format door uses. Use cadgen snapshot --help for the complete current interface.

References

  • Authoring contract (structure, URDF pairing, golden skeleton): references/authoring-contract.md
  • SRDF workflow (URDF table extraction, edit loop): references/srdf-workflow.md
  • Planning ledger: references/planning-ledger.md
  • Validation and verification recipe: references/validation.md
  • End effectors: references/end-effectors.md
  • Disabled collisions: references/disabled-collisions.md

© earthtojake, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 8 other files (references) in skills/srdf of earthtojake/text-to-cad.

  • SKILL.md
  • LICENSE
  • agents/openai.yaml
  • references/authoring-contract.md
  • references/disabled-collisions.md
  • references/end-effectors.md
  • references/planning-ledger.md
  • references/srdf-workflow.md
  • references/validation.md

Open the folder on GitHubat commit b48ff49

Compare with similar skills

MoveIt SRDF Authoring next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

MoveIt SRDF Authoring compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
MoveIt SRDF Authoring this skillearthtojake/text-to-cad19k—~2.8kAutomated safety check: PassMIT
Code Review ChecklistshareAI-lab/learn-claude-code78k4 repos~1.1kAutomated safety check: PassMIT
Minimizing Ty Ecosystem Changesastral-sh/ruff50k—~4.6kAutomated safety check: PassMIT
Merge Dependabot PRsonyx-dot-app/onyx32k1 repos~2.2kAutomated safety check: PassMIT
Summarise Ecosystem Resultsastral-sh/ruff50k—~2.2kAutomated safety check: PassMIT
Senior Architect Toolkitmaslennikov-ig/claude-code-orchestrator-kit2608 repos~1.2kAutomated safety check: NotesCustom licence

Similar skills

  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 4 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Official

    A skill your agent uses when a user says "minimize this ty ecosystem change", "reproduce this ecosystem result", "investigate a primer difference", "investigate a mypyprimer difference"…

    50k GitHub stars~4.6k tokensUpdated today
    DevelopmentAuto-check passed
  • Merge Dependabot PRs

    onyx-dot-app/onyx

    Triages and lands a batch of open Dependabot PRs in the Onyx repo, where main is gated exclusively by GitHub's merge queue: approves and enqueues green PRs, closes superseded duplicates, fixes…

    32k GitHub starsUsed in 1 repo~2.2k tokens
    DevelopmentAuto-check passed
  • Official

    A skill your agent uses when a user says "summarise ecosystem results", "summarize this ty ecosystem report", "what changed in this ecosystem run?", or asks to summarise or summarize ty ecosystem…

    50k GitHub stars~2.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Senior Architect Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin…

    260 GitHub starsUsed in 8 repos~1.2k tokens
    DevelopmentAuto-check: notes
  • Kedro Babysit

    kedro-org/kedro

    Run Kedro's local lint / format / type-check / tests on changed files (uses the project's pre-commit hooks, ruff, mypy, pytest, lint-imports, detect-secrets, Make targets — in the right venv), or…

    11k GitHub stars~4k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

More from earthtojake/text-to-cad

All 12 skills in this repo
  • DfAM Printability Check

    earthtojake/text-to-cad

    Measures STL, OBJ, PLY or 3MF mesh files against additive manufacturing design limits and reports printability findings for each print process.

    19k GitHub starsUsed in 2 repos~1.5k tokens
    Auto-check passed
  • Step Parts

    earthtojake/text-to-cad

    Find, evaluate, and download common purchasable CAD parts from step.parts, including named off-the-shelf actuators, servos, motors, electronics boards, connectors, screws, bolts, nuts, washers…

    19k GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check passed
  • Design for Manufacturing Review

    earthtojake/text-to-cad

    Guided DFM review of a part for sheet metal, CNC machining or injection molding, covering bends, tool access, draft and undercuts, with evidence-first measurement rules.

    19k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • DXF Drawing Generation

    earthtojake/text-to-cad

    Generates, regenerates and validates 2D DXF drawings from Python build123d sources for profiles, gaskets, panels and cut layouts, and reviews them in CAD Viewer.

    19k GitHub starsUsed in 1 repo~4.3k tokens
    Auto-check passed
  • OrcaSlicer G-code Slicing

    earthtojake/text-to-cad

    Slices STL, 3MF or OBJ models into printer-ready G-code with OrcaSlicer, either headless from the command line or by opening the model in the app.

    19k GitHub stars~989 tokensUpdated yesterday
    Auto-check passed
  • URDF Robot Description Authoring

    earthtojake/text-to-cad

    Guides writing, editing and validating URDF robot description files, with a design ledger, exact frame semantics and computed inertials checked by a validator.

    19k GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed

Works with

Categories

Questions about MoveIt SRDF Authoring

What does MoveIt SRDF Authoring do?

Authors and validates MoveIt2 SRDF files on top of an existing URDF: planning groups, end effectors, group states, passive joints and disabled collisions. SRDF holds MoveIt planning semantics on top of an existing valid URDF: virtual joints, passive joints, planning groups, group states, end effectors and disabled collision pairs.srdf` XML is the source of truth and is edited directly, since there is no generator.

When should I use MoveIt SRDF Authoring?

MoveIt SRDF Authoring fits situations like: creating or editing a MoveIt SRDF for an existing URDF; defining planning groups, end effectors and group states for a robot arm; reviewing a disabled-collision matrix for safety; validating an SRDF before handing it off for review.

How do I install MoveIt SRDF Authoring in Claude Code?

Run `npx skills add earthtojake/text-to-cad --skill srdf -a claude-code`. Or copy the skill folder (skills/srdf in earthtojake/text-to-cad) into .claude/skills/srdf in your project. Claude Code loads it when a task matches its description.

How do I install MoveIt SRDF Authoring in Codex?

Run `npx skills add earthtojake/text-to-cad --skill srdf -a codex`. Or copy the skill folder (skills/srdf in earthtojake/text-to-cad) into .agents/skills/srdf in your project. Codex loads it when a task matches its description.

Can I use MoveIt SRDF Authoring in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add earthtojake/text-to-cad --skill srdf -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/srdf, .gemini/skills/srdf, .github/skills/srdf and .opencode/skills/srdf in your project.

What does MoveIt SRDF Authoring need to run?

Going by SKILL.md and its folder, MoveIt SRDF Authoring needs the command-line tools its instructions call (uvx and git). Our summary lists: uv, to run the cadgen tool; A valid URDF for the robot.

Does MoveIt SRDF Authoring access the network?

SKILL.md names 1 domain. As links in the text: docs.astral.sh. This is read from the text; nothing was executed.

Is MoveIt SRDF Authoring safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does MoveIt SRDF Authoring use?

MoveIt SRDF Authoring is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does MoveIt SRDF Authoring use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.6k tokens, read only when the agent opens those files.

What are the alternatives to MoveIt SRDF Authoring?

Skills that share tags, products or a category with MoveIt SRDF Authoring: Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars), Minimizing Ty Ecosystem Changes (astral-sh/ruff, 50k stars), Merge Dependabot PRs (onyx-dot-app/onyx, 32k stars) and Summarise Ecosystem Results (astral-sh/ruff, 50k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains MoveIt SRDF Authoring?

earthtojake (a GitHub user) maintains it in earthtojake/text-to-cad, which has 18,839 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 10, 2026.

Source: earthtojake/text-to-cad on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.