# What Text Prompts Work Best with text-to-cad: Patterns for Reliable CAD Generation

> Discover the best text prompts for text-to-cad generation. Learn patterns with verb-first structures, dimensions, and units for precise CAD creation.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: best-practices
- Published: 2026-09-13

---

**The most effective text-to-cad prompts use a verb-first structure with explicit dimensions, clear units, and reference links to existing parts, allowing the `$cad` skill agent to parse instructions into precise CAD operations.**

The earthtojake/text-to-cad repository implements a prompt-aware CAD generation system where natural-language instructions map directly to parametric modeling operations. Understanding what text prompts work best with text-to-cad requires analyzing how the underlying skill agents parse intent, handle geometric references, and route outputs to the integrated viewer.

## Architecture of the $cad Skill Agent

The text-to-cad system processes prompts through a pipeline of variable expansion, grammatical parsing, and output routing defined across several key architectural files.

### Default Prompt Configuration

The core CAD skill is configured in [`skills/cad/agents/openai.yaml`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/agents/openai.yaml) (lines 1-6), which defines the **default_prompt** instructing the LLM to "create, regenerate, inspect, and validate explicit CAD files and selector refs". This YAML configuration establishes the operational vocabulary—`create`, `regenerate`, `inspect`, and `validate`—that the parser recognizes as action verbs.

### Variable Expansion Pipeline

Before the LLM processes a request, tokens like `$cad`, `$step-parts`, and `$urdf` undergo variable expansion, replacing abstract skill references with concrete handler functions. This preprocessing ensures the prompt reaches the language model with contextually relevant definitions already injected.

### Reference Grammar and Parsing

