OpenSCAD Claude Code Skill

A Claude Code skill for programmatic 3D CAD using OpenSCAD. Design, preview, iterate, reconstruct from STL, and export 3D-printable models — with AI-driven visual feedback and automated mesh comparison.

Features

• Quick mode — One round trip from “I need a spacer” to a rendered part: assumptions are guessed, then listed back explicitly instead of asked for up front
• Modify mode — Edit an existing STL with booleans (import() + cut/add/trim) in minutes, without reconstructing it
• Printer calibration — Clearances descend from one measured profile, so a part fits on the first print instead of the third
• Programmatic 3D modeling — Generate .scad files from natural language descriptions
• AI vision feedback loop — Render multi-angle PNG previews and analyze them to iteratively refine designs
• STL-to-SCAD reconstruction — Reverse-engineer STL meshes into parametric OpenSCAD code using SVG profiling and SDF optimization
• Image-to-CAD replication — Reproduce physical objects from reference photos
• Parametric design — All dimensions as variables, overridable via CLI -D flags
• Mesh comparison — Boolean diff rendering and IoU scoring to verify reconstruction accuracy
• Printability analysis — Wall thickness, overhang, and manifold validation
• Reusable module library — Common 3D printing patterns (counterbores, heat-set bosses, ribs, snap-fits)
• Eval framework — Automated testing with 20 binary assertions across 4 scenarios (100% pass rate)

Prerequisites

OpenSCAD, reachable from the CLI. Every script resolves it as $OPENSCAD_BIN, else command -v openscad — no path is hardcoded.

sudo pacman -S openscad     # Arch / Omarchy
brew install openscad       # macOS
sudo apt install openscad   # Debian / Ubuntu

Python packages, needed only by Reconstruct and Replicate. Quick, Modify, Design and Export work without them.

# Arch: install from the repos, the interpreter is externally managed and pip will refuse
sudo pacman -S python-trimesh python-numpy python-scipy python-shapely python-rtree

# macOS / other
pip3 install trimesh numpy scipy rtree shapely

Claude Code CLI installed.

Calibrate the printer, once

Clearances are the difference between a part that fits and a reprint. Print templates/calibration-comb.scad one time, measure it, and write the numbers into templates/printer-profile.scad. Until profile_measured is set to true the skill uses declared defaults and says so whenever it emits a part whose function depends on a fit.

Installation

Option 1: Clone and symlink (recommended)

git clone https://github.com/andreahaku/openscad_claude_skill.git ~/Development/Claude/openscad_claude_skill

mkdir -p ~/.claude/skills
ln -sf ~/Development/Claude/openscad_claude_skill ~/.claude/skills/openscad

Option 2: Direct clone into skills

git clone https://github.com/andreahaku/openscad_claude_skill.git ~/.claude/skills/openscad

Verify installation

openscad --version
bash ~/.claude/skills/openscad/scripts/openscad-render.sh quick ~/.claude/skills/openscad/templates/bracket.scad

Usage

The skill triggers automatically when you mention 3D modeling, CAD, STL export, or OpenSCAD:

/openscad design a phone stand with adjustable angle

Modes

Example Workflows

Design from scratch:

> Design a parametric enclosure for a Raspberry Pi 4 with ventilation slots

Reconstruct from STL:

> Convert /path/to/model.stl into parametric OpenSCAD code

Export with parameter overrides:

> Export the bracket with width=100 and wall=3

Project Structure

openscad_claude_skill/
├── SKILL.md                              # Skill definition (6 modes, 762 lines)
├── README.md                             # This file
├── scripts/
│   ├── openscad-render.sh                # Core render/export/preview engine (7 commands)
│   ├── openscad-project.sh               # Project scaffolding (init/list/clean/info)
│   ├── openscad-validate.sh              # Strict validation with error categorization
│   ├── openscad-stl-analyze.sh           # STL mesh analysis (bbox, cross-sections, gaps)
│   ├── openscad-stl-reconstruct.sh       # Automated reconstruction pipeline (SVG profiling)
│   ├── openscad-stl-compare.sh           # Mesh comparison (boolean diff, accuracy %)
│   └── openscad-sdf-optimize.py          # SDF parameter optimizer (IoU scoring)
├── references/
│   ├── language-reference.md             # Complete OpenSCAD v2021.01 cheat sheet
│   └── reconstruction-guide.md           # Best practices for STL-to-SCAD reconstruction
├── templates/
│   ├── enclosure.scad                    # Parametric electronics box with lid
│   ├── bracket.scad                      # L-bracket with countersunk holes
│   └── printable-lib.scad               # Reusable 3D printing modules
└── eval/
    ├── eval.json                         # 4 test scenarios, 20 binary assertions
    └── results.jsonl                     # Test results log

Scripts

openscad-render.sh — Core Rendering Engine

