# Text-to-CAD GitHub Repository: Modular Skills and Architecture Guide

> Explore the text-to-CAD GitHub repository for a modular, skill-first codebase. Generate CAD artifacts with self-contained agents and a React viewer. Learn more at earthtojake/text-to-cad.

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

---

**The text-to-CAD GitHub repository is a modular, skill-first codebase maintained by earthtojake that generates CAD and robot-description artifacts through self-contained agents, shared geometry packages, and a React-based viewer.**

The earthtojake/text-to-cad repository implements a strict three-layer architecture designed to isolate domain logic from shared utilities and infrastructure. This open-source project treats STEP generation, URDF creation, and implicit CAD modeling as discrete capabilities, each governed by strict contracts defined in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) files and powered by heavy-lifting packages like `implicitjs`.

## Text-to-CAD Repository Architecture: Three Core Layers

The codebase splits functionality into **skills**, **packages**, and **runtime tooling**. This separation ensures that geometry-processing logic remains pure and reusable while CLI entry points remain thin wrappers.

### The Skills Layer

Every skill lives under `skills/<skill-name>/` and functions as an independent agent that never imports code from another skill. Each skill contains its own [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) contract, source code, and reference documentation.

Key skills include:

- **CAD** (`skills/cad/`): Generates STEP parts with secondary exports to STL, 3MF, and GLB. According to [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md), STEP is treated as the primary artifact format.
- **URDF** (`skills/urdf/`): Produces robot description files with links to the CAD Viewer.
- **Implicit CAD** (`skills/implicit-cad/`): Handles signed-distance function (SDF) modeling.
- **G-code** (`skills/gcode/`): Generates manufacturing instructions.

Skills expose CLI entry points through thin wrappers located in `scripts/`. For example, `scripts/step` delegates to the CAD skill, while `scripts/inspect` provides artifact analysis.

### The Packages Layer

Located in `packages/`, these language-agnostic libraries provide the heavy lifting for geometry creation and metadata handling:

- **`implicitjs`** (`packages/implicitjs/`): A browser-native implicit CAD runtime that parses [`.implicit.js`](https://github.com/earthtojake/text-to-cad/blob/main/.implicit.js) modules, builds GLSL ray-march shaders, renders with Three.js, and exports to mesh formats. The public API surface in [`packages/implicitjs/src/index.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/src/index.js) exposes `loadImplicitModuleFromSource`, `renderImplicitToDataUrl`, and `exportImplicitModel`.
- **`cadpy_metadata`** (`packages/cadpy_metadata/`): Dependency-free utilities for generating STEP metadata, content hashes, and versioned artifact identifiers.

Other packages such as `cadjs` and `cadpy` are generated at build-time and vendored into skills during the bundle process.

### Runtime and Tooling

Supporting infrastructure glues the skills together for development and production:

- **`viewer/`**: A Vite-powered React application that displays generated CAD, G-code, and robot files. The `$cad-viewer` hand-off rule ensures every skill that produces an artifact also spawns a viewer link (`viewer?dir=…&file=…`).
- **`scripts/`**: Contains Bash, Node, and Python wrappers for skill CLIs, plus the bundling script at [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).
- **`.github/workflows/`**: CI pipelines running unit tests for Python and JavaScript, bundle verification, and deployment of documentation.
- **`benchmarks/`**: Git-LFS stored visualizations used for regression testing and demos.

## Working with Skills and SKILL.md Contracts

Each skill defines its behavior through a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file located in its root directory. These files specify the skill’s purpose, default assumptions, required workflow, hand-off policies, and links to reference documentation.

### Contract Structure

The [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) contract typically includes:

- **Workflow**: Step-by-step instructions for invoking the skill.
- **Hand-off policies**: Rules like `$cad-viewer` that trigger the viewer automatically.
- **References**: Pointers to auxiliary documentation in `references/*.md`, such as [`references/cad-brief.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/cad-brief.md) or [`references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/supported-exports.md).

For example, [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) mandates that generated STEP files include a topology sidecar in GLB format, while [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) defines constraints for robot joint descriptions.

## Implicit CAD Generation with the implicitjs Package

The `implicitjs` package demonstrates the repository’s philosophy of keeping UI concerns out of geometry libraries. It provides a single public API surface that any consumer—whether the viewer, CLI, or another skill—can integrate without dragging in React or DOM dependencies.

### Key API Functions

As implemented in [`packages/implicitjs/src/index.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/src/index.js):

- **`loadImplicitModuleFromSource(source)`**: Parses an [`.implicit.js`](https://github.com/earthtojake/text-to-cad/blob/main/.implicit.js) module string and returns an executable SDF model.
- **`renderImplicitToDataUrl(model, params)`**: Generates a PNG snapshot by compiling the SDF to a GLSL shader and ray-marching via Three.js.
- **`exportImplicitModel(model, format, params)`**: Samples the implicit surface and exports to STL, 3MF, or animated GLB formats using `exportImplicitAnimatedGlb`.

The accompanying CLI supports snapshot generation and export workflows without requiring a browser environment.

## Command-Line Usage Examples

### Generate a STEP Part from Python

To create a STEP file from a build123d script:

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

```

This produces `my_part.step` and a GLB topology sidecar, automatically triggering the `$cad-viewer` hand-off to open the CAD Viewer.

### Inspect Selector References

Analyze a STEP file for geometry facts, plane equations, and positioning data:

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

```

The tool parses selector tokens such as `#o1.2.f1` and reports the corresponding geometry metadata.

### Render an Implicit CAD Snapshot

Generate a PNG preview from an [`.implicit.js`](https://github.com/earthtojake/text-to-cad/blob/main/.implicit.js) model:

```bash
npm run snapshot -- --input models/sphere.implicit.js --output /tmp/sphere.png

```

This invokes `loadImplicitModuleFromSource` and `renderImplicitToDataUrl` to produce the image.

### Export an Animated GLB

Create a mesh file with animation from implicit parameters:

```bash
npm run export -- \
  --input models/sphere.implicit.js \
  --format glb \
  --output /tmp/sphere.glb \
  --params '{"radius":30}'

```

The command samples the SDF inside the model’s bounds using `exportImplicitAnimatedGlb` and writes the resulting GLB file.

### Run the Full Test Suite

Execute CI-like validation locally:

```bash

# Python skill tests

./.venv/bin/python -m unittest discover -s tests/python

# JavaScript package tests

npm --prefix packages/implicitjs test

# Full orchestration

./scripts/test/test.sh

```

## Key Files and Entry Points

Understanding the text-to-CAD repository requires familiarity with these paths:

- **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)**: Repository-level rules defining the branch strategy (`develop` for active work, `main` for bundled releases), symlink layout, and release workflow.
- **[`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)**: Canonical contract for the CAD skill, including hand-off policies and export format hierarchy.
- **[`packages/implicitjs/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/README.md)**: Complete API documentation for the implicit CAD runtime.
- **[`packages/implicitjs/src/index.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/src/index.js)**: Public entry point exporting the implicit CAD API.
- **[`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh)**: Build script that vendors packages into skills before publishing to `main`.
- **`viewer/vite.config.mjs`**: Vite configuration defining the development server and build pipeline for the CAD Viewer UI.

## Summary

- The **text-to-CAD GitHub repository** organizes functionality into three strict layers: self-contained **skills** (`skills/`), shared **packages** (`packages/`), and **runtime tooling**.
- **Skills** operate independently via CLI wrappers in `scripts/` and define contracts in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) files; they never import code from one another.
- The **`implicitjs`** package provides the heavy lifting for implicit CAD, exposing pure functions like `loadImplicitModuleFromSource` and `exportImplicitModel` in [`packages/implicitjs/src/index.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/src/index.js).
- **Development workflow** uses the `develop` branch for active work, bundles releases with [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh), and deploys to `main` with all packages vendored.
- The **CAD skill** treats STEP as the primary artifact, automatically generating GLB sidecars and triggering the viewer via the `$cad-viewer` hand-off policy.

## Frequently Asked Questions

### What is the text-to-CAD GitHub repository used for?

The text-to-CAD GitHub repository provides a modular framework for converting programmatic or natural language inputs into manufacturable CAD artifacts. It generates STEP files, URDF robot descriptions, implicit CAD models, and G-code instructions through a system of self-contained skills and shared geometry libraries.

### How does the skill architecture prevent coupling between components?

Each skill in `skills/<name>/` is a completely self-contained unit that, according to [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), never imports code from another skill. This ensures runtime independence and allows individual skills to be tested, bundled, and deployed in isolation. Skills communicate through well-defined CLI contracts and hand-off policies rather than internal APIs.

### What functions does the implicitjs package provide for developers?

The `implicitjs` package exposes a UI-agnostic JavaScript API for implicit CAD operations, including `loadImplicitModuleFromSource` for parsing [`.implicit.js`](https://github.com/earthtojake/text-to-cad/blob/main/.implicit.js) files, `renderImplicitToDataUrl` for generating PNG snapshots via Three.js shaders, and `exportImplicitModel` for writing STL, 3MF, or animated GLB outputs. These functions are implemented in [`packages/implicitjs/src/index.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/src/index.js) and can be consumed by any skill or the React viewer.

### How do I generate a STEP file using the repository?

Run the CAD skill CLI from the repository root using `python scripts/step --kind part my_part.py`, where [`my_part.py`](https://github.com/earthtojake/text-to-cad/blob/main/my_part.py) contains a build123d script defining a `gen_step()` function. This generates both a `.step` file and a topology sidecar, automatically opening the CAD Viewer through the skill’s `$cad-viewer` hand-off mechanism defined in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md).