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

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 (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 (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 (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 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

# 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

# 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

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

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