What Is the URDF Skill in text-to-cad? Purpose, Validation, and Workflow Explained

The URDF Skill is a dedicated agent in the earthtojake/text-to-cad repository that authors, validates, and visualizes URDF robot-description files by wrapping the cadgen CLI and enforcing a strict workflow that ends with the CAD Viewer.

The URDF Skill serves as the central pipeline for producing standards-compliant robot models in the earthtojake/text-to-cad ecosystem. It bridges raw XML editing with automated validation and immediate visual feedback, ensuring every URDF file is technically correct and instantly reviewable. This skill integrates tightly with the cadgen distribution to provide a complete authoring environment.

Core Purpose of the URDF Skill

The URDF Skill manages the full lifecycle of robot description files through five distinct responsibilities defined in skills/urdf/SKILL.md.

Authoring and Editing with Design Ledgers

At the core of the skill is direct XML editing of .urdf files. Every file must include a design-ledger comment block that records frame conventions, units, and engineering assumptions. This ledger acts as a living document within the XML, ensuring context persists alongside the geometry. The specific rules for this workflow are documented in skills/urdf/SKILL.md (lines 30-38) and further detailed in skills/urdf/references/design-ledger.md.

Validation via cadgen urdf validate

Before any change is considered complete, the skill runs cadgen urdf validate. This command, implemented in packages/cadgen/src/cadgen/cli/urdf_validate.py, performs a comprehensive check of XML structure, topology, joint semantics, mesh references, and inertial data. The validation acts as a guard-rail rather than a proof of spatial correctness, catching syntax errors and semantic inconsistencies early. The build_parser function (lines 23-48) defines the CLI arguments, including the --strict flag to treat warnings as errors, and --json for machine-readable output.

Snapshot Rendering for Visual Verification

To guarantee visual parity with the final viewer, the skill invokes cadgen urdf snapshot. This command renders a PNG image of the robot using the same headless-browser runtime as the CAD Viewer. Described in skills/urdf/SKILL.md (lines 73-81) and implemented in packages/cadgen/src/cadgen/cli/urdf_snapshot.py, this tool provides immediate feedback on the robot's appearance without launching the full interactive viewer.

CAD Viewer Handoff

Following successful validation, the skill must invoke $cad-viewer with the URDF path. This command launches or updates the CAD Viewer and returns a link to the rendered model. This handoff, defined in skills/urdf/SKILL.md (lines 40-43), ensures every change is immediately inspectable in a 3D environment.

Workflow Integration

The skill references skills/urdf/references/urdf-workflow.md, an end-to-end guide that ties together ledger creation, mesh preparation, frame-semantic checks, validation, and viewer review. This document provides the canonical procedure for creating or editing URDF descriptions according to repository standards.

How to Use the URDF Skill: Command Reference

The following commands implement the URDF Skill's pipeline. These examples assume you have installed the skill's runtime dependencies.

First, install the required packages:

python -m pip install -r requirements.txt
python -m playwright install chromium

Validate a URDF file with increasing strictness:

# Basic validation

cadgen urdf validate path/to/robot.urdf

# Treat warnings as errors

cadgen urdf validate path/to/robot.urdf --strict

# Machine-readable JSON output

cadgen urdf validate path/to/robot.urdf --json

Render a visual snapshot:

cadgen urdf snapshot path/to/robot.urdf review.png

Hand off to the CAD Viewer:

$cad-viewer path/to/robot.urdf

Key Implementation Files

The URDF Skill spans multiple files across the repository:

• skills/urdf/SKILL.md: The human-readable skill manifest containing core rules, workflow steps, and command specifications.
• packages/cadgen/src/cadgen/cli/urdf_validate.py: The CLI adapter that invokes the cadgen.urdf.validate function, handling argument parsing via build_parser.
• packages/cadgen/src/cadgen/cli/urdf_snapshot.py: The CLI adapter for the snapshot rendering engine.
• skills/urdf/references/urdf-workflow.md: Complete end-to-end workflow guide for URDF creation.
• skills/urdf/references/design-ledger.md: Specification for the required comment-block ledger.
• skills/urdf/references/validation.md: Detailed validation and verification recipes including external tools.
• skills/urdf/references/frame-semantics.md: Canonical guide to URDF frame conventions, joint origins, and link frames.

Summary

• The URDF Skill provides a dedicated agent for authoring URDF files within the earthtojake/text-to-cad repository.
• It enforces a design-ledger requirement for documenting frame conventions and assumptions directly in the XML.
• Validation runs through cadgen urdf validate, checking structure, joints, meshes, and inertial data as implemented in packages/cadgen/src/cadgen/cli/urdf_validate.py.
• Snapshot rendering via cadgen urdf snapshot produces PNG previews using the same runtime as the CAD Viewer.
• The skill mandates a CAD Viewer handoff ($cad-viewer) to ensure every change is immediately reviewable in 3D.

Frequently Asked Questions

What does the URDF Skill validate in a robot description?

The skill validates XML structure, kinematic topology, joint semantics, mesh file references, and inertial data properties. The cadgen urdf validate command, defined in packages/cadgen/src/cadgen/cli/urdf_validate.py, acts as a guard-rail to catch syntax errors and semantic inconsistencies before rendering. It does not verify absolute spatial correctness or collision detection.

How does the URDF Skill integrate with the CAD Viewer?

After validation, the skill invokes $cad-viewer path/to/robot.urdf to launch or update the viewer instance. This handoff, specified in skills/urdf/SKILL.md, returns a link to the rendered model and guarantees that every validated URDF is immediately available for interactive 3D inspection.

What is the design ledger in URDF authoring?

The design ledger is a mandatory XML comment block that accompanies every URDF file edited through the skill. It records frame conventions, units, and engineering assumptions. This ledger provides essential context for collaborators and is specified in skills/urdf/references/design-ledger.md.

How do I render a visual snapshot of a URDF file?

Use the cadgen urdf snapshot command to generate a PNG image. This tool uses the same headless-browser runtime as the CAD Viewer, ensuring visual parity. For example: cadgen urdf snapshot robot.urdf preview.png. The implementation resides in packages/cadgen/src/cadgen/cli/urdf_snapshot.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}