How to Create and Edit CAD Models Using the CAD Skill

The CAD Skill is a command-line interface that wraps the cadgen package to build, inspect, and validate parametric CAD parts and assemblies from Python scripts decorated with @step.

According to the earthtojake/text-to-cad repository, the CAD Skill provides a document-door workflow where plain Python scripts serve as the single source of truth for parametric models. All generated files—STEP, STL, and mesh exports—are derived artifacts that should never be edited directly. Instead, you modify the source script and rerun the build pipeline to update outputs.

Setting Up the CAD Skill Environment

Before creating models, install the runtime dependencies in your environment. The CAD Skill requires the cadgen distribution and a headless browser for rendering snapshots.

python -m pip install -r requirements.txt
python -m playwright install chromium

These commands pull the core CAD generation library from packages/cadgen and install Chromium for the snapshot rendering engine used in the review workflow.

Creating Your First CAD Model Script

A CAD model is a plain Python script containing a single, parameter-less function decorated with @step. The function must return a build123d shape. As documented in references/step-generation.md, this contract ensures the script can be compiled, cached, and exported to standard CAD formats.

Create src/bracket.py with the following structure:

# src/bracket.py

from cadgen import build123d as bd
from cadgen import step

# ----- parameters (editable) -----

WIDTH = 30.0          # mm

THICKNESS = 5.0
HEIGHT = 20.0

# --------------------------------

@step                     # writes a STEP file next to this script

def bracket():
    """A simple rectangular bracket."""
    return bd.Box(WIDTH, THICKNESS, HEIGHT)
    
if __name__ == "__main__":
    bracket()            # triggers the build when the script is executed

The @step decorator, imported from cadgen, handles the export logic. When the script executes, it writes a .step file beside the source and records a content-addressed entry in ~/.cache/cadgen.

Building and Caching Models

Execute the Python script directly or use the cadgen CLI to trigger the build process. Both methods compile the script and store outputs in the local cache.

# Method 1: Direct execution

python src/bracket.py

# Method 2: Explicit CLI build

cadgen step build src/bracket.py out/BRACKET.step

The build process performs three operations defined in skills/cad/SKILL.md:

1. Compilation – Parses the @step decorator and executes the shape function
2. Caching – Stores a content-addressed record in ~/.cache/cadgen
3. Export – Writes the declared outputs (.step, .stl, .glb) to the filesystem

Editing and Rebuilding Models

To edit a model, modify the constants or geometry logic in the source script, then rerun the build command. The cache automatically detects changes and marks the model as stale, triggering a rebuild of only the affected parts while keeping dependent assemblies unchanged.

# Edit WIDTH in src/bracket.py, then rebuild

python src/bracket.py

Because the system tracks content hashes, identical scripts return cached results instantly, while modified scripts trigger fresh compiles. This incremental behavior is critical when managing multi-part assemblies where individual components update independently.

Inspecting and Validating Geometry

Validate dimensional accuracy and geometry facts using the inspection CLI tools. These commands analyze the generated STEP file without requiring you to open external CAD software.

cadgen step inspect refs src/bracket.step --facts --planes

This command, detailed in references/inspection-and-validation.md, displays selector references, positioning data, and geometric facts for verification against design specifications.

Rendering Snapshots for Review

Every model change requires a visual snapshot for review. The snapshot command renders a PNG image from the STEP file using the headless browser installed during setup.

cadgen step snapshot src/bracket.step tmp/bracket.png

As outlined in references/snapshot-review.md, this step is mandatory in the CAD Skill workflow before handing models to the Viewer skill or committing changes to version control.

Summary

• Single source of truth – Edit only the Python script decorated with @step; never modify generated STEP or mesh files directly.
• Decorator-based builds – The @step decorator in cadgen automates export and caching to ~/.cache/cadgen.
• Incremental rebuilds – The cache detects stale models and rebuilds only modified components.
• Validation pipeline – Use cadgen step inspect for geometric validation and cadgen step snapshot for visual review before finalizing designs.

Frequently Asked Questions

How does the CAD Skill handle model parameters?

The CAD Skill relies on constants defined at the module level in your Python script. When you change values like WIDTH or HEIGHT in src/bracket.py and rerun the script, the content-addressed cache detects the source change and regenerates the STEP file with the new dimensions.

Can I build multiple CAD models in one script?

Each model script should contain a single function decorated with @step that returns one build123d shape, as specified in references/step-generation.md. For assemblies, create separate scripts and reference them through the composition patterns documented in the project layout reference.

What file formats does the CAD Skill generate?

By default, the @step decorator exports .step files for CAD interoperability. The build system can also generate .stl for 3D printing and .glb for web viewing, depending on the export decorators applied to your function.

How do I view the CAD model after building it?

After running cadgen step build, hand off the generated STEP file to the CAD Viewer skill using $cad-viewer out/BRACKET.step. This opens an interactive viewer and returns a shareable link for collaborative review.

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