What Is the Purpose of the CAD Skill in text-to-cad?

The CAD skill serves as the core engine for creating, modifying, inspecting, and validating STEP-first parametric CAD models from natural language specifications, reference images, or 2D technical drawings.

The CAD skill in the earthtojake/text-to-cad repository orchestrates a complete workflow that transforms text-based instructions into manufacturable 3D geometry. It treats STEP/STP files as the canonical artifact while optionally generating secondary mesh side-cars (STL, 3MF, GLB), ensuring a reproducible pipeline from concept to physical production.

Core Workflow and Primary Goals

According to skills/cad/SKILL.md (lines 12-15), the primary purpose of the CAD skill is to generate or edit parametric CAD models, validate the resulting STEP artifact, and return fully checked outputs. The skill handles requests for CAD geometry, assemblies, parametric features, selector references, measurements, and secondary mesh exports. It also processes reference images and 2D technical drawings when provided as input.

Dual Entry Paths for Model Creation

As documented in skills/cad/SKILL.md (lines 16-17), the skill supports two distinct entry paths that converge on the same inspection and validation pipeline:

Build123d Source Generation — The default path when designing from scratch. The skill generates Python source code using the build123d library, creating fully parametric geometry that can be version-controlled and modified later.

Direct STEP Import — Used when a generator does not exist or when the user explicitly targets an existing STEP file. This path bypasses source generation but still executes the same inspection and snapshot steps.

Standardized Assumptions and Coordinate System

The CAD skill operates under strict documented assumptions defined in skills/cad/SKILL.md (lines 28-38) to ensure consistency across all generated models:

• Units: Millimeters (mm)
• Base plane: XY
• Up direction: +Z
• Geometry type: Closed solids unless otherwise specified
• Positioning: Per references/positioning.md

Toolchain and Script Architecture

The skill leverages three primary CLI tools located in skills/cad/scripts/ to execute its workflow:

STEP Generation (scripts/step)

Implemented in skills/cad/scripts/step/cli.py, this tool generates STEP files from build123d Python source and exports optional side-car formats.

Geometric Inspection (scripts/inspect)

Located at skills/cad/scripts/inspect/cli.py, this tool performs geometric inspection, extracts facts about planes and positioning, handles measurements, and manages assembly alignment.

Visual Snapshots (scripts/snapshot)

Found in skills/cad/scripts/snapshot/cli.py, this tool creates PNG/GIF snapshot packets for human review, enabling visual verification of geometry before downstream use.

The 10-Step Validation Workflow

skills/cad/SKILL.md (lines 61-73) mandates a rigorous, repeatable workflow that ensures quality and traceability:

1. Classify the task
2. Load needed references
3. Write a CAD brief
4. Verify purchasable components
5. Plan parameters and labels
6. Edit source (never generated artifacts)
7. Run scripts/step
8. Validate with scripts/inspect
9. Snapshot the primary STEP
10. Repair and repeat if needed

Integration with the CAD Viewer

Upon successful completion of the workflow, the skill hands off the generated STEP (or secondary files) to the $cad-viewer skill, as described in skills/cad/SKILL.md (lines 74-80). This launches the CAD Viewer and returns a link for interactive review. Visual snapshots generated by scripts/snapshot are attached when available to facilitate human verification.

Non-Negotiable Constraints

The CAD skill enforces strict architectural rules documented in skills/cad/SKILL.md (lines 81-87):

• STEP is always primary: Secondary formats like STL, 3MF, and GLB exist only as side-cars for specific manufacturing workflows.
• Source-controlled geometry: All modifications must occur in the Python source files (build123d code), never in generated artifacts.
• Named parameters: All features must use named parameters and selector references to maintain parametric editability.

Practical CLI Examples

Below are runnable CLI snippets demonstrating the typical CAD skill workflow using the tools in skills/cad/scripts/:

# Generate STEP and optional side-cars from build123d source

python scripts/step models/enclosure.py \
  --stl meshes/enclosure.stl \
  --3mf meshes/enclosure.3mf \
  --glb meshes/enclosure.glb

# Inspect geometric facts, planes, and positioning

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

# Measure specific features using selectors

python scripts/inspect measure models/enclosure.step \
  --selector "#hole1" --dimension diameter

# Align parts in assemblies using datum references

python scripts/inspect align models/assembly.step \
  --source "#partA.datum1" --target "#partB.datum2"

# Create visual snapshot packets for human review

python scripts/snapshot models/enclosure.step \
  --views front top iso \
  --output snapshots/enclosure_snapshot.zip

Summary

• The CAD skill is the central orchestration layer for parametric CAD generation in the text-to-cad ecosystem.
• It mandates a STEP-first workflow where STEP files are the canonical artifact, and all other formats are secondary.
• The skill supports both build123d source generation and direct STEP import, converging on the same validation pipeline.
• Three core CLI tools—scripts/step, scripts/inspect, and scripts/snapshot**—handle generation, validation, and visualization respectively.
• Strict assumptions (mm units, XY base plane, +Z up) and a 10-step workflow ensure reproducible, inspectable results.
• Upon completion, artifacts are handed to the $cad-viewer skill for interactive visualization.

Frequently Asked Questions

What is the primary output format of the CAD skill?

The primary output is always a STEP/STP file. According to skills/cad/SKILL.md (lines 12-15), STEP is treated as the canonical CAD artifact, while formats like STL, 3MF, and GLB are generated only as secondary side-cars for specific manufacturing or visualization needs.

How does the CAD skill handle existing CAD files?

When a build123d generator does not exist or the user provides an existing file, the skill uses the Direct STEP Import path. As noted in skills/cad/SKILL.md (lines 16-17), this path bypasses source generation but still executes the full inspection and snapshot workflow to ensure the imported geometry meets project standards.

What are the measurement and alignment capabilities in the CAD skill?

The scripts/inspect CLI (located at skills/cad/scripts/inspect/cli.py) provides measurement tools using selector references (e.g., #hole1) and alignment operations that match source datums to target datums. This enables precise assembly construction and geometric verification against specifications.

Why does the CAD skill enforce editing source files rather than generated artifacts?

The skill requires all changes to be made to build123d Python source rather than generated STEP or mesh files. As specified in skills/cad/SKILL.md (lines 81-87), this ensures parametric editability, proper version control, and the ability to regenerate artifacts reproducibly. Editing generated binaries would break the parametric workflow and make future modifications impossible to track.

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