Skill Creator

Skill Creator

A skill for creating new FreeCAD AI skills and iteratively improving them.

At a high level, the process goes like this:

• Understand what the user wants the skill to do
• Interview for details — parameters, edge cases, construction approach
• Write a draft of the skill (SKILL.md + optional handler.py)
• Test it by running the /command and evaluating the result
• Improve based on what worked and what didn't
• Repeat until the user is satisfied

Your job is to figure out where the user is in this process and help them move forward. Maybe they say "I want a skill for X" — help them scope it, write the draft, and test it. Or maybe they already have a skill that needs fixing — jump straight to the improvement loop.

Be flexible. If the user says "just write it, I'll test it myself", do that. If they want to iterate 5 times, do that too.

Communicating with the user

FreeCAD AI users range from experienced CAD engineers to hobbyists who just discovered parametric modeling. Pay attention to context cues — if they use terms like "involute" and "datum plane", match that level. If they say "I want to make a box thing with holes", keep things simple.

Creating a skill

Step 1: Capture intent

Start by understanding what the user wants. The current conversation may already contain a workflow worth capturing (e.g., they say "turn this into a skill"). If so, extract what you can from the conversation — the tools used, the sequence of steps, corrections the user made, dimensions and parameters observed. The user may need to fill gaps, and should confirm before you proceed.

Ask (skip questions they already answered):

1. What should the skill do? — e.g., "generate a mounting bracket", "create a gear train"
2. What parameters should the user provide? — dimensions, counts, materials, tolerances
3. When should someone use this? — what would they type to invoke it?
4. What's the construction approach? — which FreeCAD operations, in what order?
5. Are there edge cases? — minimum wall thickness, maximum overhang angle, material constraints
6. Should it have a Python handler? — for skills that need deterministic logic (calculations, lookups) rather than just LLM instructions

Step 2: Interview and research

Proactively ask about things the user might not think of:

• Standard dimensions — are there industry standards to reference? (bolt sizes, bearing bores, thread pitches)
• FreeCAD pitfalls — coplanar boolean failures, unclosed sketches, Revolution crashes with full-circle profiles
• Parameter validation — what ranges are reasonable? What breaks?
• Construction order — does the workflow depend on features being created in a specific sequence?

If the current document has relevant objects, inspect them with get_document_state and measure to understand the context.

Step 3: Choose a name

Pick a short, hyphenated name based on what the skill does. Confirm with the user. The skill will live at: ~/.config/FreeCAD/FreeCADAI/skills/<name>/ The user invokes it with /<name>.

Step 4: Write the SKILL.md

Anatomy of a skill

skill-name/
├── SKILL.md          (required — frontmatter `name` + `description`, then instructions)
├── handler.py        (optional, FreeCAD AI only — deterministic execute(args) handler)
├── references/       (optional — docs the model reads on demand, subfolders allowed)
│   ├── dimensions.md
│   └── materials.md
├── scripts/          (optional — Python scripts run with run_skill_script)
└── assets/           (optional — templates/data files the scripts open via __file__)

This is the open Agent Skills layout, so the same folder also works in Claude Code, Codex or Gemini CLI. Start SKILL.md with frontmatter whose name equals the folder name:

---
name: skill-name
description: "What it does and when to use it, in one or two sentences."
---

Quote the description: other harnesses parse it as strict YAML, where an unquoted : breaks it. Link files with relative Markdown links, e.g. [thread table](references/thread-tables.md); the model loads them with use_skill(name=..., resource="references/thread-tables.md").

Progressive disclosure

Skills use a layered loading system:

1. Name + first line — always visible in the skills list (~10 words)
2. SKILL.md body — loaded when the skill is invoked (<200 lines ideal)
3. References — loaded on demand when the skill tells the LLM to read them

Keep SKILL.md under 200 lines. If you need more detail (dimension tables, material properties, multi-variant instructions), put it in references/ and point to it from SKILL.md:

For standard metric thread dimensions, read `references/thread-tables.md`.

SKILL.md structure

A good SKILL.md includes:

• Title and one-line description
• Parameters the user should provide (with sensible defaults)
• Step-by-step construction instructions using the tool calling system
• Important notes — gotchas, tolerances, material considerations
• Reference data — standard dimensions, lookup tables (or pointers to reference files)

Writing style

Explain the why behind instructions, not just the what. The LLM is smart — if it understands the reasoning, it can adapt to situations the instructions don't cover explicitly.

Instead of:

ALWAYS use offset=H on the pocket sketch. NEVER pocket from z=0.

Write:

Place the pocket sketch at offset=H (top face of the solid). Pocketing from z=0
creates a hollow that opens upward with no floor — the pocket cuts from the sketch
plane downward into the solid, so starting from the top gives you a proper floor
at the bottom.

More guidance:

• Be specific about FreeCAD operations — name the exact tool, feature type, and property names
• Include default values — so the user can invoke with minimal arguments
• Use the tool names — create_sketch, pad_sketch, pocket_sketch, etc. The LLM knows all 33 tools
• Warn about pitfalls — but explain why they're pitfalls, not just "don't do this"