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

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 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 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, 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 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 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.
• .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 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 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 or references/supported-exports.md.

For example, skills/cad/SKILL.md mandates that generated STEP files include a topology sidecar in GLB format, while 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:

• loadImplicitModuleFromSource(source): Parses an .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:

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:

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 model:

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:

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:

# 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: Repository-level rules defining the branch strategy (develop for active work, main for bundled releases), symlink layout, and release workflow.
• skills/cad/SKILL.md: Canonical contract for the CAD skill, including hand-off policies and export format hierarchy.
• packages/implicitjs/README.md: Complete API documentation for the implicit CAD runtime.
• packages/implicitjs/src/index.js: Public entry point exporting the implicit CAD API.
• 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 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.
• Development workflow uses the develop branch for active work, bundles releases with 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, 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 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 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 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.

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