Installation and your first check

日本語 · Usage · Notices

Requirements / Skill / Updates / FreeCAD / Blender / AI connection / Troubleshooting

Requirements depend on what you want to do

This distribution is a workflow skill, not a complete model generator. It does not bundle or automatically install CAD, finished scenes, reference images, fonts or an MCP server. Review installations and permissions yourself.

The reference project's FreeCAD 1.1.3, Blender 5.1.1 and ffmpeg 8.1 are historical tool versions, not requirements or compatibility guarantees for every OS. Select packages for your OS, CPU and GPU from official sources. Blender support differs notably between Intel and Apple Silicon Macs.

1. Copy the skill

The layout follows GitHub's official Agent Skills guide and CLI skill installation. Skills contain instructions and code: read them before installing. This skill does not grant blanket shell preapproval through allowed-tools.

Download: the skill-only ZIP (SHA-256), or Code → Download ZIP in the repository. Extract first. In the full repository ZIP, the source folder is .github/skills/lego-like-3d-print. To see hidden .github, use Command+Shift+. in macOS Finder, Ctrl+H in many Linux file managers, or enable hidden items in Windows File Explorer.

Choose one location and copy the whole folder, including LICENSE, NOTICES, references and scripts. Do not register separate Japanese/English SKILL.md files or duplicate the same skill at both scopes. This distribution repository already has its project skill installed in the correct location.

Non-overwriting copy on macOS / Linux

Run this example from the extracted repository root. For the skill-only ZIP, change src to ./lego-like-3d-print. An existing destination stops the copy; nothing is deleted or overwritten.

(
  set -eu
  src=".github/skills/lego-like-3d-print"
  dest="$HOME/.copilot/skills/lego-like-3d-print"
  test -f "$src/SKILL.md" || { echo "STOP: source SKILL.md not found" >&2; exit 1; }
  if [ -e "$dest" ] || [ -L "$dest" ]; then
    echo "STOP: destination exists; use the update procedure" >&2
    exit 1
  fi
  mkdir -p "$(dirname "$dest")"
  cp -R "$src" "$dest"
)

For a project install, set dest to that repository's .github/skills/lego-like-3d-print, for example dest="../my-model/.github/skills/lego-like-3d-print". Verify the target repository before running.

Non-overwriting copy in Windows PowerShell

Again, run from the extracted repository root. For the skill-only ZIP, change $source to ./lego-like-3d-print.

$ErrorActionPreference = "Stop"
$source = ".github/skills/lego-like-3d-print"
$destination = Join-Path $HOME ".copilot/skills/lego-like-3d-print"
if (-not (Test-Path -LiteralPath "$source/SKILL.md")) {
    throw "STOP: source SKILL.md not found"
}
if (Test-Path -LiteralPath $destination) {
    throw "STOP: destination exists; use the update procedure"
}
New-Item -ItemType Directory -Force -Path (Split-Path $destination) | Out-Null
Copy-Item -LiteralPath $source -Destination $destination -Recurse

For project scope, change $destination to the location inside the target repo. A file-manager copy is also fine; cancel any replacement prompt and follow the update procedure instead.

Load it in Copilot

CLI: Start a new session, or type these inside an existing interactive CLI:

/skills reload
/skills info lego-like-3d-print

These are not OS shell commands. Check that /skills info reports the intended location. Copilot app: Open a new session in the target project after copying, then ask "Use lego-like-3d-print; first explain the baseline and available tools." Type / to inspect the app's actual command picker; do not assume the CLI's /skills reload is available there. See the official app command reference.

2. Update without destroying an existing skill

Extract the new version into a separate staging folder. Review differences in SKILL.md, references and scripts; manually integrate any personal changes into the staged version. Preserve the old folder outside skill discovery locations (for example ~/skill-backups/2026-09-23/), then use the guarded copy above once the destination is absent. Choose a different backup name if it already exists. Merely renaming the old folder inside .copilot/skills can expose two skills with the same name. Reload in the CLI or start a new app session. No automatic overwrite or rm -rf is needed.

3. Install FreeCAD

Use the official downloads and linked official releases. Start with a stable release, not a weekly/development build. Check the chosen release's requirements and checksums rather than relying on a permanently hardcoded "latest" version number.

Linux example: replace FreeCAD-downloaded.AppImage with the actual filename.

chmod +x ./FreeCAD-downloaded.AppImage
./FreeCAD-downloaded.AppImage

Official instructions: macOS / Windows / Linux / AppImage. If the OS warns about unsafe or untrusted software, do not ask the AI to bypass the warning. Verify provenance/signing and make the decision yourself.

Confirm version and embedded Python

Launch FreeCAD and check About FreeCAD (the application menu on macOS, usually Help elsewhere). Show View → Panels → Python console and enter these lines one at a time. They do not change documents.

import FreeCAD as App
import sys
print("FreeCAD:", App.Version())
print("Python:", sys.version)
print("Application home:", App.getHomePath())
print("FreeCAD module:", App.__file__)
print("Executable:", sys.executable)

