CommunityCoding & Developmentgithub.com

3d-builder

Spec-driven creation and editing of 3D models in Blender or FreeCAD. Keeps everything for one model together in models/<name>/. Writes a spec file there, asks clarifying questions one at a time, records every decision and assumption, for buildings discusses the floor plan and draws an SVG plan per floor for approval, then builds the model via a Blender/FreeCAD MCP server or a generated Python script and saves it in the same folder. Use whenever the user wants a 3D model, part, object, enclosure, bracket, holder, mount, case, prop, mesh, CAD design or building (house, cabin, office, game level with rooms) created or changed - even if they don't mention Blender, FreeCAD or "3D" explicitly (e.g. "design a wall mount for my router", "make the hook 5 mm thicker", "I need a printable box for an Arduino", "a low-poly crate for my Godot game", "model a two-storey house with three bedrooms", "move the kitchen wall 1 m east"). Also for assets meant for games or the web (exports .glb/.fbx for...

What is 3d-builder?

3d-builder is a Claude Code agent skill that spec-driven creation and editing of 3D models in Blender or FreeCAD. Keeps everything for one model together in models/<name>/. Writes a spec file there, asks clarifying questions one at a time, records every decision and assumption, for buildings discusses the floor plan and draws an SVG plan per floor for approval, then builds the model via a Blender/FreeCAD MCP server or a generated Python script and saves it in the same folder. Use whenever the user wants a 3D model, part, object, enclosure, bracket, holder, mount, case, prop, mesh, CAD design or building (house, cabin, office, game level with rooms) created or changed - even if they don't mention Blender, FreeCAD or "3D" explicitly (e.g. "design a wall mount for my router", "make the hook 5 mm thicker", "I need a printable box for an Arduino", "a low-poly crate for my Godot game", "model a two-storey house with three bedrooms", "move the kitchen wall 1 m east"). Also for assets meant for games or the web (exports .glb/.fbx for...

Works with~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/thanikc/3d-builder/tree/HEAD/skills/3d-builder

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does 3d-builder do?

Don't guess at a 3D model. Write down what will be built, clear up what's ambiguous with the user, record every assumption, and only then model it. A model built on guessed dimensions gets corrected over and over; a spec catches the guesses before they become geometry.

The workflow has these phases, always in this order: spec → questions → floor plans (buildings only) → model. Don't open Blender or FreeCAD, and don't write modelling code, before the spec exists and the questions are done. For a building, the user must also have approved the floor plans first.

Project layout

A project can hold several models, so everything that belongs to one model lives in its own folder:

models/
  <name>/
    specs/
      <yyyy-mm-dd-hhmmss>-<request>.md   # one spec per request
    plans/                               # buildings only
      layout.json
      floor-<id>.svg
    <name>.blend | <name>.FCStd          # the model
    <name>.py                            # script fallback only
    <name>.glb | <name>.fbx              # game/web exports only
.3d-builder.json                         # remembered tool choice, for the whole project

<name> is a short kebab-case name for the object (phone-holder, router-wall-mount). It names the folder and the model files. All paths below are relative to models/<name>/ unless they say otherwise.

Older projects may still use the previous flat layout (specs/ and plans/ at the project root, models/<name>.blend). If you find one, work with it as it is and offer once to move the files into this structure. Don't move anything without asking.

Phase 1: Write the spec

  1. Pick the model's <name>. For a new model, check that models/<name>/ doesn't exist yet, then create it and its specs/ folder.
  2. Get the timestamp from the system clock (e.g. date +%Y-%m-%d-%H%M%S) rather than inventing one.
  3. Create specs/<yyyy-mm-dd-hhmmss>-<request>.md using the template in references/spec-template.md. <request> is a short kebab-case label for this request: initial for a new model, or the change for an edit (thicker-hook, move-kitchen-wall).

Fill in what the request already states, then list the open points: everything that affects the geometry but wasn't specified. Typical open points:

  • Overall dimensions and units, and which dimensions are fixed vs. free
  • Fit and clearance against real objects (a 60 mm phone needs a slot slightly wider than 60 mm; how much?)
  • Wall thickness, fillets/chamfers, hole sizes, screw types
  • Mounting method, orientation, load
  • Purpose and manufacturing (3D printing → overhangs, minimum walls, flat base; CNC; render-only; game/web asset)
  • For game/web assets: target engine, polygon budget, scale in engine units, pivot position, UVs and textures vs. plain colours, LODs, collision mesh
  • Level of detail, materials (Blender), parametric needs (FreeCAD)
  • For buildings: floors, footprint, rooms and their sizes, stairs, doors and windows. These get settled in Phase 3 with the floor plans, so list them there and not here

Editing an existing model: find the object's folder in models/ first. Write a new spec for the change (each request gets its own file, so the history stays readable), link it to the previous spec, and state what changes and what must stay the same. Read the existing model (via MCP, or the script that built it) before editing, so the edit starts from what's actually there. For a building with a plans/ folder, a layout change goes through the plans first (Phase 3, "Editing a building").

Phase 2: Clarifying questions

If the request leaves open points, ask about them before modelling. The user knows things you can't infer (the actual phone width, where the wall screws go), and one question now saves a rebuild later.

