OpenParable
Skip to content
← Back to skills

Use Openscad

Design
use-openscad

Use Openscad is an Agent Skill for design published in the FradSer/dotclaude repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Writes OpenSCAD code and drives the `openscad` command-line compiler to produce STL/3MF/AMF/DXF/SVG/PNG outputs from parametric `.scad` models. This skill should be used when the user asks to design a 3D-printable part, generate a laser-cut 2D plate, render a preview image of a CAD model, export STL for 3D printing, batch-render parametric variants, or convert between mesh formats. Invoked via "/hardware:use-openscad".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/FradSer/dotclaude/blob/HEAD/hardware/skills/use-openscad/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/use-openscad, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Use OpenSCAD

Design parametric 3D and 2D parts in OpenSCAD and compile them to fabrication outputs with the openscad CLI. OpenSCAD is a functional code-based CAD language — modules and functions, CSG booleans, extrusion — ideal for an agent to write and iterate.

Process

  1. Understand what the user wants (a printable part, a laser-cut plate, a preview image, a mesh conversion) and pick the target format (STL/3MF/AMF for 3D printing, DXF/SVG for 2D cutting, PNG for preview).
  2. Locate and verify the binary (see "Locating the binary"). Run openscad --version first to confirm it works.
  3. Author the .scad model using references/language.md for syntax. Make dimensions -D variables when the user wants parametric control from the command line.
  4. Compile with the right flags from references/cli.md. Use references/workflows.md for end-to-end recipes and references/design.md for printability rules.
  5. After STL/3MF export, scan stderr for manifold warnings (see CRITICAL rules) before declaring success.

CRITICAL operating rules

  • Mesh exports (STL/3MF/AMF/DXF/SVG) always get full CGAL geometry — --render is NOT needed for them. --render only affects PNG image export (without it, PNG uses OpenCSG preview). A plain openscad -o out.stl model.scad produces a complete mesh. For STL, explicitly pass --export-format binstl (ASCII is the current default; binary is the planned future default). After export, scan stderr for manifold warnings — see below.
  • macOS binary is not on PATH. It lives at /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD. On Linux try openscad or openscad-nightly; on Windows invoke openscad.com (the wrapper, not openscad.exe). MUST confirm with openscad --version before building a pipeline.
  • Exit codes are not officially documented. Empirically non-zero on compile/parse error, zero on success even with warnings; --hardwarnings makes the first warning fatal. Do NOT assume — for CI gating, run with --hardwarnings and treat any non-zero exit as failure. When unsure of a flag, run openscad --help and read the actual list.
  • Variables are immutable within a scope. Reassigning in the same scope replaces-at-origin (the first assignment is never executed, a warning is emitted); braces create inner scopes that do not leak outward. Use is_undef(x), not x == undef. -D var=val constants from the CLI override top-level program values.
  • use libraries, do not include them. include <lib.scad> is literal copy-paste that runs top-level geometry and confuses error line numbers; use <lib.scad> suppresses top-level geometry and exposes only functions/modules. Use use for any library file.
  • String -D values need shell quoting. -D 'mode="parts"' (bash) — the inner quotes are part of the OpenSCAD expression. Numeric -D w=60 needs no quotes.
  • Scan stderr after mesh export. Capture 2>&1 and grep for manifold, self-intersect, degenerate, warning — OpenSCAD prints mesh problems to stderr even when the exit code is zero. See references/workflows.md.

Command map

User wantsFlagsReference
STL for 3D printing--export-format binstl -o out.stlreferences/cli.md
3MF / AMF-o out.3mfreferences/cli.md
2D DXF / SVG (laser cut)-o out.dxfreferences/cli.md
Preview PNG--preview --imgsize W,H --viewall --autocenter (--render for accurate non-preview)references/cli.md
Parametric variants-D var=val (repeatable)references/cli.md
Batch rendershell loop over -D valuesreferences/workflows.md
Mesh conversion (STL→3MF)import() in a re-export .scadreferences/workflows.md
Language syntaxmodules, functions, CSG, extrusionreferences/language.md
Printability ruleswalls, overhangs, clearancereferences/design.md

Locating the binary

OPENSCAD="/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD"
if [[ ! -x "$OPENSCAD" ]]; then
  command -v openscad >/dev/null && OPENSCAD="openscad" || OPENSCAD="openscad-nightly"
fi
"$OPENSCAD" --version

If none works, tell the user OpenSCAD is not installed or ask for the install path.

References

  • references/language.md — OpenSCAD syntax: modules/functions, variables and scope, control flow, CSG booleans, primitives, transforms, extrusion and projection, import/include/use.
  • references/cli.md — full openscad CLI: output and format flags, -D variables, rendering modes, image/camera options, diagnostics, --enable features, headless notes.
  • references/design.md — printability heuristics (min wall, overhangs, bridges, clearance, manifold) and 2D-for-laser rules.
  • references/workflows.md — end-to-end recipes (parametric STL, 2D DXF, preview PNG, batch variants, mesh conversion, stderr validation).