# Text-to-CAD Documentation: A Complete Guide to the Earthtojake Repository

> Explore comprehensive Text-to-CAD documentation for the Earthtojake repository. Learn to generate, validate, and visualize CAD artifacts with a skills-based architecture.

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

---

**The text-to-cad repository is a modular agent ecosystem for generating, validating, and visualizing CAD and robot-description artifacts using skills-based architecture with clear separation between generation, packages, and viewer components.**

The **text-to-cad** repository provides a comprehensive framework for converting natural language and code into manufacturable CAD models. Built around a **skills-based architecture**, it separates CAD generation, reusable libraries, and browser-based visualization into distinct, composable units. This documentation covers the repository structure, primary workflows, and key entry points for developers building agent-powered design pipelines.

---

## Text-to-CAD Repository Structure

The repository organizes code into three top-level domains defined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md):

### The Three Core Groups

- **`skills/`** – Self-contained skill packages for specific capabilities (CAD generation, URDF, SRDF, G-code, viewing)
- **`packages/`** – Reusable runtime libraries shared across skills (`cadjs`, `implicitjs`, `cadpy`)
- **`viewer/`** – Browser-based CAD Viewer application for presenting generated artifacts

This separation allows new skills to be added without modifying existing code. Shared functionality lives exclusively in `packages/`, while each skill maintains its own contract and entry points.

---

## Understanding Skill Design

Every skill follows a standardized layout. Each skill directory contains:

1. **[`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md)** manifest – declares name, description, and usage contract
2. **`scripts/`** subdirectory – houses the skill's executable code

### CAD Skill Example

The **CAD skill** (`skills/cad/`) demonstrates this pattern:

| Component | Path |
|-----------|------|
| Skill manifest | [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) |
| Generation CLI | [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py) |
| Entry point wrapper | `scripts/step` |

The CLI at [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py) handles parametric model generation via **build123d** Python source or STEP file import. It is invoked through the `scripts/step` wrapper.

---

## Primary Text-to-CAD Workflow

The standard pipeline moves from generation through validation to visualization:

### Step 1: Generate or Import STEP

Create a parametric model using Python source via `gen_step()` or import an existing STEP file:

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

```

### Step 2: Validate and Snapshot

The `scripts/inspect` tool checks geometry integrity, while `scripts/snapshot` produces reviewable PNG/GIF packets:

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

```

### Step 3: Launch CAD Viewer

The CAD Viewer skill starts a local Vite server and returns a direct URL to the artifact:

```bash
npm --prefix scripts/viewer run serve -- \
  --host 127.0.0.1 \
  --dir $(pwd)/models \
  --shutdown-after 12h \
  --json | tail -1 | jq -r '.url + "?file=my_part.step"'

```

The viewer URL format follows `?dir=<abs-dir>&file=<rel-path>` for direct artifact reference.

---

## Secondary Export Formats

The text-to-cad pipeline generates side-car artifacts from the primary STEP model. Supported formats include:

- **STL** – mesh for 3D printing
- **3MF** – modern manufacturing format
- **GLB** – web-optimized visualization
- **DXF** – 2D technical drawings
- **G-code** – machine tool instructions

The [`skills/cad/references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/supported-exports.md) documents optional export pipelines. For STL generation via the shared library:

```bash
python -m cadpy.glb --input my_part.step --export stl --out my_part.stl

```

---

## Key Packages and Shared Libraries

The `packages/` directory contains runtime libraries consumed by multiple skills:

| Package | Purpose | Location |
|---------|---------|----------|
| `cadpy` | Python STEP/GLB generation logic | `packages/cadpy/src/cadpy` |
| `cadjs` | JavaScript CAD utilities | `packages/cadjs` |
| `implicitjs` | Implicit surface operations | `packages/implicitjs` |

The `cadpy` package provides the core Python implementation for STEP and GLB generation used across the CAD skill pipeline.

---

## Quick Start: Installing Text-to-CAD

Install the repository via the Skills CLI:

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

```

Development occurs on the `develop` branch with symlinked layouts for generated runtime assets. Tests run per-language via `scripts/test/*.sh` on every push.

---

## Extending the System

New skills integrate without touching existing directories:

1. Create skill folder under `skills/`
2. Add [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest defining contract
3. Implement code in `scripts/` subdirectory
4. Consume shared libraries from `packages/` only

The `scripts/bundle/` utilities assemble final runtime bundles for deployment.

---

## Summary

- **Text-to-cad** uses a three-group architecture: `skills/`, `packages/`, and `viewer/` with clear separation of concerns
- Each skill requires a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest and `scripts/` subdirectory containing executable code
- Primary workflow: `scripts/step` → `scripts/inspect` → `scripts/snapshot` → viewer URL
- Secondary exports (STL, 3MF, GLB, DXF, G-code) derive from the canonical STEP model
- Shared functionality lives in `packages/cadpy`, `packages/cadjs`, and `packages/implicitjs`
- Installation via `npx skills install earthtojake/text-to-cad`

---

## Frequently Asked Questions

### What is the entry point for CAD generation in text-to-cad?

The primary entry point is `scripts/step`, which wraps [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py). This CLI accepts `--kind`, `--src`, and `--out` parameters to generate STEP models from Python source files using build123d or import existing STEP files.

### How does the text-to-cad viewer display generated models?

The viewer runs as a local Vite server started via `npm --prefix scripts/viewer run serve`. It accepts `--dir` and `--file` parameters to construct URLs in the format `?dir=<abs-dir>&file=<rel-path>`, enabling direct browser access to generated artifacts without file copying.

### Where is the shared Python CAD logic located in the repository?

The `packages/cadpy/src/cadpy` directory contains the shared Python implementation for STEP and GLB generation. This package is imported by the CAD skill and can be invoked directly via `python -m cadpy.glb` for export operations.

### Can I add new export formats to text-to-cad without modifying existing skills?

Yes. New skills are self-contained in `skills/<name>/` directories with their own [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifests and `scripts/` subdirectories. They consume shared libraries from `packages/` without requiring changes to other skills. The [`skills/cad/references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/supported-exports.md) documents the extension pattern for export pipelines.