Skill Creator

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 24034f36bad7 · 19 Oct 2026Report an issue or request a re-scan

• Publisherghbalf GitHub userOwner of the repository this skill is read from
• Source folderghbalf/freecad-ai/skills/skill-creatorThe exact folder we audited
• LicenceLGPL-2.1As the repository states it
• Commit pinned for this verdict24034f36bad7A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create new FreeCAD AI skills, modify existing skills, and iteratively improve them. Use when users want to create a skill from scratch, update or optimize an existing skill, capture a workflow as a reusable skill, or…

---
name: skill-creator
description: Create new FreeCAD AI skills, modify existing skills, and iteratively improve them. Use when users 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 trigger when the user says "turn this into a skill", "make a skill for X", "save this as a command", or similar.
---

# 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:

```markdown
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:
```markdown
ALWAYS use offset=H on the pocket sketch. NEVER pocket from z=0.
```

Write:
```markdown
Place the pocket sketch at offset=H (top face of the solid). Pocketing from z=0
creates a hollow that opens upward with n

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-19
   ✓SAFE B 89 / 100

   first audit · source 24034f36bad7

Questions about Skill Creator

• github.com/ghbalf/freecad-ai/tree/master/skills/skill-creator — the audited source at commit 24034f36bad7 and every finding aboveObserved · 19 Oct 2026

Spotted something wrong? Report a correction · Methodology