Skip to content
Get packs

Guide · Agent skill

How to use the FreeCAD Python Scripting agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The FreeCAD Python Scripting skill (skill name freecad-scripts) is a set of reference notes and examples that an AI agent reads before writing FreeCAD Python code. It is aimed at CAD users who want to automate repeated modeling steps, Python developers building workbenches or parametric objects, and engineers who want a starting script from a written description of a part. After this guide you will know what the skill does, how to install it, how to ask for work in a way that triggers it, and what to check before running the scripts it produces.

FreeCAD Python Scriptinggithub/awesome-copilot · MIT

Quick start

  1. 1Install FreeCAD. Make sure FreeCAD 0.19 or newer is installed. Version 0.21 or 1.0 or later is recommended for the latest API.
  2. 2Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
  3. 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
  4. 4Describe your FreeCAD task. Write the task in plain words, including dimensions and units, and mention FreeCAD.
  5. 5Review the generated script. Read the code, check object names and dimensions, and confirm it does not touch objects you need to keep.
  6. 6Run it in FreeCAD on a copy. Run the script inside FreeCAD on a copy of your model, then check the result visually and with properties such as Volume.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches the skill's description. This one is called freecad-scripts. Its SKILL.md file describes it as an expert skill for writing FreeCAD Python scripts, macros, and automation.

Once installed, the agent knows the FreeCAD Python API well enough to turn plain-language or rough descriptions of 3D parts into working scripts. The source describes it as covering the Part, Mesh, and Sketcher modules, FeaturePython objects, PySide GUI dialogs, Coin3D scenegraph work through Pivy, and macro development.

  • Create primitive shapes such as boxes, cylinders, spheres, cones and tori
  • Run booleans (fuse, cut, common), fillets, chamfers, lofts and sweeps
  • Create and manage documents, objects and placements
  • Build parametric FeaturePython objects with custom properties
  • Draft macros or PySide GUI dialogs

What the skill does not do

The skill does not open FreeCAD. It is a set of reference notes and examples the agent reads; the agent writes the script, and you run that script inside FreeCAD yourself. The generated scripts cannot run without FreeCAD, because they depend on FreeCAD's bundled Python modules.

According to the metadata, the skill does not run scripts and does not use the network.

How do you install the freecad-scripts skill?

Download the ZIP file for the skill from this page and unzip it. You can install it in one of two places. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

What do you need installed first?

The skill writes scripts for FreeCAD, so FreeCAD must be installed on the machine where you run them. The skill's source lists FreeCAD 0.19 or newer, with 0.21+ or 1.0+ recommended for the latest API.

Python 3 comes bundled with FreeCAD. PySide2 is needed only for GUI work and Pivy only for Coin3D scenegraph work; both are also bundled with FreeCAD.

  • FreeCAD 0.19+ (0.21+ or 1.0+ recommended for the latest API)
  • Python 3 (bundled with FreeCAD)
  • PySide2 for GUI work (bundled with FreeCAD)
  • Pivy for Coin3D scenegraph work (bundled with FreeCAD)

How do you trigger the skill with a natural request?

You do not need a special command. Describe the FreeCAD task in plain words, and mention FreeCAD so the agent's description match is clear. The skill's description lists the kinds of requests it covers: creating FreeCAD models, parametric objects, Part, Mesh or Sketcher scripts, workbench tools, PySide GUI dialogs, Coin3D scenegraph manipulation, and any FreeCAD Python API task.

Rough descriptions work. The skill is designed to interpret shorthand, quasi-code and natural language descriptions of 3D modeling tasks.

  • Write a FreeCAD macro that makes a 10 x 10 x 10 mm box with a 2 mm hole through the centre.
  • Give me a FreeCAD Python script for a flanged bushing: a cylinder with a bore and four bolt holes on a circle.
  • Make a parametric FeaturePython object in FreeCAD with a Width and Height property.
  • Write a PySide dialog for FreeCAD that asks for a radius and creates a sphere.

Example: a short script the skill can produce

The reference material uses the Part module to build shapes and the document model to show them. The following pattern is taken from the skill's own examples: create a box, set its size on a document object, and recompute.

Read generated code before you run it. Check the object names and dimensions against what you asked for.

import FreeCAD doc = FreeCAD.newDocument("MyDoc") box = doc.addObject("Part::Box", "MyBox") box.Length = 10.0 box.Width = 10.0 box.Height = 10.0 doc.recompute()

What safety checks should you run on generated scripts?

The skill's scripts can modify or delete document objects. Do not run generated scripts blindly on important models. Open a copy of your file first, read the script, and run it on the copy.

The skill does not run scripts and does not use the network, so the agent does not execute code for you. You are the one who runs it inside FreeCAD.

  • Work on a copy of any model that matters
  • Read the whole script before running it, especially any lines that call removeObject
  • Check the result visually and by looking at properties such as Volume and BoundBox

Tips for better results

Give the agent the dimensions, units and the FreeCAD workbench you are working in. State whether you want a one-off script, a macro, a parametric object or a GUI dialog, because the skill covers each of these differently.

Ask for small pieces first. A single primitive plus one boolean is easier to verify than a full assembly in one request.

  • State dimensions and units explicitly
  • Say which kind of output you need: script, macro, FeaturePython object or PySide dialog
  • Start with a simple part and build up
  • Name the objects you want created so you can find them in the tree

What people use it for

  • Automating a repeated modeling step, such as creating the same bracket with different dimensions each time, using a macro
  • Building a parametric FeaturePython object with custom properties for a reusable part
  • Writing a PySide dialog that asks for values and then creates geometry in the active document
  • Generating a starting script for a part described in words, which you then refine by hand
  • Converting between Part shapes and Mesh objects for export workflows

Frequently asked questions

How do I install the FreeCAD scripting agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What do I need to use the freecad-scripts skill?

You need FreeCAD 0.19 or newer, with 0.21+ or 1.0+ recommended for the latest API. Python 3, PySide2 and Pivy are bundled with FreeCAD, so a normal FreeCAD install covers them.

Is the freecad-scripts skill free?

The skill is published under the MIT licence. Check the licence text on this page for the terms that apply to your use.

Does the skill run FreeCAD for me?

No. The skill is reference notes and examples that the agent reads to write scripts. It does not open FreeCAD, does not run scripts and does not use the network, so you run the generated script yourself.

Why does my generated script fail?

Check that you are running it inside FreeCAD, since the scripts depend on FreeCAD's bundled modules and will not run in a plain Python environment. Also check your FreeCAD version against the 0.19+ minimum, and confirm object names match those in your document.

How does this compare with writing FreeCAD macros by hand?

The skill saves you from looking up Part, Mesh and Sketcher API calls by hand and gives a starting script quickly. You still need to review and test the output, because the skill cannot run it or check it against your model.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already have FreeCAD and want an agent to draft macros, parametric objects or PySide dialogs from written descriptions. Skip it if you do not have FreeCAD installed, or if you want a tool that runs and verifies models for you, since this skill only writes the scripts and you must review and run them.

Download the skill