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

> Discover the purpose of the URDF Skill in text-to-cad. Learn how it authors, validates, and visualizes URDF files, streamlining your robot design workflow.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: deep-dive
- Published: 2026-09-11

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) (lines 30-38) and further detailed in [`skills/urdf/references/design-ledger.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) (lines 73-81) and implemented in [`packages/cadgen/src/cadgen/cli/urdf_snapshot.py`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

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

```

Validate a URDF file with increasing strictness:

```bash

# 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:

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

```

Hand off to the CAD Viewer:

```bash
$cad-viewer path/to/robot.urdf

```

## Key Implementation Files

The URDF Skill spans multiple files across the repository:

- **[`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/urdf_snapshot.py)**: The CLI adapter for the snapshot rendering engine.
- **[`skills/urdf/references/urdf-workflow.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/urdf-workflow.md)**: Complete end-to-end workflow guide for URDF creation.
- **[`skills/urdf/references/design-ledger.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/design-ledger.md)**: Specification for the required comment-block ledger.
- **[`skills/urdf/references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/validation.md)**: Detailed validation and verification recipes including external tools.
- **[`skills/urdf/references/frame-semantics.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/urdf_snapshot.py).