Text-to-CAD (CAD Skills)

What It Does

text-to-cad is a library of 11 agent skills that give an AI coding agent a complete, source-controlled CAD, robotics, and fabrication pipeline. The skills span parametric CAD generation (STEP as the primary artifact, with STL, 3MF, and GLB as secondary exports), 2D DXF drawing, off-the-shelf STEP part sourcing, robot description files (URDF for structure, SRDF for MoveIt2 planning, SDF for simulation), G-code slicing, SendCutSend upload preflight, Bambu Lab print dispatch, an implicit-CAD experiment using GLSL signed-distance fields, and a browser-based CAD Viewer that previews every artifact. It targets mechanical engineers, robotics developers, and hardware makers who want their agent to produce real, inspectable manufacturing files rather than render-only concept art. The cad skill is the anchor: it wraps the build123d Python CAD kernel (itself built on the OpenCASCADE geometry engine via cadquery-ocp) behind a gen_step() source contract, a generation CLI, a geometry inspection CLI, and a snapshot CLI for visual review. The repo also ships a Next.js docs site (cadskills.xyz) and a three.js viewer app.

The Good

The core claim holds: it generates a real, valid STEP file from Python source. After installing build123d 0.11.1 and cadquery-ocp 7.9.3.1.1 and the editable cadpy package, a hand-written build123d generator defining gen_step() (a 100 x 60 x 20 mm block with four 8 mm vertical through-holes) was run through the cad skill's python scripts/step gen_block.py -o out/calibration_block.step command. It produced a 30,985-byte, 817-line ISO-10303-21 STEP file (FILE_SCHEMA AUTOMOTIVE_DESIGN, written by the Open CASCADE STEP processor 7.9) plus a 194 KB hidden GLB topology artifact for the viewer, in 2.15 seconds total. The build123d shape reported is_valid: True, a volume of 115,978.761 mm cubed (which exactly matches the expected 120,000 minus four cylinders of pi times 16 times 20), and a bounding box of negative-50 to 50, negative-30 to 30, negative-10 to 10. This is a genuine CAD interchange file, not a toy.

The geometry inspection tool returns correct, structured, content-addressed facts. Running python scripts/inspect refs out/calibration_block.step --facts returned JSON with "ok": true, a stepHash of 24644942d320dbae... (a SHA-256 over the STEP content, so regeneration is reproducibly checkable), kind: "part", faceCount: 10 (six block faces plus four inner cylindrical hole faces, the correct count for four through-holes), edgeCount: 24, bounds matching the spec, and entryFacts.size: [100.0, 60.0, 20.0]. An agent can read this JSON and verify its own work programmatically, which is exactly the validation loop the skill mandates.

A second skill generates a valid DXF end to end. The dxf skill wraps the ezdxf library behind a gen_dxf() contract. A hand-written generator (a 120 x 80 mm gasket plate with a central 20 mm bore and four 6 mm mounting holes) ran through python skills/dxf/scripts/dxf gen_gasket.py -o out/gasket.dxf in 182 ms and produced a 36 KB DXF (version AC1024, which is R2010) that re-reads cleanly with six entities (one LWPOLYLINE outline plus five CIRCLE entities). The two skills share the same source-contract-then-CLI pattern, so the architecture is consistent across the library.

801 of the repo's own tests pass on a fresh clone. The Python suite ran 397 passed with 7 skipped across the global structural tests (skill self-containment, plugin manifests, release version paths, models directory policy), the cadpy package tests, and every per-skill CLI test (cad, urdf, srdf, sdf, dxf, gcode, bambu-labs). The JavaScript suite (cadjs, the shared render and viewer runtime) ran 404 passed with 0 failed in 753 ms using node --test. The bundle integrity gate (scripts/bundle/bundle.sh --check) confirmed the generated cad snapshot runtime and the cadpy runtime are both up to date against their sources. This is the strongest quality signal available short of running the repo's own CI, and it holds.

