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

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

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:

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:

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:

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, automatically handles artifact hand-off between generation and visualization.

Exporting Secondary Formats

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

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 – Defines the CAD skill workflow, CLI entry points, and STEP-first assumptions
• packages/cadpy/README.md – Documents the Python helper library for STEP generation and assembly management
• AGENTS.md – Documents repository layout, symlink strategy, and release workflow guidelines
• scripts/dev/setup-symlinks.sh – Configures the development environment required for develop branch work
• 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.

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.

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