# What is text-to-CAD? A Library of Agent Skills for AI-Driven CAD Generation

> Explore text-to-CAD, an AI agent skill library for generating CAD geometry programmatically. Discover how it streamlines your design workflow with Python and build123d.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: getting-started
- Published: 2026-08-02

---

**text-to-CAD is a library of agent skills that enables AI-driven agents to programmatically generate, inspect, and export CAD geometry using a STEP-first workflow built on Python's build123d library.**

text-to-CAD is an open-source repository developed by earthtojake that provides AI agents with structured workflows for computer-aided design tasks. The project implements a modular skill architecture where each capability—from CAD generation to URDF export—operates as an isolated, self-contained unit. At its core, text-to-CAD follows a **STEP-first** philosophy, ensuring all geometric operations produce validated STEP files before optional secondary exports to formats like STL or GLB.

## Core Architecture of text-to-CAD

### The STEP-First Workflow

All CAD operations in text-to-CAD produce a validated STEP file as the primary artifact. According to [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md), this approach ensures geometric fidelity before generating secondary formats such as STL, 3MF, or GLB. The workflow guarantees that downstream inspection and viewer operations always reference a standardized, validated geometry source stored in the repository's `models/` directory.

### Skill Isolation and Structure

The repository organizes functionality into discrete skills under `skills/<skill>/` directories. As documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), each skill contains its own scripts, references, and agent definitions, with strict isolation preventing cross-skill imports. Shared runtime helpers live in `packages/` and are vendored into individual skill runtimes during execution. This architecture ensures that the CAD skill (`skills/cad/`), URDF skill, and G-code skill operate independently while sharing common utilities through the `packages/cadpy` library.

### Python CAD Engine via build123d

The `packages/cadpy` package provides the geometric foundation, wrapping the build123d library to generate STEP files from Python source. The `cadpy.assembly.AssemblyHelper` class and associated utilities in `packages/cadpy` handle the heavy lifting of solid modeling, assembly management, and format conversion. This pure-Python approach allows agents to define geometry programmatically rather than through traditional GUI-based CAD interfaces.

## Installing and Using text-to-CAD

### Installing the Skill Library

Deploy text-to-CAD skills into your agent runtime using the Skills CLI:

```bash
npx skills install earthtojake/text-to-cad

```

This command pulls individual skills and makes CLI commands available for CAD generation and inspection tasks.

### Generating STEP Models from Python

Create CAD geometry by implementing a `gen_step()` function in a Python file, then invoke the STEP generator:

```bash
python scripts/step --kind part my_part.py

```

This produces `my_part.step` as the primary artifact, alongside optional `my_part.stl` and snapshot PNG files for visualization. The script leverages `cadpy.assembly.AssemblyHelper` internally to process the Python source and emit validated STEP geometry.

### Inspecting Geometry Facts

After generation, extract geometric metadata using the inspection script:

```bash
python scripts/inspect refs my_part.step --facts --planes

```

This command, defined in the CAD skill's CLI, outputs dimensions, face normals, and datum locations critical for downstream validation and robotic integration.

### Running the CAD Viewer Locally

Preview generated artifacts using the browser-based CAD Viewer. Start the Vite-based server with:

```bash
npm --prefix scripts/viewer run serve -- --host 127.0.0.1 --dir /absolute/path/to/models --shutdown-after 12h --json

```

Access the viewer at the returned URL (e.g., `http://localhost:4178/?dir=/abs/models&file=my_part.step`) to interactively inspect STEP, STL, URDF, and GLB files. The viewer integration, documented in [`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md), automatically handles artifact hand-off between generation and visualization.

### Exporting Secondary Formats

Convert existing STEP files to mesh formats using the export functionality:

```bash
python scripts/step --export stl my_part.step
python scripts/step --export glb my_part.step

```

These commands generate `my_part.stl` and `my_part.glb` alongside the primary STEP file, enabling workflows for 3D printing and web visualization.

## Repository Structure and Key Files

Understanding the codebase layout is essential for extending text-to-CAD:

- **[`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)** – Defines the CAD skill workflow, CLI entry points, and STEP-first assumptions
- **[`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/README.md)** – Documents the Python helper library for STEP generation and assembly management
- **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)** – Documents repository layout, symlink strategy, and release workflow guidelines
- **[`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh)** – Configures the development environment required for `develop` branch work
- **[`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md)** – Instructions for the browser-based STEP/STL/GLB preview system and URL requirements

## Summary

- text-to-CAD is a modular library of agent skills for AI-driven CAD generation hosted at earthtojake/text-to-cad.
- The architecture enforces **STEP-first** workflows where all geometry validates as STEP before exporting to STL, 3MF, or GLB.
- Skills operate in isolation under `skills/<skill>/`, sharing code only through the `packages/cadpy` runtime helpers.
- Primary workflows use `python scripts/step` for generation and `python scripts/inspect` for geometric validation.
- The CAD Viewer provides browser-based inspection via `npm --prefix scripts/viewer run serve`.

## Frequently Asked Questions

### What is text-to-CAD used for?

text-to-CAD enables AI agents to programmatically generate mechanical parts, assemblies, and robot descriptions without human GUI interaction. The library supports workflows ranging from pure CAD generation to URDF/SDF export for robotics simulation, all while maintaining geometric validation through STEP files as implemented in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md).

### How does text-to-CAD differ from traditional CAD software?

Unlike traditional GUI-based CAD tools, text-to-CAD operates entirely through code and CLI commands, making it ideal for automated pipelines and AI agents. The repository wraps build123d in `packages/cadpy` to provide a programmatic interface via `cadpy.assembly.AssemblyHelper`, eschewing manual modeling in favor of Python-defined geometry generation.

### What file formats does text-to-CAD support?

text-to-CAD uses STEP as its canonical format, generating `.step` files as primary artifacts. Secondary exports include STL, 3MF, and GLB for 3D printing and visualization. The `scripts/step` CLI handles these conversions automatically when passed `--export` flags or when invoked with the `--kind part` parameter.

### Can I run text-to-CAD without installing the full AI agent framework?

Yes. While designed for agent integration, individual skills function as standalone CLI tools. You can execute `python scripts/step` and `python scripts/inspect` directly after installing Python dependencies from `packages/cadpy`, though the `npx skills install` method provides the intended runtime environment with proper symlink handling via [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh).