| name | mechanical-ai-skill |
| description | Mechanical engineering CAD-review skill for AI agents (Codex, Claude Code, Cursor) — Community Edition, freemium. Drives the SolidWorks API and reads STEP to: generate a BOM, identify standard parts, explain an assembly, check interference / clearances, run basic DFM, compute single-load-case static analysis (stress, deflection, safety factor) and first-3-mode modal (frequencies, resonance), produce a simple risk score, and render a PDF/HTML report — all free and real, no commercial solver needed. Trigger on a SolidWorks/STEP file or requests like "explain this assembly", "generate a BOM", "check for interference", "is this machinable", "what is the safety factor", "will it resonate", "give me a risk score", "make a report". Advanced work — fatigue, thermal, CFD, multibody dynamics, topology optimization, automatic load identification, advanced DFM/DFA, design review, procurement — is Professional Edition: those commands return enterprise_required and degrade gracefully until the licensed core is installed. |
Mechanical AI Skill — Community Edition
A mechanical-engineering CAD-review skill for AI coding agents. It sits between the agent and SolidWorks/STEP and answers the everyday questions an engineer asks of a model: What's in this assembly? Make me a BOM. How does it work? Does anything interfere? Give me a report.
The agent turns a natural-language request into a JSON task; this skill runs it against the real tools and returns a structured result the agent reports back.
READ THIS FIRST — how to report results (do not skip)
Every result JSON has a headline field. Read it and report what it says. Do not re-interpret the status yourself, and never invent data the skill did not return.
status: "ok" → The command SUCCEEDED. Report the real numbers. A summarized result (with tier/counts) is still a full success; the full data is in artifacts.full_results if a sidecar was written. graph_type: "hierarchy_fallback" is still a successful result — report it as a hierarchy/belongs-to graph, not as a failure.status: "deck_only" → PARTIAL, NOT a failure and NOT a missing feature. It means no geometry engine (SolidWorks/cadquery) is installed on this machine, so the skill produced a runnable macro instead. The capability exists and works where a geometry engine is present. Do not report this as "the tool needs SolidWorks / is broken / is unsupported." Report it as: ran successfully, geometry engine absent, macro generated.status: "needs_input" → the command ran fine but needs the inputs listed in needs_input. Provide them (usually just point at the STEP/zip/folder). Not a failure.status: "enterprise_required" → a Professional capability. Community correctly declined rather than fabricating an answer. Report it as such.status: "failed" → only THIS is an actual failure. See caveats.
Never fabricate. Do not guess part names, vendors (e.g. "FANUC M-16iB"), counts, or materials from a filename, a preview image, or a website note. If the skill didn't return it, say it wasn't computed. Inventing engineering data is the single worst thing this skill can do.
Path input is forgiving: hand the model path a .STEP file, a non-standard extension (e.g. .snapshot.1), a .zip, OR the unzipped folder — the skill resolves all of them. You do not need to dig out the exact .STEP yourself.
Non-STEP formats are recognized, not silently failed: if the file is a SolidWorks (.sldasm/.sldprt), IGES (.igs), Parasolid (.x_t), ACIS (.sat), Inventor/CATIA/Creo native, or mesh (.stl/.obj) file, the skill identifies the format and returns a needs_input with the format name and how to export STEP — report that to the user (what the file is + the export step), don't just say "failed." The skill analyzes STEP; other formats must be exported to STEP first (this keeps it pure-Python and cross-platform — no SolidWorks/CAD install needed).
review_summary writes its report for you — don't guess where. It generates review_summary.md (human-readable) and review_summary.json (machine-readable) in a mech_review/ folder next to the STEP file, and returns both exact paths in artifacts.summary_md / artifacts.summary_json. Report those exact paths to the user — never invent a temp path or claim a location you didn't get from artifacts.
Editions
This is the open Community Edition, freemium. On its own — no license — it does CAD understanding, assembly diagnostics, basic reporting, and real entry-level analysis: single-load-case static (stress / deflection / safety factor), first-3-mode modal (frequencies / resonance), basic DFM, and a simple risk score. Upload a STEP and get real results, not a demo.
Advanced engineering is Professional Edition (closed source): full/auto FE (multi-load, contact, nonlinear, automatic load-face / constraint / mesh), modal beyond 3 modes, fatigue / thermal / CFD / multibody dynamics, optimization & lightweighting, advanced DFM/DFA rule library, advanced risk scoring, automated design review, procurement, and advanced report templates. The Community commands cover these too: within the free tier they compute locally; beyond it they return enterprise_required (with an upgrade note) until the licensed mechanical_ai_core package is installed — they never crash and never fabricate results.
| Capability | Community (free) | Professional |
|---|
| BOM, part count, standard-part ID, assembly structure summary | ✅ | ✅ |
| Interference / mate / clearance diagnostics | ✅ | ✅ |
| STEP export, basic PDF/HTML report | ✅ | ✅ |
| Static analysis | single load case | multi-load, contact, nonlinear, auto-faces |
| Modal analysis | first 3 modes | unlimited modes, prestressed |
| DFM | basic rules | advanced rule library |
| DFA | basic (complexity + tool clearance) | sequence / path / time / automation |
| Fastener checks | engagement + washer/nut stack | preload / torque / joint stiffness |
| Connectivity | geometric adjacency (who touches whom) | force-flow / constraint graph |
| Mechanism detection | type ID (experimental) | design intent / purpose / power flow |
| Assembly tree | structure display | assembly order / sequence |
| Risk score | simple, multi-factor + contributors | criticality-weighted, FEA/reliability |
| Fatigue · thermal · CFD · multibody dynamics | enterprise_required | ✅ |
| Optimization / lightweighting | enterprise_required | ✅ |
| Auto load / constraint / mesh ID | enterprise_required | ✅ |
| Automated design review · procurement · advanced report | enterprise_required | ✅ |
The JSON contract
Every capability is one command: --task task.json → --out result.json. Result status is ok | needs_input | deck_only | failed | enterprise_required, plus results, assumptions, caveats. The canonical schema is sdk/CONTRACT.md; a Community summary is references/contract.md.
Commands
python scripts/sw_understand.py --task task.json --out result.json
python scripts/sw_mechanism.py --task task.json --out result.json
python scripts/sw_diagnostics.py --task task.json --out result.json
python scripts/sw_export.py --task task.json --out result.json
python scripts/report_pdf.py --results r1.json --out report.pdf
python scripts/sw_dfm.py --task task.json --out result.json
python scripts/run_analysis.py --task task.json --out result.json
python scripts/optimize.py --task task.json --out result.json
python scripts/design_review.py --task task.json --out result.json
All commands degrade gracefully: if SolidWorks isn't installed the open commands return deck_only with a macro; if the Professional core isn't installed the gated commands return enterprise_required. Nothing is ever faked.
What the Community Edition does
CAD understanding (stage 0.x) — sw_understand.py
generate_bom (item / part / qty / standard-part flag), part_count, identify_standard_parts, and explain_assembly — a structure summary that returns the component + mate tree and a plain inventory of what's in the assembly. It describes what is there; interpreting why (working principle, power flow, design intent) is the Professional Edition. See references/cad_understanding.md.
Assembly diagnostics (stage 1.0) — sw_diagnostics.py
interference_check (overlap volume per clashing pair, distinguishing likely press-fits from errors), assembly_error_check (rebuild / dangling refs), mate_conflict_check (over/under-defined), clearance_check (min-gap violations). See references/assembly_diagnostics.md.
Geometry — sw_export.py
export_step for downstream use.
Reporting — report_pdf.py
Render any result JSON(s) into a basic PDF (or HTML if reportlab is absent): status, results, BOM/finding tables, assumptions, caveats. --advanced uses Professional templates (gated).
How it stays honest
needs_input when data is missing (nothing runs); deck_only when SolidWorks is absent (macro generated); failed when a run errors; enterprise_required when a Professional capability isn't licensed.- Every default and auto-choice goes in
assumptions; every limit in caveats.
- Standard-part identification is a name heuristic — flagged for confirmation.
Knowledge base (open)
references/knowledge/ ships open engineering references for interpreting open-edition results and answering questions: formulas.md (criteria/formulas), standards.md (which code governs), faq.md (troubleshooting), literature.md (optional online lookup via the host's web tools). The DFM/DFA rule library and the simulation/optimization know-how are Professional.
Install
See INSTALL.md. Short version — Claude Code plugin: /plugin marketplace add almightyshui/Mechanical-AI-Skill then /plugin install mechanical-ai-skill; or bash install.sh all for Codex/Cursor.
File map
sdk/CONTRACT.md — canonical task/result contract + edition/extension interfaceconnectors/ — open SolidWorks / STEP / BOM adaptersscripts/ — commands (open: sw_understand, sw_diagnostics, sw_export, report_pdf; gated stubs: sw_dfm, run_analysis, optimize, design_review; core_bridge.py does the detect-and-delegate)references/ — open docs (contract, cad_understanding, assembly_diagnostics, solidworks connector, units, materials) + knowledge/examples/ — task templates; demo.sh shows the open flow + graceful gating