The system supports persistent object references using the grammar defined in [`packages/cadgen/src/cadgen/cad_ref_syntax.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cad_ref_syntax.py) (lines 9-30). Ref strings follow the pattern `part.stl#o1.2`, combining a file identifier with an object selector targeting specific faces, edges, or sub-assemblies. These references survive copy-paste operations, enabling precise iterative editing without losing the geometric context.

### URL Normalization and Viewer Routing

When skills generate artifacts, [`packages/cadgen/src/cadgen/viewer/url_norm.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/url_norm.py) (lines 1-20) normalizes viewer URLs that embed prompts. Generated geometry files (STEP, STL, 3MF, or GLB) automatically route to the `$cad-viewer` for immediate visual feedback, creating a tight loop between text instruction and visual verification.

## Six Elements of Effective text-to-cad Prompts

High-performance prompts combine specific structural elements that the skill parser extracts as parameters for the CAD kernel.

**Verb-First Instructions** – Start with action verbs (`create`, `regenerate`, `inspect`, `validate`) to set the operational mode. Example: `Create a 20 mm × 20 mm × 5 mm rectangular plate`.

**Explicit Geometry Types** – Declare the output format to determine the export module. The default is STEP; specify `export as STL` or `export as 3MF` when mesh formats are required.

**Clear Dimensions and Units** – Provide unambiguous numeric values with units. CAD kernels require explicit units (e.g., `12 mm`, `0.5 in`) to prevent fallback to default measurements that may not match your design intent.

**Reference Links** – When modifying existing parts, include ref strings like `gear.step#o3` to target specific components. This syntax directs the regenerator to edit that object rather than create new geometry from scratch.

**Constraints and Tolerances** – For manufacturable designs, specify thickness, clearance, or material constraints. Example: `Ensure a minimum wall thickness of 0.8 mm`.

**Styling Modifiers** – Free-form adjectives (`smooth`, `filleted`, `rounded`) are interpreted as CAD modifier parameters during geometry generation, allowing aesthetic instructions to affect parametric operations.

## Working with CAD References and Selectors

The ref syntax implemented in [`cad_ref_syntax.py`](https://github.com/earthtojake/text-to-cad/blob/main/cad_ref_syntax.py) enables surgical editing of complex assemblies. A reference like `part.stl#o1.2` combines the filename (`part.stl`) with an object selector (`#o1.2`) that survives copy-paste operations into new prompts. When you write `Enlarge the gear.step#o3 tooth by 15%`, the parser isolates the specific sub-assembly `o3` within `gear.step` and applies the dimensional modifier only to that topological entity.

## Executable Prompt Examples

The following patterns demonstrate the syntax for common text-to-cad workflows.

### Basic Part Creation

```python

# Define a simple mechanical part with explicit dimensions

prompt = """
Create a rectangular base plate 100 mm long, 50 mm wide, 5 mm thick.
Add a 12 mm diameter hole centered 30 mm from each long edge.
Export as STEP.
"""

# Execute via Skills CLI: $ cad "$prompt"

```

### Editing via Object Reference

```python

# Modify an existing part using the ref syntax

prompt = """
Enlarge the tooth on gear.step#o3 by 10%.
Add a fillet of 2 mm to all new edges.
Maintain a minimum wall thickness of 0.8 mm.
Export as STL.
"""

# Execute via Skills CLI: $ cad "$prompt"

```

### Multi-Skill Workflow with URDF

```python

# Combine robotic description with CAD generation

prompt = """
Use $urdf to add a new link named "gripper" with a visual mesh "gripper.stl".
Place the gripper 0.1 m forward of the existing "wrist" link.
Then, with $cad, create a simple gripper geometry (two 30 mm fingers, 10 mm thick).
Export both URDF and the STL.
"""

# Execute: $ urdf "$prompt" then $ cad "$prompt"

```

## Integration Methods for text-to-cad Prompts

You can submit optimized prompts through three primary interfaces, each leveraging the same underlying pipeline.

**Skills CLI** – Install the repository (`npx skills add earthtojake/text-to-cad`) and execute prompts via `npx skills run $cad "<prompt>"`. This method provides direct access to the variable expansion and routing logic.

**CAD Viewer Interface** – Paste prompts directly into the viewer's chat window. The validation logic in `apps/viewer/src/shared/viewerConfig.mjs` (lines 150-165) sanitizes input and confirms command structure before forwarding to skill agents.

**Programmatic Python API** – Import the generation module (`import cadgen; cadgen.run_prompt(prompt)`) to invoke the skill pipeline directly from Python applications, bypassing the CLI for automated workflows.

## Summary

- **Verb-first syntax** with `create`, `regenerate`, `inspect`, or `validate` sets the correct operational mode for the `$cad` skill agent.
- **Explicit units** and dimensional tolerances prevent the CAD kernel from falling back to incorrect default values.
- **Ref strings** (`filename.step#oX`) enable precise editing of existing parts without regenerating entire assemblies.
- **Output format declarations** (STEP, STL, 3MF, GLB) determine which export module processes the final geometry.
- **Prompt validation** occurs in `viewerConfig.mjs` before commands reach the agent pipeline, ensuring malformed requests fail early.

## Frequently Asked Questions

### What file formats does text-to-cad support for export?

The `$cad` skill supports STEP as the default parametric format, plus mesh formats including STL, 3MF, and GLB. Specify your preferred format with phrases like `export as STL` or `export as 3MF` in the prompt; otherwise, the system defaults to STEP as configured in the agent YAML.

### How do I reference a specific face or edge in an existing CAD file?

Use the ref syntax defined in [`packages/cadgen/src/cadgen/cad_ref_syntax.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cad_ref_syntax.py): append `#o` followed by the object index to the filename. For example, `gear.step#o3` targets the third topological object in `gear.step`. This selector survives copy-paste operations and allows you to command operations like `fillet gear.step#o3.edges` or `enlarge gear.step#o3 by 10%`.

### Can I combine multiple CAD operations in a single text-to-cad prompt?

Yes. The prompt parser in the `$cad` skill accepts compound instructions containing multiple verbs and constraints. You can combine creation, modification, and validation steps—such as creating a base plate, adding holes, and applying fillets—within one prompt string. The agent extracts each operation sequentially and generates the corresponding geometry.

### Where is prompt validation handled in the text-to-cad codebase?

Prompt validation occurs in `apps/viewer/src/shared/viewerConfig.mjs` (lines 150-165) when using the viewer interface, and within the Skills CLI dispatcher when using command-line execution. These validation layers check for supported verbs, valid ref syntax, and recognized export formats before forwarding the request to the OpenAI agent defined in [`skills/cad/agents/openai.yaml`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/agents/openai.yaml).