Text-to-CAD Architecture: A Deep Dive into the Skills-Based CAD Pipeline

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/<skill>/ 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 — 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 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:

# 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, the public API exposes geometry construction and export:

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:

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 defines JSON-encoded request/response structures:

# 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 injects shared packages into each skill's runtime

4. CI validation — scripts/test/test.sh ensures symlink layout, package versions, and generated bundles remain synchronized

Practical Usage Examples

Generate a BOX with the Python API

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

Run the CAD Skill CLI

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

Launch the CAD Viewer

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 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 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, 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 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/<name>/ containing a SKILL.md descriptor, CLI scripts under scripts/, and vendored packages from packages/. Run scripts/bundle/bundle.sh to inject dependencies, then validate with scripts/test/test.sh before merging to main.

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