This is FreeCAD's Python, not necessarily your system python / python3 or the site's venv. pip install FreeCAD is not a substitute for installing the app.

A safe small check

Review freecad_smoke.py, then run it from the FreeCAD Python console. Replace the path below with the actual downloaded/copied script (Windows paths can go in the raw string too).

from pathlib import Path
script = Path(r"REPLACE_WITH_FULL_PATH_TO/freecad_smoke.py")
exec(compile(script.read_text(encoding="utf-8"), str(script), "exec"), {"__name__": "__main__"})

Alternatively, create a macro with an unused name through Macro → Macros, paste this small script and run it. Do not overwrite an existing macro. Each run creates a test-only 8×8×3.2 mm box, saves FCStd / STEP / STL into a new temporary folder and checks reopening. It does not save or close your existing documents; it closes only its own test documents. Success prints FREECAD_SMOKE_OK and the output location. This box has no studs or sockets; it is not a fit coupon or print kit.

CLI or embedded interpreter access from the AI

Use the console output above to locate actual installed files and inspect their --help. sys.executable may point to the GUI itself, not a standalone Python. On macOS use Finder's Show Package Contents, or these read-only listings:

ls "/Applications/FreeCAD.app/Contents/MacOS"
ls "/Applications/FreeCAD.app/Contents/Resources/bin"

On Windows inspect bin under your recorded installation location. On Linux use the AppImage's supported launch route or actual files discovered by command -v FreeCADCmd freecadcmd freecad. Names and locations vary by package. Even a matching interpreter can require the FreeCAD module search path. For the macOS layout above, after confirming Resources/lib/FreeCAD.so exists:

PYTHONPATH="/Applications/FreeCAD.app/Contents/Resources/lib" \
  "/Applications/FreeCAD.app/Contents/Resources/bin/python" \
  ".github/skills/lego-like-3d-print/scripts/freecad_smoke.py"

This example runs from the repository root; it is not a universal OS path. Do not mix Python versions, CPU architectures or ABIs, such as a macOS module with another Windows Python. Use the GUI console/macro if unsure. Prefer a separate process that does not operate on your existing GUI work.

4. Install Blender

Read the official download page, requirements and installation manual.

Official OS instructions: macOS / Windows / Linux.

Cross-version compatibility: A reference scene saved in Blender 5.1.1 is not guaranteed to reproduce unchanged in 4.5 LTS. This skill bundles no finished scenes. Normally, build a scene from the real STL/meshes in your supported Blender version. Keep originals and test migrations on separate copies.

Check the splash screen / About Blender, or use --version on the actual executable. Run the following in a separate background process so an existing unsaved interactive scene is not erased. These examples run from the extracted repository root. With the skill-only ZIP or an installed copy, replace the argument after --python with the actual full path to that copy's blender_smoke.py.

macOS, using the usual installation location:

"/Applications/Blender.app/Contents/MacOS/Blender" --version
"/Applications/Blender.app/Contents/MacOS/Blender" --background --factory-startup \
  --python-exit-code 1 --python ".github/skills/lego-like-3d-print/scripts/blender_smoke.py"

Windows PowerShell: replace $blender with your actual installation path.

$blender = "C:\PATH_TO_BLENDER\blender.exe"
& $blender --version
& $blender --background --factory-startup --python-exit-code 1 `
  --python ".github/skills/lego-like-3d-print/scripts/blender_smoke.py"

Linux: use the extracted location, or locate a PATH installation with command -v blender.

BLENDER="./PATH_TO_EXTRACTED_BLENDER/blender"
"$BLENDER" --version
"$BLENDER" --background --factory-startup --python-exit-code 1 \
  --python ".github/skills/lego-like-3d-print/scripts/blender_smoke.py"

blender_smoke.py creates a test-only box equivalent to 8×8×3.2 mm in a new scene, saves a .blend in a new temporary folder and reopens it. It does not render. Look for BLENDER_SMOKE_OK. It refuses a foreground instance before changing anything. This is not a system-Python bpy installation procedure. See the official CLI arguments.

5. What the AI needs to execute

The skill explains what to do and check; it does not extend permissions. The AI needs access to project files and a permitted shell or compatible CAD tool connection. With GUI-only access, you can review AI-generated code and run it yourself through the console/macro. With CLI access, identify real paths and versions and ask for only the smoke check first.

MCP is optional. Copying this skill does not install, configure or start a server. If you use one, separately review the connector's official setup, permissions, current schema and live scene state. Installing the skill alone does not make FreeCAD or Blender executable.

Troubleshooting, and what a check actually proves

Reviewing official instructions is different from executing them on every OS/CPU/version. A box generation/reopen pass is not a render, complete-model manufacturing, slicing, fit/retention/tipping test or compatibility guarantee. Check your own environment, then follow the physical trial gates.