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

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). Skills never import from one another; instead, they access shared utilities through vendored packages. For example, skills/cad/SKILL.md defines the CAD skill's capabilities, while 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.

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.

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 – Human-readable description and usage guide
• requirements.txt – Skill-specific Python dependencies
• agents/ – Optional LLM agent configuration (openai.yaml)
• scripts/ – Executable entry points (step, inspect, snapshot)
• references/ – Markdown guardrails and workflow diagrams

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

npx skills install earthtojake/text-to-cad

Generate a STEP part from Python:

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

Import and validate existing geometry:

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

Inspect topology and metadata:

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

Create visual snapshots:

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

Launch the viewer:

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

Key Source Files

File	Purpose
skills/cad/SKILL.md	CAD skill description and workflow defaults
skills/urdf/SKILL.md	URDF generation and validation guide
packages/implicitjs/README.md	Implicit CAD runtime documentation (GLSL SDF)
viewer/README.md	Viewer startup and configuration
scripts/bundle/bundle.sh	Master bundler for skill runtimes
models/README.md	Authoritative file-type policy for generated assets
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 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, 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.
• 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 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 manifest, 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 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.

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