# Text-to-CAD Community Forum: Skills-Based Architecture and Developer Guide

> Join the Text-to-CAD community forum for collaborative CAD, URDF, and G-code generation. Explore our skills-based architecture and developer guide. Contribute today!

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

---

**The Text-to-CAD community forum operates on a modular, skills-first architecture where independent agents for CAD, URDF, and G-code generation collaborate through shared packages and a unified web viewer.**

The earthtojake/text-to-cad repository provides the open-source foundation for this ecosystem, organizing functionality into self-contained skills that communicate via deterministic validation pipelines and a browser-based preview system. Every skill operates in isolation, importing shared functionality exclusively from the `packages/` directory to ensure modularity and maintainability.

## Core Architecture of the Text-to-CAD Ecosystem

The repository is structured around three foundational concepts that enable community collaboration: isolated skills, reusable packages, and a universal viewer.

### Skill Isolation and Independence

Each skill (`cad`, `urdf`, `gcode`) resides as an independent entity under the `skills/` directory and exposes a command-line interface governed by a **Skill Manifest** ([`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md)). Skills never import from one another; instead, they access shared utilities through vendored packages. For example, [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) defines the CAD skill's capabilities, while [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) governs robot description generation.

### Shared Packages Ecosystem

Reusable runtime code lives in the `packages/` directory, serving as the single source of truth for geometry operations:

- **`packages/cadpy`** – Pure-Python utilities for STEP/GLB generation, topology extraction, and metadata handling.
- **`packages/implicitjs`** – GLSL-based signed-distance field CAD that runs directly in the browser, powering the `implicit-cad` skill.
- **`packages/cadjs`** – Low-level 3-D rendering helpers consumed by the viewer.

These packages are vendored into each skill's runtime during the bundling process orchestrated by [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).

### The Viewer as Collaboration Hub

The `viewer/` directory contains a lightweight Vite-based web application that supports STEP, STL, GLB, URDF, SDF, SRDF, and G-code formats. Skills hand off file URLs to this viewer via the `$cad-viewer` command, enabling instant browser-based inspection of generated artifacts. Configuration details for port handling and directory cataloging are documented in [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md).

## Working with Skills in the Text-to-CAD Forum

Contributors interact with the ecosystem through a standardized four-stage workflow that ensures quality and reproducibility.

### Directory Structure and Skill Manifests

Each skill subdirectory contains:

- [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) – Human-readable description and usage guide
- [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) – Skill-specific Python dependencies
- `agents/` – Optional LLM agent configuration ([`openai.yaml`](https://github.com/earthtojake/text-to-cad/blob/main/openai.yaml))
- `scripts/` – Executable entry points (`step`, `inspect`, `snapshot`)
- `references/` – Markdown guardrails and workflow diagrams

The [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) file at the repository root defines repository-level policies, symlink workflows, and contribution rules that all community members must follow.

### The Four-Stage Workflow

1. **Generate** – Execute `scripts/step` with either a **build123d** Python generator (`--generator`) or import existing STEP files (`--input`).
2. **Validate** – Run `scripts/inspect` to produce deterministic validation reports listing selector facts, planes, and positioning data.
3. **Snapshot** – Capture visual PNG/GIF packets using `scripts/snapshot` for documentation and regression testing.
4. **Hand-off** – Invoke `$cad-viewer` to open the artifact in the browser, or print a viewer URL for asynchronous review.

This pipeline enforces the repository's **STEP-first** policy, where STEP remains the primary artifact and STL/3MF/GLB are derived side-car files.

## Essential Commands and File References

Community members use the Skills CLI to install and execute functionality. The following commands assume execution from the repository root with the appropriate Python interpreter (`./.venv/bin/python`).

Install the complete skill set:

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

```

Generate a STEP part from Python:

```bash
python scripts/step \
  --kind part \
  --generator src/my_part.py \
  --output my_part.step

```

Import and validate existing geometry:

```bash
python scripts/step \
  --kind part \
  --input existing_part.step \
  --output existing_part_checked.step

```

Inspect topology and metadata:

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

```

Create visual snapshots:

```bash
python scripts/snapshot my_part.step \
  --output snapshots/

```

Launch the viewer:

```bash
cad-viewer --dir "$(pwd)/models" file=my_part.step

```

### Key Source Files

| File | Purpose |
|------|---------|
| [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) | CAD skill description and workflow defaults |
| [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) | URDF generation and validation guide |
| [`packages/implicitjs/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/implicitjs/README.md) | Implicit CAD runtime documentation (GLSL SDF) |
| [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md) | Viewer startup and configuration |
| [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) | Master bundler for skill runtimes |
| [`models/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/models/README.md) | Authoritative file-type policy for generated assets |
| [`tests/python/global/test_models_directory_policy.py`](https://github.com/earthtojake/text-to-cad/blob/main/tests/python/global/test_models_directory_policy.py) | Enforcement of file-type policies |

## Development Standards and Contribution Workflow

The Text-to-CAD community follows strict conventions to maintain code quality and deterministic outputs.

### Symlink-First Development

The `develop` branch contains symlinks pointing to real source in `packages/` and `viewer/`. Contributors must edit the symlink targets, not the symlinks themselves, to prevent configuration drift. The [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) document outlines this workflow and repository policies in detail.

### Deterministic Validation Requirements

Every CAD generation must run `scripts/inspect` and `scripts/snapshot`; failures are logged and require re-run after minimal fixes. The test suite, accessible via [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh), includes Python and JavaScript validation runners that enforce these standards across all contributions.

## Summary

- The Text-to-CAD community forum is built on a **skills-first architecture** where independent agents (`cad`, `urdf`, `gcode`) operate without cross-imports.
- Shared functionality resides in `packages/cadpy`, `packages/implicitjs`, and `packages/cadjs`, vendored during bundling via [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).
- The **four-stage workflow** (Generate → Validate → Snapshot → Hand-off) ensures STEP-first artifacts and deterministic validation.
- Contributors follow a **symlink-first development model** defined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) to maintain repository integrity.
- The Vite-based viewer (`viewer/`) supports immediate preview of STEP, URDF, and G-code files through the `$cad-viewer` command.

## Frequently Asked Questions

### How do I add a new skill to the Text-to-CAD repository?

Create a new directory under `skills/` containing a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest, [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt), and executable scripts in a `scripts/` subdirectory. Ensure your skill imports shared utilities exclusively from `packages/` and never from other skills. Follow the symlink-first workflow documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) when developing locally.

### What is the difference between `scripts/inspect` and `scripts/snapshot`?

`scripts/inspect` performs topological validation and extracts metadata facts (planes, positioning, selectors) from STEP files, producing deterministic text reports. `scripts/snapshot` generates visual artifacts (PNG and GIF renders) for documentation and regression testing. Both are required steps in the generation pipeline.

### Why does the repository use STEP as the primary format instead of STL?

STEP files retain precise boundary representation (B-rep) data and topological information necessary for accurate editing and parameterization, whereas STL is a triangulated mesh format. The **STEP-first** policy ensures that all derived formats (STL, 3MF, GLB) maintain fidelity to the original design intent and can be re-imported for modification.

### How do I preview my generated files without installing CAD software?

Launch the built-in viewer using `cad-viewer --dir /path/to/models` or `npm --prefix viewer run serve`. This browser-based application, configured via `viewer/vite.config.mjs`, renders STEP, STL, GLB, URDF, SDF, SRDF, and G-code files without requiring external CAD installations.