The cad skill's design is a model for how to write a high-stakes executable skill. The 102-line SKILL.md uses genuine progressive disclosure: nine reference files (cad-brief, build123d-modeling, step-generation, inspection-and-validation, snapshot-review, positioning, parameters, supported-exports, repair-loop) are loaded only when their trigger applies. It enforces a STEP-first philosophy where STEP is the primary validated artifact and STL, 3MF, and GLB are explicitly secondary. It mandates a 10-step workflow that includes writing a natural-language CAD brief before coding, editing source rather than generated artifacts, running geometric validation, and a mandatory snapshot review step (with documented skip cases). It defines a handoff contract (always pass file paths to the cad-viewer skill) and a set of non-negotiables (closed solids, verbose native labels, never use git diff on large exported artifacts). The #o1.2.f1 selector-reference syntax for addressing specific geometry is a real addressing scheme that the inspect tool resolves.

The vertical coverage is unusually complete. The 11 skills form a connected pipeline from design to physical part: cad generates the model, step-parts sources off-the-shelf components, dxf produces 2D cut layouts, sendcutsend preflights the upload, gcode slices meshes into printer-ready FDM toolpaths, and bambu-labs dispatches the print to a Bambu Lab machine over LAN. In parallel, the robotics track covers urdf (structure), srdf (MoveIt2 planning groups and collision), and sdf (simulator worlds with physics and sensors). This is the only skill library GearScope has seen that takes an agent from a text prompt to a dispatched print job.

The Bad

There is no CHANGELOG despite 13 versioned tags. The repo has tags from 0.3.1 through 0.3.13, but no CHANGELOG.md and the GitHub releases carry no release notes. For a skill library whose cad kernel (build123d) and own API both evolve, the absence of any per-release change record means a consumer cannot tell what changed between 0.3.10 and 0.3.13 without reading the git log. A pinned install has no diffable upgrade path.

The cadpy and cadjs packages are private and source-only. Neither is published to PyPI or npm (cadjs has "private": true in its package.json; cadpy is installed editable from scripts/packages/cadpy). The only install path is clone-then-editable-install. There are no daily download numbers to cite because there is no registry package, and a consumer cannot pip install cadpy or pin a registry version. The version surface is the git tag and the VERSION file, which is adequate but not what most Python or npm consumers expect.

Python 3.12 is a hard floor and the dependency footprint is large. cadpy's pyproject.toml declares requires-python >=3.12, and the runtime pulls in cadquery-ocp (the OpenCASCADE bindings), VTK 9.6, numpy, scipy, scikit-learn, matplotlib, ezdxf, and roughly 30 more packages, totaling about 430 MB installed. This is inherent to doing real CAD geometry (OpenCASCADE is the industry kernel and it is not small), but it means the install is heavier than any doc-only skill and will not work on a minimal agent sandbox without the full Python toolchain.

The cadjs test runner pins a Node flag that Node 24 dropped. The packages/cadjs/scripts/run-tests.mjs runner invokes node --test --experimental-default-type=module. The --experimental-default-type=module flag was removed in Node 23 and 24 (ESM is now the default there), so on a Node 24 host the runner exits immediately with bad option: --experimental-default-type=module and runs zero tests. The CI pins Node 22, where the flag is valid, so this is a version-pinning gap rather than a broken test suite. The workaround is to run node --test directly on the test files (which works on Node 24 and ran all 404 tests clean), but the documented npm test path fails on current Node.

The pytest layout needs a non-default invocation flag. The per-skill test directories lack __init__.py files, so several test_cli.py files with identical basenames (under cad/inspect, cad/step, urdf, srdf, sdf, dxf) collide under pytest's default prepend import mode, producing an import file mismatch collection error. Running with --import-mode=importlib resolves it and all tests pass. The repo's own CI avoids this through its invocation, but a contributor running pytest naively on a subset hits the collision.

No Hermes-specific or OpenClaw-specific install documentation. The README documents three paths: the skills CLI, the Claude Code plugin marketplace, and the Codex plugin marketplace. The skills CLI does cover Hermes generically (it lands skills in .hermes/skills/), but neither the README nor the plugin manifests call out Hermes or OpenClaw by name. A Hermes user would use the generic skills CLI path, which works, but the on-ramp is not documented for that host.

Several skills need external tooling or hardware that could not be exercised. The gcode skill requires a real slicer CLI (prusa-slicer, orca-slicer, or bambu-studio) to slice meshes. The bambu-labs skill requires a physical Bambu Lab printer reachable on LAN. The step-parts skill depends on the external step.parts service. The snapshot skill needs a Playwright Chromium browser to render PNG and GIF review packets. These are honest scope limits of a hardware-vertical skill set, not defects, but they mean the deepest end of the pipeline (a dispatched print) was not functionally verified here.