bash scripts/openscad-render.sh quick            # Single isometric preview
bash scripts/openscad-render.sh preview           # 4-view (iso, front, right, top)
bash scripts/openscad-render.sh stl  [-D ...]     # Export STL
bash scripts/openscad-render.sh 3mf               # Export 3MF
bash scripts/openscad-render.sh export            # Full export (STL + 3MF + PNG)
bash scripts/openscad-render.sh analyze           # Printability analysis
bash scripts/openscad-render.sh custom  [opts]    # Custom render

openscad-stl-reconstruct.sh — Automated STL Analysis

bash scripts/openscad-stl-reconstruct.sh model.stl output_dir/

Runs the full analysis pipeline:

1. trimesh mesh analysis (volume, watertight, normals, bounding cylinder)
2. SVG profiling via OpenSCAD projection(cut=true) at 5 Z levels
3. Primitive detection (RANSAC axis estimation, normal-based CSG inference)

Output: mesh-info.json, primitives.json, SVG slice files

openscad-stl-compare.sh — Mesh Comparison

bash scripts/openscad-stl-compare.sh original.stl reconstruction.stl output_dir/

Produces:

• diff-A-minus-B.png — Geometry in original but MISSING from reconstruction
• diff-B-minus-A.png — EXTRA geometry in reconstruction
• overlay.png — Both models overlaid
• Geometric accuracy % — Based on volume of boolean differences

openscad-sdf-optimize.py — Parameter Optimizer

python3 scripts/openscad-sdf-optimize.py model.stl stadium-slot --verbose

Uses Signed Distance Fields + IoU scoring to find optimal parameters without invoking OpenSCAD in the loop. Converges in seconds via scipy.optimize.minimize.

openscad-stl-analyze.sh — Raw Mesh Analysis

bash scripts/openscad-stl-analyze.sh model.stl                          # Full analysis
bash scripts/openscad-stl-analyze.sh model.stl --cross-section z 5.0     # Slice at Z=5
bash scripts/openscad-stl-analyze.sh model.stl --gaps y                  # Find Y-axis gaps

STL-to-SCAD Reconstruction

The reconstruction pipeline converts triangle meshes into clean, parametric OpenSCAD code:

The Sculptor Approach

All reconstructions follow the sculptor method — start from a solid block, subtract everything:

difference() {
    solid_body();        // 1. Full solid first
    channels();          // 2. Subtract channels/slots
    taper_cuts();        // 3. Subtract wedges
    all_holes();         // 4. ALL holes LAST
}

Two-Tier Pipeline

1. SVG Profile Analysis (fast) — openscad-stl-reconstruct.sh identifies the model topology by slicing at multiple Z levels
2. SDF Optimization (precise) — openscad-sdf-optimize.py finds exact parameters via IoU scoring

Proven Results

See references/reconstruction-guide.md for the complete best practices guide.

Templates

printable-lib.scad — Reusable Modules

use 

shell_box(outer=[60,40,20], wall=2, floor=2);
rounded_box([50,30,10], r=3);
screw_clearance_hole(d=3, h=10, fit="close");
counterbore_hole(shaft_d=3, head_d=6, head_h=3, h=12);
countersink_hole(d=3, cs_d=6, cs_h=2, h=10);
heatset_boss(insert_d=4.6, insert_h=5, wall=2, h=8);
screw_post(outer_d=7, inner_d=3, h=10);
rib(len=20, height=12, thick=2);
snap_tab(width=8, length=6, thick=1.5, overhang=0.8);
text_label("Hello", size=8, depth=1);

fit_clearance("press");   // 0.15mm
fit_clearance("close");   // 0.25mm
fit_clearance("slide");   // 0.30mm
fit_clearance("loose");   // 0.40mm

3D Printing Guidelines

• Wall thickness: min 1.2mm (FDM with 0.4mm nozzle)
• Clearance: 0.2-0.3mm for fitting parts
• Overhangs: < 45° from vertical; prefer chamfers on downward faces
• Epsilon (eps = 0.01) in all boolean operations
• Flat bottoms for bed adhesion
• assert() for self-validating parametric models
• Counterbore vs countersink: always check reference images

Environment Variables

Eval Framework

The skill includes automated testing:

ls eval/
# eval.json      — 4 test scenarios, 20 binary assertions
# results.jsonl  — Test results log

Baseline: 100% pass rate (20/20) across:

• Design (simple box + sculptor approach)
• STL reconstruction (96.27% geometric accuracy)
• Parametric export with -D overrides

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Run: bash scripts/openscad-render.sh quick templates/bracket.scad
5. Submit a pull request

Support

OpenSCAD Claude Code Skill is free and open source. If it is useful to you, you can support its development with a one-off donation on Ko-fi or by sponsoring me on GitHub Sponsors. Donations are voluntary and do not unlock any feature.

License

MIT

Credits

Built with Claude Code (Anthropic), with architectural input from Gemini (Google) and Codex (OpenAI).

Powered by OpenSCAD — The Programmers Solid 3D CAD Modeller.