Skills

Skills

Skills are reusable instruction sets that teach the LLM how to build specific types of FreeCAD models. Instead of describing every step from scratch each time, you invoke a skill with a short /command and the assistant follows a proven construction recipe.

Overview

Skills are stored in <FreeCADAI dir>/skills/. Each skill is a directory containing:

• SKILL.md (required): Markdown instructions that get injected into the LLM prompt. These tell the assistant exactly what FreeCAD operations to perform, in what order, with what parameters. May include optional YAML frontmatter with name and description fields.
• handler.py (optional): A Python module with an execute(args) function. When present, the handler runs before prompt injection and can perform calculations, validate parameters, or return direct output.
• references/ (optional): Directory containing additional documentation files loaded on demand. Useful for keeping SKILL.md concise while providing detailed reference data (dimension tables, material properties, etc.).

Skills are loaded automatically when the SkillsRegistry is created. The registry scans every subdirectory under SKILLS_DIR (<FreeCADAI dir>/skills/), looking for directories that contain a SKILL.md file.

Invoking Skills

Type a /command in the chat input field. Everything after the command name is passed as arguments to the skill.

Examples:

/enclosure 100x60x40mm, 2mm walls, snap-fit lid
/gear module=2 teeth=24
/thread-insert M3 at corners
/lattice honeycomb 8mm cells inside the top panel
/fastener-hole M4 counterbore at (10,10), (60,10), (60,40), (10,40)
/skill-creator I need a skill for creating mounting brackets

Skills work in both Plan and Act modes. In Plan mode, the LLM will describe the steps it plans to take based on the skill instructions. In Act mode, it executes the steps immediately using tool calls.

How Skills Work

The execution flow when you type a /command:

1. Command matching -- SkillsRegistry.match_command() splits the input into the command (e.g., /enclosure) and the remaining arguments (e.g., 100x60x40mm, 2mm walls, snap-fit lid). It checks all registered skills for a trigger match.

2. Skill execution -- SkillsRegistry.execute_skill() is called with the matched skill name and arguments.

3. Handler check -- If the skill directory contains a handler.py with an execute() function, the handler is called first. The handler receives the raw argument string and returns a dict:

   • {"inject_prompt": "text"} -- inject text into the LLM prompt (adds to or replaces the SKILL.md content)
   • {"output": "text"} -- display the text directly to the user without involving the LLM
   • {"error": "text"} -- display an error message

4. Prompt injection -- If no handler exists (or the handler returns None), the full contents of SKILL.md are injected into the LLM's system prompt. The LLM then follows the skill's instructions to create the model, using the standard tool calling system.

5. Tool execution -- The LLM processes the injected instructions alongside the user's arguments and makes tool calls (create_body, create_sketch, pad_sketch, pocket_sketch, etc.) to build the model step by step.

Skill Discovery

Skills are discovered at registry creation time:

<FreeCADAI dir>/skills/
  enclosure/
    SKILL.md              <-- loaded
  gear/
    SKILL.md              <-- loaded
  my-custom-skill/
    SKILL.md              <-- loaded
    handler.py            <-- detected, execute() called on invocation
    references/           <-- optional docs loaded on demand
      dimensions.md
  empty-dir/              <-- skipped (no SKILL.md)
  notes.txt               <-- skipped (not a directory)

Each skill gets a trigger command derived from its directory name: the directory thread-insert becomes the command /thread-insert.

The skill's description is extracted automatically using this priority order:

1. The description field from YAML frontmatter (if present)
2. The first non-empty, non-heading line of the SKILL.md body

This description appears in the system prompt so the LLM knows what skills are available.

YAML Frontmatter (Optional)

Skills can include YAML frontmatter at the top of SKILL.md:

---
name: my-skill
description: Create parametric mounting brackets with configurable hole patterns.
---

# My Skill

Construction instructions here...

The description field is preferred over body-text extraction and supports longer, more descriptive text. The name field is informational (the directory name is always used for the trigger command).

Built-in Skills

FreeCAD AI ships with 7 built-in skills covering common mechanical design tasks:

Command	Description
/enclosure	Parametric electronics enclosure with base + lid (screw, press-fit, or snap-fit)
/gear	Involute spur gear from module and tooth count using Part geometry
/fastener-hole	Clearance, counterbore, or countersink holes with standard metric dimensions
/thread-insert	Heat-set threaded insert holes sized for 3D printing
/lattice	Grid, honeycomb, or diagonal infill patterns for lightweight structures
/sketch-from-image	Extract 2D geometry from an attached image and create a FreeCAD sketch
/skill-creator	Meta-skill that guides you through creating new skills interactively

The built-in skills are bundled in the workbench source at skills/ and are copied to SKILLS_DIR on first run. You can modify them freely -- your copies in <FreeCADAI dir>/skills/ take precedence.

Skill Descriptions in the System Prompt

The SkillsRegistry.get_descriptions() method generates a formatted list of all available skills that is included in the LLM's system prompt. This ensures the assistant knows which skills exist and can suggest them when relevant. The format looks like:

## Available Skills

### enclosure
Generate a parametric electronics enclosure with a base and lid.
Invoke with: `/enclosure`

### gear
Create an involute spur gear using FreeCAD's Part module.
Invoke with: `/gear`

This means the LLM can proactively suggest using a skill when the user's request matches one, even if the user does not know about it.

---

See Skills Reference for detailed documentation of each built-in skill, including parameters, construction steps, and examples.

See Creating Skills for a guide on writing your own skills.

---

Next: Skills Reference | Creating Skills | Tool Reference