-
Notifications
You must be signed in to change notification settings - Fork 68
Skills Reference
Detailed documentation for all 9 built-in skills. Each skill is a set of instructions that the LLM follows to create specific FreeCAD models using the standard tool calling system.
Generate a parametric electronics enclosure with a base and lid.
This is the most complex built-in skill, producing a two-body assembly (base + lid) with optional screw posts, press-fit lip, or snap-fit mechanism. The construction follows a strict 10-step sequence to ensure correct geometry.
| Parameter | Default | Description |
|---|---|---|
| L (length) | -- | Outer length in mm (required) |
| W (width) | -- | Outer width in mm (required) |
| H (height) | -- | Outer height in mm (required) |
| T (wall thickness) | 2mm | Wall and floor thickness |
| Lid type | "screw" |
One of: screw, press-fit, snap-fit
|
| Post radius | 3mm | Screw post outer radius (screw lid only) |
| Screw size | M3 | Screw hole radius = 1.5mm, clearance = 1.75mm (screw lid only) |
The enclosure is built in 10 ordered steps. Some steps are skipped depending on the lid type.
| Step | Operation | Screw | Press-fit | Snap-fit |
|---|---|---|---|---|
| 1 | Create base body ("EnclosureBase") | Yes | Yes | Yes |
| 2 | Outer shell: pad rectangle (0,0)-(L,W) to height H | Yes | Yes | Yes |
| 3 | Interior pocket: sketch at offset=H, pocket depth=H-T | Yes | Yes | Yes |
| 4 | Screw posts: 4 circles at corners, pad H-T | Yes | Skip | Skip |
| 5 | Screw holes: 4 circles r=1.5mm, pocket through-all | Yes | Skip | Skip |
| 6 | Create lid body ("EnclosureLid") | Yes | Yes | Yes |
| 7 | Lid screw holes: 4 circles r=1.75mm, pocket through-all | Yes | Skip | Skip |
| 8 | Position lid with transform_object | Yes | Yes | Yes |
| 9 | Add ridge (base) + snap tabs (lid) | Skip | Skip | Yes |
| 10 | Hide all sketches | Yes | Yes | Yes |
Step 3 detail -- the pocket sketch must use offset=H so it sits on the top face of the padded solid. The pocket then cuts downward by H-T, leaving a floor of thickness T at the bottom. Placing the pocket sketch at z=0 instead would result in no floor.
Step 4 detail -- screw post positions are computed as:
- X positions:
T + PR(left),L - T - PR(right) - Y positions:
T + PR(front),W - T - PR(back)
This keeps the posts inside the cavity and clear of the walls.
Step 6 detail -- lid construction varies by type:
- Screw lid: Simple slab, rectangle (0,0)-(L,W), padded to thickness T.
-
Press-fit lid: Lip first (rectangle inset by
T+0.2mmon each side, padded 3mm), then slab on top atoffset=3(rectangle (0,0)-(L,W), padded T). The 0.2mm gap provides friction-fit clearance. - Snap-fit lid: Same as press-fit but with 1mm clearance instead of 0.2mm, providing room for the snap tab protrusion (0.5mm).
For press-fit and snap-fit, the lip extends from z=0 to z=3, and the slab from z=3 to z=3+T. After positioning with transform_object, the lip hangs down into the base cavity.
Step 9 detail -- snap-fit mechanism:
-
create_inner_ridgeadds a thin ridge (0.8mm wide, 0.5mm tall) around the inside of the base atz = H-2. -
create_snap_tabsadds 6 tabs on the lid lip exterior (2 per long side, 1 per short side) that catch on the ridge. - The lid must be positioned (step 8) before creating snap tabs, because the tool copies the lid's current shape including its placement.
/enclosure 100x60x40mm, 2mm walls, snap-fit lid
This creates:
- Base body: 100x60x40mm outer shell, 96x56mm interior cavity, 2mm walls and floor
- Lid body: 2mm slab with 3mm lip (1mm clearance for snap tabs)
- Inner ridge at z=38 on base
- 6 snap tabs on lid lip
Create an involute spur gear using FreeCAD's Part module.
Unlike most skills that use the PartDesign workflow (Body/Sketch/Pad), this skill uses execute_code with a complete Python script that builds the gear from mathematical curves using Part geometry directly.
| Parameter | Default | Description |
|---|---|---|
| Module (m) | 2.0mm | Tooth size parameter -- standard gear metric |
| Number of teeth (z) | 20 | Total tooth count |
| Pressure angle | 20 degrees | Standard involute pressure angle |
| Face width | 10mm | Thickness of the gear (extrusion depth) |
| Bore diameter | 5mm | Center hole diameter (0 = no bore) |
These are calculated automatically from the parameters:
| Dimension | Formula | Example (m=2, z=20) |
|---|---|---|
| Pitch diameter | d = m * z | 40mm |
| Tip diameter | da = m * (z + 2) | 44mm |
| Root diameter | df = m * (z - 2.5) | 35mm |
| Base circle radius | rb = (d/2) * cos(pressure_angle) | 18.79mm |
The skill provides a complete Python script that:
- Computes involute curve points from the base circle to the tip circle.
- Mirrors the curve to create both flanks of a single tooth.
- Connects the flanks with a tip arc and root arc.
- Builds a BSpline wire for each involute flank.
- Creates a closed tooth profile face and extrudes it.
- Creates a base cylinder at the root diameter.
- Fuses all teeth onto the base cylinder using
Part.fuse(). - Cuts the center bore hole using
Part.cut(). - Adds the result as a
Part::FeaturenamedGear_M{m}_Z{z}.
The script is inserted verbatim into execute_code with only the parameter values at the top changed to match the user's request.
/gear module=3 teeth=32 bore=8mm
This creates a gear with pitch diameter 96mm, tip diameter 102mm, root diameter 88.5mm, with an 8mm bore.
- The gear uses
Part::Feature, not PartDesign. It cannot be combined with PartDesign operations (pad, pocket, fillet within a body). - The gear is centered at the origin.
- Do not use
App.Guiin the script -- it may not be available. - The label includes the parameters for easy identification: "Gear M3 Z32".
Create standard fastener holes: clearance, counterbore, or countersink.
This skill provides reference tables for metric fastener dimensions so the LLM does not need to guess or calculate hole sizes.
Through-holes for a bolt to pass through without threading. Two fit classes are available:
| Size | Close Fit | Normal Fit |
|---|---|---|
| M2 | 2.2mm | 2.4mm |
| M2.5 | 2.7mm | 2.9mm |
| M3 | 3.2mm | 3.4mm |
| M4 | 4.3mm | 4.5mm |
| M5 | 5.3mm | 5.5mm |
| M6 | 6.4mm | 6.6mm |
| M8 | 8.4mm | 9.0mm |
A clearance hole with a larger shallow recess so the screw head sits flush or below the surface:
| Size | Clearance Hole | CB Diameter | CB Depth |
|---|---|---|---|
| M3 | 3.4mm | 6.5mm | 3.0mm |
| M4 | 4.5mm | 8.0mm | 4.0mm |
| M5 | 5.5mm | 10.0mm | 5.0mm |
| M6 | 6.6mm | 11.5mm | 6.0mm |
| M8 | 9.0mm | 15.0mm | 8.0mm |
A clearance hole with a conical recess for flat-head screws:
| Size | Clearance Hole | CS Diameter |
|---|---|---|
| M3 | 3.4mm | 6.3mm |
| M4 | 4.5mm | 8.4mm |
| M5 | 5.5mm | 10.4mm |
| M6 | 6.6mm | 12.6mm |
| Parameter | Description |
|---|---|
| Screw size | M2 through M8 |
| Hole type |
clearance, counterbore, or countersink
|
| Fit |
close or normal (clearance holes only) |
| Target object | Body or feature to cut into |
| Positions | List of XY coordinates, or a pattern description |
| Pattern | Optional: linear array (count + spacing) or bolt circle (diameter + count) |
- Create a sketch on the target face.
- For each hole position, add a circle with the clearance diameter.
- Pocket through-all for the clearance hole.
- For counterbore: create a second sketch with larger circles at the same positions, pocket to the counterbore depth.
- For countersink: use a cone shape (
Part.makeCone) to create the 90-degree chamfer at each position. - Hide all sketches after construction.
/fastener-hole M4 counterbore at (10,10), (60,10), (60,40), (10,40)
This creates 4 counterbore holes for M4 socket head cap screws: 4.5mm clearance holes through-all, with 8.0mm diameter counterbores to 4.0mm depth.
Create properly sized holes for heat-set threaded inserts in 3D printed parts.
Heat-set inserts are brass threaded inserts that are pressed into plastic parts using a soldering iron. They provide strong, reusable threads in 3D printed enclosures and brackets. This skill provides the correct hole dimensions for reliable insertion.
| Size | Insert Hole Diameter | Insert Depth |
|---|---|---|
| M2 | 3.2mm | 3.5mm |
| M2.5 | 3.6mm | 4.0mm |
| M3 | 4.0mm | 5.0mm |
| M4 | 5.6mm | 6.0mm |
| M5 | 6.4mm | 7.0mm |
If the insert needs a screw to pass all the way through the part, a smaller clearance hole is added below the insert pocket:
| Size | Clearance Hole Diameter |
|---|---|
| M2 | 2.4mm |
| M2.5 | 2.9mm |
| M3 | 3.4mm |
| M4 | 4.5mm |
| M5 | 5.5mm |
| Parameter | Description |
|---|---|
| Insert size | M2, M2.5, M3, M4, or M5 |
| Target object | Which body or feature to cut into |
| Positions | XY coordinates or a description (e.g., "at four corners") |
| Through-hole | Whether to add a clearance hole below the insert pocket |
- For each position, create a sketch on the target face.
- Draw a circle with the insert hole diameter from the reference table.
- Pocket to the insert depth.
- If a through-hole is requested: add a second smaller circle (screw clearance diameter) and pocket through-all.
- Hide all sketches after construction.
/thread-insert M3 at four corners of the enclosure
This creates 4 insert holes: 4.0mm diameter, 5.0mm deep. If through-holes are requested, an additional 3.4mm hole extends through the remaining material below each insert.
Generate a 3D lattice or infill pattern inside a bounding region.
Lattice patterns reduce material and weight while maintaining structural integrity. This skill creates 2D patterns that are extruded and boolean-intersected with a target region.
| Pattern | Description | Strength | Best For |
|---|---|---|---|
| Grid | Rectangular array of square or circular holes | Moderate | Simple weight reduction |
| Honeycomb | Hexagonal cells | Highest strength-to-weight | Structural panels, 3D printing infill |
| Diagonal | 45-degree crosshatch lines | Good in shear | Decorative panels, ventilation |
| Parameter | Default | Description |
|---|---|---|
| Pattern type | -- |
grid, honeycomb, or diagonal (required) |
| Region | -- | Existing object to fill, or bounding box dimensions (required) |
| Cell size | 10mm | Distance between pattern centers |
| Wall thickness | 1.5mm | Thickness of lattice walls/beams |
| Height/depth | -- | Extrusion height of the pattern |
- Create a sketch with a rectangular array of circles or squares.
- Spacing = cell_size. Hole diameter = cell_size - wall_thickness.
- Pad to the target height.
- Boolean-intersect with the bounding shape to trim.
- Create hexagonal cells (6 line segments per cell).
- Hex radius = cell_size / 2.
- Offset rows by cell_size * 0.75 horizontally and cell_size * sqrt(3)/2 vertically to create the interlocking pattern.
- Pad to the target height.
- Boolean-intersect with the bounding shape.
- Create a set of parallel lines at +45 degrees, spaced by cell_size.
- Create a second set at -45 degrees.
- Each line has width = wall_thickness.
- Pad to the target height.
- Boolean-intersect with the bounding shape.
- Always create the lattice pattern larger than the target region, then use boolean intersection to trim it to shape. This avoids edge artifacts.
- Label the result clearly with the pattern type and cell size: "Lattice Honeycomb 8mm".
- For 3D printing, ensure
wall_thickness >= 2x nozzle diameter(typically >= 0.8mm for a 0.4mm nozzle). - The skill instructions mention a "gyroid" pattern type as advanced, but it is not implemented in the construction steps.
/lattice honeycomb 8mm cells inside the top panel
This creates a honeycomb pattern with 8mm cell spacing, extruded to match the panel thickness, and trimmed to fit the panel outline.
Extract 2D geometry from an attached image and create a FreeCAD sketch.
Early development. This skill is functional but under active development. Future versions will support dimension extraction from technical drawings, spline/curve tracing, and more geometry types. Expect the interface and behavior to change.
This is a prompt-only skill (no handler.py) -- the LLM interprets the attached image (or uses a vision-fallback MCP server like llm-vision-mcp) and translates visible shapes into create_sketch geometry.
| Input | Required | Default | Description |
|---|---|---|---|
| Attached image | Yes | -- | Drawing, sketch, reference photo, or technical drawing |
| Bounding size | Yes | -- | Real-world size in mm (e.g. "width 40mm" or "height 25mm") |
| Plane | No | XY |
Sketch plane: XY, XZ, YZ
|
| Body name | No | -- | Existing body to add the sketch to |
The bounding size is mandatory -- without a real dimension, the sketch is useless for CAD.
| Type | Sketch element |
|---|---|
| Rectangle | 4 line segments with auto-constraints |
| Circle | Full circle with radius constraint |
| Polygon | Connected line segments with coincident constraints |
| Line | Single line segment |
Curves and splines are approximated as polygons. For complex curves, manual tracing or a dedicated tracing tool is recommended.
- Attach an image and type
/sketch-from-image(or describe what you want: "create a sketch from this, width 40mm") - The LLM identifies shapes in the image, scales them to match the bounding size, and calls
create_sketch - To modify the sketch, ask naturally (e.g. "make the rectangle 50mm wide", "move the circle to the center")
- The LLM uses
edit_sketchwithclear_all=trueto replace geometry cleanly
- Dimension lines and annotations in the image are not extracted (planned for a future version)
- Hidden lines, section lines, and construction lines are treated as regular geometry
- Accuracy depends on the vision model's ability to interpret the image
- Requires a vision-capable LLM or a vision-fallback MCP server (e.g.
llm-vision-mcpwith Ollama)
Meta-skill for creating new skills, modifying existing skills, and iteratively improving them.
Use when you want to create a skill from scratch, update or optimize an existing skill, capture a workflow as a reusable skill, or improve an existing skill's instructions. Also triggers on phrases like "turn this into a skill", "make a skill for X", or "save this as a command".
The skill-creator follows an interview-and-iterate approach. It figures out where you are in the process and helps you move forward — whether you're starting from scratch or improving an existing skill.
The LLM understands what you want. If the current conversation already contains a workflow worth capturing (e.g., you say "turn this into a skill"), it extracts what it can — tools used, step sequence, corrections made, dimensions observed. It asks (skipping questions already answered):
- What should the skill do? — e.g., "generate a mounting bracket", "create a gear train"
- What parameters should the user provide? — dimensions, counts, materials, tolerances
- When should someone use this? — what would they type to invoke it?
- What's the construction approach? — which FreeCAD operations, in what order?
- Are there edge cases? — minimum wall thickness, maximum overhang, material constraints
- Should it have a Python handler? — for deterministic logic (calculations, lookups)
The LLM proactively asks about things you might not think of:
- Standard dimensions and industry references (bolt sizes, bearing bores, thread pitches)
- FreeCAD pitfalls (coplanar boolean failures, unclosed sketches, Revolution crashes)
- Parameter validation — reasonable ranges and failure modes
- Construction order dependencies
Pick a short, hyphenated name (e.g., mounting-bracket). The skill will live at <FreeCADAI dir>/skills/<name>/ and be invoked with /<name>.
Generate SKILL.md with YAML frontmatter (name and description fields), following these principles:
- Explain the why, not just the what — the LLM adapts better when it understands reasoning
- Use progressive disclosure — keep SKILL.md under 200 lines, put reference data in
references/ - Be specific about FreeCAD operations (exact tool names, property names)
- Include default values for all parameters
- Optionally generate a
handler.pyfor deterministic logic
After saving the files using execute_code, the LLM proposes 2-3 realistic test invocations:
/bracket 80x40mm, 4 mounting holes M4, 3mm thick aluminum
/bracket 30x20mm, 2 holes M3
/bracket — just use defaults
After each test run, the LLM:
- Checks results with
get_document_stateandmeasure - Notes what worked and what didn't
- Asks for your feedback
- Improves the skill and re-tests
The loop continues until you're satisfied or improvements plateau.
If you already have a skill that needs work:
- The LLM reads the current SKILL.md
- Asks what's not working — specific failures, edge cases, quality issues
- Runs test cases to reproduce the problems
- Applies improvements and re-tests
/skill-creator I need a skill for creating mounting brackets
The LLM will ask follow-up questions about bracket dimensions, mounting hole patterns, material thickness, and then generate the complete skill files. After saving, it will propose test invocations and iterate based on results.
Automatically optimize a skill's SKILL.md by running test cases, scoring results, and iteratively improving instructions.
Runs a multi-iteration loop: evaluate the skill against test cases, measure completion/error rate/geometry correctness, use the LLM to suggest SKILL.md improvements, re-evaluate, repeat. The best-scoring version is saved; the original is always backed up.
/optimize-skill
/optimize-skill enclosure
Opens a configuration dialog where you select the skill, define test cases, set iteration count, strategy (conservative/balanced/aggressive), and metrics.
| Metric | Weight (with VALIDATION.md) | Weight (without) | Description |
|---|---|---|---|
| Completion | 0.15 | 0.30 | Did the LLM finish without crashing? |
| Error rate | 0.15 | 0.25 | Ratio of successful tool calls |
| Correctness | 0.45 | disabled | Geometry validation pass rate |
| Efficiency | 0.10 | 0.10 | Fewer tool calls = better |
| Retries | 0.10 | 0.10 | Network retry count |
| Visual | 0.05 | 0.05 | Visual similarity (if configured) |
When a skill has a VALIDATION.md, correctness becomes the dominant metric, so broken geometry scores low even if the LLM "completes successfully."
If the skill has a VALIDATION.md, the dialog shows structured parameter fields (extracted from the validation rules). Otherwise, test cases are entered as free text.
Generate a draft VALIDATION.md for a skill by analyzing its SKILL.md construction steps.
This is a helper skill that reads an existing skill's SKILL.md, analyzes the geometry construction steps, and generates a starting-point VALIDATION.md with parameter definitions, body checks, bounding box expectations, and volume formulas.
/create-validation enclosure
/create-validation gear
The generated VALIDATION.md is a DRAFT, not a finished product. It will likely contain errors, especially in volume formulas. You must:
- Review every check -- does it match what the skill actually builds?
- Verify all volume formulas by hand -- calculate expected values for at least one set of dimensions and compare with the formula
-
Test with
--validate-- run the skill with known-good parameters and--validateto see if checks pass on correct geometry - Adjust tolerances -- defaults (0.5mm for bbox, 5% for volume) may need tuning
-
Check conditional rules -- verify each
whenblock covers the right checks for each variant
| Error | Why it happens |
|---|---|
| Wrong volume formula | Complex geometry with posts, holes, lips, ridges is hard to calculate |
| Wrong body labels | FreeCAD may rename bodies (e.g., "Body" instead of "EnclosureBase") |
| Missing conditional branches | LLM may not identify all skill variants |
| Tolerances too tight | Default 5% may not account for FreeCAD's fillet/chamfer volume changes |
/create-validation enclosure # Generate draft
# Review the generated VALIDATION.md
/enclosure 100 80 40 --validate # Test against actual geometry
# Edit VALIDATION.md to fix any failing checks
/enclosure 60 40 25 snap-fit --validate # Test another variant
Next: Creating Skills | Skills | Tool Reference