Build123d Reference Index

Use this skill before authoring or debugging custom Build123d component or assembly code.

Before modeling any screw boss, standoff, snap fit, wall interface, or overhang-sensitive feature, read references/dfm-rules.md first — do not hand-model a screw hole. If the feature is a screw into a 3D-printed part, also load the build123d-libs skill: its kit owns that joint's geometry as a hard constraint.

Workbench Cell Convention

body = Box(40, 30, 12)
publish("body", body, "Main body")

Keep publish ids and labels short for the Components sidebar (top_cap, Top cap). Put dimensions and rationale in code comments, not in the label.

The CAD Workbench injects Build123d names into each persistent target. Keep each cell small, publish stable object IDs, and do not write export files from modeling code.

Core Workflow

1. Read references/pitfalls.md when debugging a failed or unfamiliar Build123d pattern.
2. Read only the specific API reference needed for the current modeling task.
3. For enclosures or mounting features, read references/dfm-rules.md before modeling screw bosses, standoffs, snap fits, wall interfaces, or overhang-sensitive features.
4. Use cad.edit action="add_part" or cad.edit action="edit_part" for one small cell and inspect its returned image before the next edit.
5. For selector refs, measurements, alignment, or diffs, use build-bound Workbench inspection.

Assembly Convention And Self-Checks

• Assembly joint convention: normal is the joint frame Z axis pointing outward from each part; up is the frame X axis. When mating two outward-facing RigidJoints, flip the moving-side frame 180° about its up axis before connect_to. See references/joints.md.
• Embed your own checks in scripts: assert and print of key dimensions (bounding boxes, joint distances, wall thicknesses) are the assertion language. Script stdout is returned in full, so a failed assert or a printed measurement is honest, actionable feedback.
• Use cad.inspect for build-bound selection facts; distance, axis-distance, angle, radius, and diameter measurements; object geometry facts; and topology-aware build comparison. These facts support debugging; they do not replace direct visual judgment.
• Use cad.look to bring the exact committed preview back into context or render up to four read-only views of that exact build (for example views: ["iso", "front", "right", "top"]). Add isolate to inspect chosen parts alone, context: "ghost" to keep the rest of the assembly as outlines, or hide to see past an enclosing part.
• At a meaningful visual checkpoint, use cad.look as needed and act on visible findings with another short edit; never claim an unseen property is resolved.
• Use cad.export only after choosing an exact build. Draft exports are content-addressed intermediate files; handoff exports automatically run one Host-owned exact-build CAD Review and proceed only on Pass.

Plane Id Convention

Keep stable object ids in publish(...), then compare builds to see which outputs changed:

cad.inspect({ kind: "object", design_id: "enclosure", buildNumber: 2, object_id: "enclosure_bottom" })
cad.inspect({ kind: "selection", design_id: "enclosure", buildNumber: 2, selection: { object_id: "enclosure_bottom", topology_ref: "f6" } })
cad.inspect({ kind: "measure", design_id: "enclosure", buildNumber: 2, mode: "distance", from: { object_id: "enclosure_bottom", topology_ref: "f5" }, to: { object_id: "enclosure_bottom", topology_ref: "f6" } })
cad.inspect({ kind: "source", design_id: "enclosure", buildNumber: 2, target: "enclosure_bottom" })
cad.inspect({ kind: "compare", design_id: "enclosure", buildNumber: 2, before_build_number: 1, after_build_number: 2 })

Reference Index