Smoke Test Results

Testing ran on the host (macOS 26.5.2, aarch64, Python 3.12.13, Node v24.13.1, npm 11.8.0). The repo was cloned with git clone --depth 1 (1,235 tracked files, 96 MB with LFS pointers). Structural validation ran over all 11 skills and all three plugin manifests. Functional verification installed the real build123d 0.11.1 and cadquery-ocp 7.9.3.1.1 plus the editable cadpy package, generated a STEP file and a DXF file through the skill CLIs, inspected the STEP geometry, and ran both test suites.

Run A. Fresh clone, structural validation

$ git clone --depth 1 https://github.com/earthtojake/text-to-cad.git
PASS - cloned, 1235 files (excl .git), 96 MB with LFS pointers

$ find skills -name SKILL.md | wc -l
PASS - 11 skills (cad, cad-viewer, dxf, urdf, srdf, sdf, gcode, bambu-labs, sendcutsend, step-parts, implicit-cad)

$ python3 check_manifests.py
PASS - 3 of 3 plugin manifests valid JSON:
 .claude-plugin/marketplace.json (text-to-cad, v0.3.13, 1 plugin)
 .claude-plugin/plugin.json (cad, v0.3.13, MIT, skills=./skills/)
 .codex-plugin/plugin.json (cad, v0.3.13, MIT, skills=./skills/)

$ bash scripts/bundle/bundle.sh --check
PASS - CAD snapshot runtime up to date; CAD cadpy runtime up to date
 (viewer esbuild binary missing on bare clone; needs viewer/ npm install)

$ cat VERSION && git tag | tail -1
PASS - VERSION=0.3.13, latest tag=0.3.13 (13 tags 0.3.1->0.3.13)

$ find skills -path '*/references/*.md' | wc -l
PASS - 46 progressive-disclosure reference docs across 11 skills

$ find skills -name '*.yaml' -path '*/agents/*' | wc -l
PASS - 11 OpenAI agent yaml configs (one per skill)

Pass rate: 8 of 8. The skill files are structurally clean. Frontmatter is present on all 11 skills, all three plugin manifests parse with correct version and license, the bundle integrity gate passes for the two runtime bundles, and the 46 reference docs confirm genuine progressive disclosure.

Full fresh log ->

Run B. Install path and dependency resolution (with deps)

$ python3 -m venv ttc-venv && pip install build123d cadquery-ocp
PASS - build123d 0.11.1 + cadquery-ocp 7.9.3.1.1 installed, 0 conflicts

$ pip install --editable skills/cad/scripts/packages/cadpy
PASS - cadpy 0.3.13 installed editable; resolved deps honor declared pins

$ python3 check_imports.py
PASS - cadpy.generation, cadpy.step_artifact, cadpy.assembly import OK (build123d 0.11.1)

$ npx --yes skills@latest install earthtojake/text-to-cad --agent claude
PASS - cloned repo, found 11 skills, interactive selector with per-skill descriptions

$ bash scripts/bundle/bundle.sh --check
PASS - 2 of 3 runtime bundles consistent (viewer needs its own npm install)

Pass rate: 5 of 5. This is the canonical install-correctness verdict. The OpenCASCADE-backed dependency chain resolves cleanly with no version overrides, the editable cadpy package imports, the skills CLI detects all 11 skills, and the production bundle integrity holds.

Full with-deps log ->

Run C. Functional verification (STEP and DXF generation, geometry inspection, test suites)

$ python skills/cad/scripts/step gen_block.py -o out/calibration_block.step --verbose
PASS - wrote 30,985-byte ISO-10303-21 STEP (Open CASCADE 7.9) + 194 KB GLB in 2.15s
 build123d: is_valid=True, volume=115978.761 mm^3 (exact: 120000 - 4*pi*16*20)
 bbox: -50..50, -30..30, -10..10

$ python skills/cad/scripts/inspect refs out/calibration_block.step --facts
PASS - ok=true, stepHash=24644942..., faceCount=10, edgeCount=24,
 size=[100.0,60.0,20.0], bounds centered, kind=part

