Text-to-CAD Quick Start Guide: Generate CAD Models from Natural Language

The text-to-CAD repository transforms natural language prompts into manufacturing-ready STEP files using Build123d Python scripts, complete with validation tools and a web-based viewer for immediate visual feedback.

This guide walks through the earthtojake/text-to-cad repository, a modular library of agent skills that automate CAD generation and robot description workflows. The project follows a strict separation of concerns across skills, shared packages, and a lightweight viewer, making it straightforward to generate, inspect, and hand-off geometric artifacts. Whether you are creating individual parts or complex assemblies, this text-to-CAD quick start guide covers the essential architecture, CLI commands, and validation steps required to move from prompt to physical design.

Repository Architecture and Layer Design

The codebase organizes functionality into distinct layers to keep the system modular and extensible. Understanding these boundaries is critical for contributing new skills or debugging generation pipelines.

• Skills Layer: Individual capabilities reside under skills/<skill>/, each containing a markdown SKILL.md that documents its API and data flow. For example, skills/cad/SKILL.md defines the CAD generation contract, while skills/cad-viewer/SKILL.md handles visualization hand-offs.
• Packages Layer: Reusable runtime code lives in packages/. The packages/cadpy directory specifically houses Python helpers for STEP, STL, GLB, and URDF generation that multiple skills import.
• Viewer Layer: A lightweight web viewer located in viewer/ previews STEP, STL, GLB, G-code, and robot description files. Configuration is managed in viewer/vite.config.mjs.
• Benchmarks and Assets: Example models and visualizations sit in benchmarks/ and assets/. These are large binary files tracked with Git LFS to maintain lightweight repository clones.
• CI and Testing: The scripts/test/test.sh harness runs automated validation on the develop branch. Note that pull requests must target develop, while main remains a publish-only branch as defined in AGENTS.md.
• Documentation Site: A Next.js application in docs/ publishes the skill reference to https://www.cadskills.xyz, pulling markdown directly from the skills/ directory.

Installation and Environment Setup

Install the skill library using the preferred package manager method. This configures the CLI tools and symlinks required to run skills from any directory.

npx skills install earthtojake/text-to-cad

After installation, ensure Git LFS is initialized if you plan to access benchmark models or asset files stored in the repository. Remember that active development happens on the develop branch; direct commits to main are restricted according to the branching policy in AGENTS.md.

The Six-Step CAD Generation Workflow

The core workflow moves from natural language to a validated, viewable artifact. Each step corresponds to a specific script or skill in the repository.

1. Author the Build123d Source

Create a Python file that implements the gen_step() function. This function must return a Build123d object or assembly. Place reusable geometry logic in packages/cadpy to keep your source file clean.

# my_part.py

from build123d import *

def gen_step():
    return Box(10, 10, 5)

2. Generate the Primary STEP File

Run the STEP generation script, specifying whether the output is a part or assembly. This creates the primary artifact; all secondary exports (STL, 3MF, GLB) are derived from this file as documented in references/supported-exports.md.

python scripts/step my_part.py --kind part --out my_part.step

3. Inspect Geometry Selectors

Validate that the generated geometry matches your intent by inspecting faces, edges, and positioning data. This is crucial for assemblies where parts must interface correctly.

python scripts/inspect refs my_part.step --facts --planes --positioning

4. Create Visual Snapshots

Generate PNG snapshots for documentation or reviewer feedback. The snapshot command renders the STEP file from a standard camera angle.

python scripts/snapshot my_part.step --out snapshots/my_part.png

5. Launch the CAD Viewer

Start the local viewer server, binding to 127.0.0.1 and pointing the --dir flag to your absolute models/ path.

npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models

6. Hand Off to the Viewer

The viewer returns a JSON line containing a URL. Navigate to this address to preview your model. The URL follows the pattern:

http://127.0.0.1:4178/?dir=/absolute/path/to/text-to-cad/models&file=my_part.step

Alternatively, use the $cad-viewer skill to automate this hand-off from your agent workflow.

Locating Standard Components with $step-parts

Avoid modeling common hardware from scratch by using the $step-parts skill. This searches an internal library of off-the-shelf STEP components and returns an absolute file path ready for import.

step-parts find "M4 socket head cap screw"

Import the returned path directly into your assembly script to maintain accurate geometry for bolts, nuts, and standard structural elements.

Key Reference Files and Documentation

Navigate the codebase efficiently by bookmarking these critical files:

• README.md: Project overview, quick-start snippets, and screenshots.
• AGENTS.md: Repository policies, symlink layout, and the develop-versus-main branching strategy.
• skills/cad/SKILL.md: Complete CAD skill definition, including all CLI flags for scripts/step.
• skills/cad-viewer/SKILL.md: Viewer startup options and URL parameter specifications.
• scripts/step: Entry point for STEP generation. While this appears in the root scripts directory, the core logic is implemented in packages/cadpy.
• packages/cadpy: Reusable Python modules for geometric operations and file format conversions.
• scripts/test/test.sh: Entry point for the continuous integration test suite.
• docs/: Source for the public documentation site at cadskills.xyz.

Summary

• Install the environment with npx skills install earthtojake/text-to-cad and develop on the develop branch.
• Generate geometry by implementing gen_step() in Build123d and running python scripts/step to produce validated STEP files.
• Validate designs using scripts/inspect for geometric accuracy and scripts/snapshot for visual confirmation.
• Visualize models by serving the viewer from viewer/ and accessing the generated URL with absolute path parameters.
• Reference SKILL.md files in skills/ subdirectories for detailed API documentation and extension points.

Frequently Asked Questions

What is the primary output format of the text-to-CAD workflow?

The system treats STEP files as the single source of truth for all geometry. Secondary formats like STL, 3MF, and GLB are derived exports generated from this primary STEP artifact, ensuring dimensional consistency across manufacturing workflows.

How do I start the CAD viewer to preview my models locally?

Start the viewer by running npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models from the repository root. The process outputs a URL containing absolute path parameters; navigate to this link to inspect STEP, STL, or GLB files rendered in the browser.

Where is the core STEP generation logic implemented?

While you invoke generation via scripts/step in the root directory, the actual implementation resides in packages/cadpy. This package contains reusable Python helpers for constructing STEP data, handling STL tessellation, and generating URDF robot descriptions.

Can I use standard hardware like bolts and screws in my assemblies?

Yes. The $step-parts skill provides a CLI to locate off-the-shelf components. Running step-parts find "M4 socket head cap screw" returns a STEP file path that can be imported into your Build123d assembly, eliminating the need to model common fasteners manually.

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