Rules:

  • One question at a time. Wait for the answer before asking the next. Order questions by how much they affect the geometry: overall size and purpose first, cosmetic details last.
  • Yes/no where possible. "Should the cable slot be centred?" beats "Where should the cable slot be?".
  • Otherwise multiple choice: the recommended option first and marked "(recommended)", then the alternatives, and a free-text answer last. Use the agent's question tool (e.g. AskUserQuestion) if it has one; it usually adds the free-text option for you.
  • Batches of 5. After every 5 questions, ask whether to continue with up to 5 more, saying roughly how many open points are left. If the user says no, stop asking.
  • Don't ask about things that don't matter to this model, and don't ask what the user already said.
  • Record each answer in the spec's Decisions section right away, so the spec is always current.

Stop when nothing important is left unclear, or when the user stops answering. For every open point that remains, decide yourself, choosing the sensible default for the stated purpose, and write it in Assumptions with a one-line reason. The user should be able to read the spec and see every choice made on their behalf.

If the request is already fully specified, skip the questions and say so in one line.

Phase 3: Floor plans (buildings only)

If the model is a building or has rooms, settle the layout on paper before modelling. Read references/floorplans.md and follow it:

  1. Discuss the floor plan with the user, using the question rules above: floors, footprint, rooms, adjacency, stairs, doors and windows.
  2. Draw a vector plan for each floor. Write plans/layout.json and generate plans/floor-<id>.svg with the bundled scripts/draw_plans.py.
  3. Review the plans with the user and revise them until the user approves. Record the approval in Decisions.

The approved layout.json is the source of truth for the model's walls, openings, rooms and stairs. Skip this phase for anything that isn't a building.

Phase 4: Model

Save the result to <name>.blend (Blender) or <name>.FCStd (FreeCAD) in the model's folder. For a game or web asset, also export it next to the source file (see Export for engines).

Choose the tool

Check which MCP servers are configured: look at your available tools for Blender or FreeCAD MCP tools (names usually contain blender or freecad).

  1. Remembered choice: if .3d-builder.json exists in the project root, use its "tool" ("blender" or "freecad") unless the user asks for something else.
  2. Exactly one MCP server configured: use that tool.
  3. Both or neither configured: ask the user which tool to use (one multiple-choice question). Recommend FreeCAD for functional parts with precise dimensions (brackets, enclosures, anything printed or machined), and Blender for organic shapes, sculpted or decorative objects, anything meant for rendering, and game or web assets (FreeCAD's tessellated meshes are poorly suited to real-time use).
  4. Remember the choice by writing {"tool": "blender"} or {"tool": "freecad"} to .3d-builder.json. Record the tool in the spec too.

Build via MCP (preferred)

  1. Make one cheap call first (e.g. get scene/document info). If it errors or doesn't respond within 10 seconds, treat the server as unavailable and switch to the script fallback. Tell the user why in one line.
  2. Build the model step by step from the spec. Check dimensions as you go (query bounding boxes or object properties) rather than trusting that the code did what you meant.
  3. Save to the path above.

Script fallback

When no MCP server is usable, write a standalone Python script, <name>.py in the model's folder, that builds the model from scratch and saves <name>.blend or <name>.FCStd next to itself. Put the key dimensions as named constants at the top so the user can tweak them. For a building, the script reads plans/layout.json and doesn't copy the coordinates into the code (see references/floorplans.md, "Build the model from the layout").

Then try to run it headless, if the tool is installed:

  • Blender: blender --background --python models/<name>/<name>.py
  • FreeCAD: freecadcmd models/<name>/<name>.py (on some systems FreeCADCmd or freecad.cmd)

If it runs, check the output (file exists, printed bounding box matches the spec). If it fails, fix the script and rerun. If the tool isn't on the PATH, tell the user the exact command to run.

Tool-specific pitfalls and script skeletons: references/blender.md, references/freecad.md. Read the one for the chosen tool before writing code.

Export for engines

Only for game or web assets. Keep the .blend as the editable source and export alongside it:

TargetFormatFile
Web (three.js, Babylon.js), Godot, general useglTF binary<name>.glb
Unity, UnrealFBX (or .glb if the user's pipeline imports glTF)<name>.fbx

Engines are real-time, so the asset has to respect the spec's budget: check the triangle count, apply transforms, put the pivot where the spec says, and match the engine's scale and axes. Export settings and pitfalls: the "Game and web assets" section in references/blender.md.

This skill delivers the asset file. Loading it into a scene, writing engine scripts or building a three.js page is outside its scope; if the user wants that too, do it as a separate step after this workflow is finished.

Finish

  1. Verify the model against the spec: overall dimensions, every listed feature present, and any fit or clearance requirements. For game/web assets, also the triangle count against the budget and the exported file's bounding box in engine units. For buildings, also check against the approved plans: overall dimensions, wall positions, every door and window, and floor levels.
  2. Update the spec: set Status to done, fill in Output (file paths including exports and plans, tool, MCP or script), and note anything that turned out different from the plan.
  3. Report to the user briefly: what was built, where the files are, and the main assumptions they may want to revisit (point to the spec for the rest).

If the user asks for changes after that, treat them as a new edit request (Phase 1, "Editing an existing model"). Small follow-ups in the same conversation ("a bit thicker") can go in the same spec under Revisions instead.

Related Skills