# Text-to-CAD Architecture: A Deep Dive into the Skills-Based CAD Pipeline > Explore the Text-to-CAD architecture a three layer system for AI to generate preview and export CAD artifacts through composable capabilities Learn more about this innovative skills based pipeline. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: architecture - Published: 2026-08-04 --- **The Text-to-CAD architecture implements a three-layer system—Skills, Shared Packages, and Viewer & Runtime—that enables AI agents to generate, preview, and export CAD and robot-description artifacts through isolated, composable capabilities.** The **text-to-cad** repository by earthtojake demonstrates a novel approach to generative CAD systems. Its architecture separates agent capabilities into self-contained **skills**, shares reusable geometry logic through language-agnostic **packages**, and provides local **viewer tools** for real-time preview. This design prioritizes isolation, reproducibility, and extensibility for AI-driven mechanical design workflows. ## The Three Core Layers of Text-to-CAD ### Skills Layer: Isolated Agent Capabilities Each skill in the text-to-cad architecture represents a standalone capability—such as CAD geometry creation, STEP/GLB export, URDF/SRDF generation, or G-code slicing. Skills reside under `skills//` and strictly **cannot import from other skills**. Shared functionality is accessed exclusively through the `packages/` layer, enforcing clean boundaries. A typical skill structure includes: - [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) — human-readable descriptor with capability documentation - `scripts/` — CLI entry points and implementation - `packages/` — vendored copies of shared libraries The **CAD skill** at `skills/cad/` demonstrates this pattern. Its descriptor at [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) links directly to source files, making capabilities discoverable for both agents and developers. The STEP generation CLI lives at [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py): ```python # Entry point for STEP file generation # File: skills/cad/scripts/step/cli.py ``` ### Shared Packages Layer: Reusable CAD Primitives The `packages/` directory contains language-specific libraries that power all skills. The **cadpy** Python package serves as the heart of the CAD pipeline. At [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py), the public API exposes geometry construction and export: ```python from cadpy.api import CadBuilder, ExportFormat builder = CadBuilder() builder.add_box(width=100, height=50, depth=20) builder.export(ExportFormat.STEP, path="output.step") ``` **Key shared packages include:** - **`packages/cadpy/`** — Core Python CAD engine with solid modeling and serialization - **`packages/cadpy_metadata/`** — Lightweight metadata helpers for URDF/SRDF generation - **`packages/cadjs/`** — JavaScript runtime for browser-based CAD rendering - **`packages/implicitjs/`** — Experimental GLSL-based implicit CAD engine Skills vendor these packages during bundling, ensuring each runtime carries its exact dependencies. ### Viewer & Runtime Layer: Local Preview and Interaction The text-to-cad architecture includes local tools for inspecting generated artifacts. The **CAD Viewer** (`skills/cad-viewer`) runs a Vite-based web server that serves an interactive UI for model inspection. The viewer reads from the `models/` catalog and accepts an absolute `?dir=` query parameter: ```bash npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models ``` For robot-description workflows, the **MoveIt2 server** translates viewer HTTP protocols into ROS-compatible robot data. Its protocol implementation at [`viewer/moveit2_server/moveit2_server/protocol.py`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/protocol.py) defines JSON-encoded request/response structures: ```python # Protocol handling for MoveIt2 integration # File: viewer/moveit2_server/moveit2_server/protocol.py ``` ## Build System and Development Workflow The text-to-cad repository maintains strict consistency through automated tooling: 1. **Branch structure** — Development occurs on `develop`; production builds originate from `main` 2. **Symlink management** — The `develop` branch uses symlinks pointing to true source locations; `scripts/dev/setup-symlinks.sh --check` validates these 3. **Package bundling** — [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) injects shared packages into each skill's runtime 4. **CI validation** — [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) ensures symlink layout, package versions, and generated bundles remain synchronized ## Practical Usage Examples ### Generate a BOX with the Python API ```python from cadpy.api import CadBuilder, ExportFormat builder = CadBuilder() builder.add_box(width=100, height=50, depth=20) builder.export(ExportFormat.STEP, path="box.step") ``` *Source: [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py)* ### Run the CAD Skill CLI ```bash npx skills install earthtojake/text-to-cad cad step create-box --width 100 --height 50 --depth 20 --out box.step ``` *Entry point: [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py)* ### Launch the CAD Viewer ```bash npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models ``` *Script: `viewer/scripts/start-agent-viewer.mjs`* ## Summary - **Three-layer architecture** separates skills (capabilities), packages (shared logic), and viewer/runtime (preview tools) - **Skill isolation** prevents cross-skill imports; all shared code flows through `packages/` - **cadpy API** at [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) provides the primary Python interface for geometry construction - **Automated bundling** ensures each skill runtime contains vendored, version-locked dependencies - **Local viewer tools** enable real-time inspection without external services ## Frequently Asked Questions ### How does the text-to-cad architecture enforce skill isolation? The repository strictly prohibits skills from importing code from other skills. The [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) policy document mandates that shared functionality must always be accessed through the `packages/` layer. This prevents hidden dependencies and makes each skill's capabilities fully explicit. ### What file format exports does cadpy support? According to the source at [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py), the `ExportFormat` enum includes **STEP**, **STL**, **3MF**, **GLB**, and **G-code** serialization options. Skills invoke these through the `CadBuilder.export()` method. ### Where is robot movement visualization implemented? The MoveIt2 integration lives in `viewer/moveit2_server/`. The protocol handler at [`moveit2_server/protocol.py`](https://github.com/earthtojake/text-to-cad/blob/main/moveit2_server/protocol.py) defines the JSON message format between the CAD Viewer UI and the ROS-style robot description server. ### How do I add a new skill to the text-to-cad repository? Create a directory under `skills//` containing a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) descriptor, CLI scripts under `scripts/`, and vendored packages from `packages/`. Run [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) to inject dependencies, then validate with [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) before merging to `main`.