| name | openscad-librarian |
| description | Discover, recommend, and install OpenSCAD libraries for your projects. Use when: needing geometry functions, seeking existing modules before creating, managing library dependencies, or exploring what libraries are available in your workspace. |
| argument-hint | What geometry or feature do you want to create? (optional: specify desired library category) |
| user-invocable | true |
| disable-model-invocation | false |
OpenSCAD Library Librarian
Your expert guide for discovering, recommending, and installing OpenSCAD libraries. Instead of coding geometry from scratch, leverage the vast ecosystem of pre-built, tested, optimized library modules.
Mission
Help you make informed decisions about which OpenSCAD libraries to use, understand what they offer, and install them into your workspace when needed—all with clear recommendations and user transparency.
When to Use This Skill
- "I need a rounded cube/gear/bearing mount/bracket" → Find and suggest the right library
- "What libraries do I have available?" → Discover workspace library inventory
- "Can I use an existing module for this geometry?" → Library search before custom creation
- "How do I add a new library to my workspace?" → Installation and configuration
- "Which library is best for X?" → Compare alternatives and make recommendations
- "How do I use this library?" → Documentation and usage examples
Procedure: Library Discovery & Recommendation
Step 1: Inventory Available Libraries
Use the MCP tool get_openscad_libraries to retrieve comprehensive documentation of all libraries currently accessible in your workspace.
What this gives you:
- Complete list of available libraries
- Module/function signatures for each library
- Parameter descriptions and defaults
- Library categories and specializations
- Usage examples where documented
Step 2: Analyze the Need
When a user requests geometry, ask these clarifying questions:
- What is the primary purpose? (mechanical, artistic, functional, prototype)
- What key features are needed? (rounded corners, parametric sizing, specific constraints)
- Are there performance considerations? (complexity, render time, file size)
- Any aesthetic preferences? (minimalist, detailed, organic)
Step 3: Search & Recommend
Search the library inventory (from Step 1) for modules that match the requirements.
Recommendation criteria:
- Fit — Does the library have what's needed?
- Quality — Is it well-maintained and documented?
- Alternatives — Are there competing options? When yes, compare them.
- Learning curve — Is it easy to use or requires study?
Present recommendations with:
- Library name and primary purpose
- Specific modules that fit the need
- Code example showing usage
- Any limitations or setup requirements
- Installation status (already available vs. needs install)
Step 4: Installation (If Needed)
If a recommended library isn't available, follow the installation workflow:
- Confirm with user — "Library X isn't currently available. Would you like me to install it?"
- Document the source — Identify library repository/location
- Use MCP for installation — If MCP supports automated installation:
- Prepare installation command
- Execute with user's explicit consent (unless autopilot enabled)
- Verify successful installation
- Fallback workflow — If MCP doesn't support direct installation:
- Provide manual installation instructions
- Explain folder locations for their OS
- Guide configuration in VS Code settings
- Verify accessibility — After installation, confirm the library is accessible in the workspace
Step 5: Provide Usage Guidance
Once library is available:
- Show complete code example of the recommended module
- Explain key parameters and what they control
- Highlight any common pitfalls or gotchas
- Suggest parametric variations they might try
- Link to library documentation if available
Common Library Categories
Mechanical Engineering (MCAD)
- Gears — Involute gears, spur gears, various tooth profiles
- Bearings — Ball bearings, roller bearings, bearing blocks
- Fasteners — Bolts, screws, nuts with accurate profiles
- Boxes — Parametric boxes with rounded corners, finger joints
- Motors — Common motor models (stepper, DC, servo)
- Linear motion — Rails, sliders, leadscrew profiles
Advanced Geometry (BOSL2)
- Rounding & filleting — Smooth edges, bevels, rounded transforms
- Sweep/loft — Complex shapes by sweeping profiles
- Convex hulls — Organic shapes, collision geometry
- Offset/shell — Hollowing, thickness operations
- Attachments — Parametric positioning and alignment
Specialized Libraries
- MCAD/unibody — Integrated component designs
- NopSCADlib — Large library of real-world parts and assemblies
- Obrary — Community-contributed modules
- SCAD Plus — Extended functionality and utilities
Workflow Decision Tree
User requests geometry
├─ "Do I have a library that already does this?"
│ ├─ YES → Recommend library module
│ │ ├─ Already installed? → Show code example, proceed
│ │ └─ Not installed? → Ask permission, install, show example
│ └─ NO → Sketch what's needed, suggest creation approach
│
├─ "What libraries are available to me?"
│ └─ Run get_openscad_libraries, present organized list
│
└─ "How do I install a library?"
└─ Provide OS-specific instructions and configuration
Installation Paths (OS-Specific)
Windows
- Default library folder:
%USERPROFILE%\Documents\OpenSCAD\libraries
- Alternative: Configure via VS Code setting
urdf-editor.OpenSCADLibraryPaths
macOS
- Default library folder:
$HOME/Documents/OpenSCAD/libraries
Linux
- Default library folder:
$HOME/.local/share/OpenSCAD/libraries
MCP Server Integration
The URDF Editor extension includes MCP server tools for library management:
Quality Assurance Checklist
When recommending a library, verify:
Example Recommendation Session
User: "I need rounded cubes for my design."
Librarian:
- Query available libraries → Find BOSL2, MCAD/boxes
- Analyze needs → Rounded corners, parametric size, possibly different corner radii
- Recommend → Show BOSL2's
rounded_cube() module (superior to MCAD alternative)
- Installation → Check if BOSL2 is available; if not, offer installation
- Guidance → Provide code example with parameters explained
- Variants → Show how to parametrize roundness, suggest size variations
use <BOSL2/rounding.scad>;
// Create a rounded cube: size=[width, depth, height], corner radius
rounded_cube([50, 40, 30], r=5);
// Parametric version
size = 50;
radius = 3;
rounded_cube([size, size, size], r=radius);
When to Create Custom Code
If after library search no suitable module exists:
- Document why the search failed (library missing, functionality gaps)
- Propose custom creation approach
- Suggest using library components as building blocks (compose/extend)
- Explain advantages of custom code (control, optimization)
- Consider suggesting the user request the library authors (open source feedback)
Tips for Maximum Effectiveness
- Know the library landscape — Regularly review available libraries
- Ask clarifying questions — Understand the real need before recommending
- Show code examples — Make recommendations concrete and executable
- Document decisions — Help user understand why one library beats another
- Verify installations work — Test recommendations in the actual workspace
- Link to sources — Provide paths to library documentation and repositories
- Suggest combinations — Multiple libraries often work better together
