# How to Create and Edit CAD Models Using the CAD Skill

> Learn to create and edit CAD models with the CAD Skill. Use this Python CLI tool with @step decorators to build, inspect, and validate parametric CAD parts and assemblies from text.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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.

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/references/step-generation.md), this contract ensures the script can be compiled, cached, and exported to standard CAD formats.

Create [`src/bracket.py`](https://github.com/earthtojake/text-to-cad/blob/main/src/bracket.py) with the following structure:

```python

# 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.

```bash

# 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`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```bash

# 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.

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

```

This command, detailed in [`references/inspection-and-validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/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.

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

```

As outlined in [`references/snapshot-review.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.