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

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:

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 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
Generation CLI	skills/cad/scripts/step/cli.py
Entry point wrapper	scripts/step

The CLI at 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:

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:

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:

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 documents optional export pipelines. For STL generation via the shared library:

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:

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 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 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. 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 manifests and scripts/ subdirectories. They consume shared libraries from packages/ without requiring changes to other skills. The skills/cad/references/supported-exports.md documents the extension pattern for export pipelines.

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