$ python skills/dxf/scripts/dxf gen_gasket.py -o out/gasket.dxf --verbose
PASS - wrote 36 KB DXF AC1024 (R2010) in 182ms
 ezdxf re-read: 6 entities (1 LWPOLYLINE + 5 CIRCLE)

$ python3 -m pytest tests/python/ -q --import-mode=importlib
PASS - 397 passed, 7 skipped (global + cadpy + cad/sdf/urdf/srdf/dxf/gcode/bambu-labs CLI)

$ cd packages/cadjs && node --test $(find src -name '*.test.js')
PASS - 404 tests, 404 pass, 0 fail, 753ms

Functional pass rate: 5 of 5. The cad skill's headline capability (generate a validated STEP from build123d source) works end to end with correct geometry, the inspection tool returns correct structured facts, the dxf skill generates a valid drawing, and both the Python and JavaScript test suites pass in full.

Full functional log ->

What the runs tell you

The runs say this is a production-grade engineering tool wrapped as an agent skill, not a prompt template. The structural layer is clean (8 of 8), the dependency layer resolves without conflict (5 of 5), and the functional layer is where it distinguishes itself: a real STEP file with verified geometry, a real DXF, and 801 passing tests across two languages. The only capabilities the smoke test could not reach are the ones that require external hardware or binaries (a Playwright browser for snapshots, a real slicer CLI for G-code, and a physical Bambu printer for the final dispatch), which are inherent limits of a fabrication-vertical skill set rather than gaps in the skill itself.

Setup Walkthrough

1. Install the full library with the skills CLI: npx skills install earthtojake/text-to-cad. The CLI auto-detects your installed agent and presents an interactive selector for all 11 skills. Use --agent hermes (or claude, codex, cursor) to target a specific host.
2. For Claude Code, use the plugin marketplace instead: claude plugin marketplace add earthtojake/text-to-cad, then claude plugin install cad@text-to-cad.
3. For Codex, the same pattern applies (codex plugin marketplace add then codex plugin add), but you need Codex 0.142.0 or newer. Older versions silently skip the plugin and never surface it in codex plugin list.
4. Install the cad runtime dependencies from inside the cad skill directory: pip install -r skills/cad/requirements.txt. This installs the editable cadpy package plus playwright. The cadpy package in turn pulls build123d and cadquery-ocp (the OpenCASCADE bindings), which is roughly a 430 MB install.
5. For snapshot rendering (the mandatory visual-review step in the cad workflow), install the Playwright browser: python -m playwright install chromium. Without it, the cad skill still generates STEP and runs geometric validation, but cannot produce the PNG or GIF review packets its workflow calls for.
6. For the G-code and Bambu skills, install a slicer CLI (prusa-slicer, orca-slicer, or bambu-studio) and ensure a Bambu Lab printer is reachable on LAN for bambu-labs.

Post-install gotcha: Python 3.12 or newer is required (cadpy declares requires-python >=3.12). The OpenCASCADE kernel adds several seconds to the first import (about 8 seconds cold on this host), which is normal. If you run the repo's pytest suite directly, pass --import-mode=importlib because the per-skill test directories lack __init__.py and identical test_cli.py basenames collide under the default mode.

Alternatives

1. build123d and CadQuery directly (no skill) - the underlying Python CAD kernels this skill wraps. Prefer them when you want to write CAD code yourself without an agent orchestration layer; prefer text-to-cad when you want the agent to own the generate, validate, snapshot, and handoff loop with consistent tooling.
2. jacob-bd/notebooklm-mcp-cli (already reviewed) - a research-and-knowledge MCP rather than a CAD tool, but it is the closest reviewed peer for the "domain-vertical agent tooling" pattern. It shows the MCP-server archetype; text-to-cad shows the executable-skill-pack archetype for an equally deep but different domain.
3. Hand-written AGENTS.md or .cursorrules CAD notes - some robotics teams maintain their own build123d or FreeCAD guidance. text-to-cad is more complete (11 connected skills, a real inspection tool, mandatory validation, 801 tests) and is a strict upgrade over a one-off rules file unless your project uses a private CAD kernel the skill does not wrap.