Guides
How to write a SKILL.md that teaches Claude your Blender workflow
Write a SKILL.md that teaches Claude your Blender workflow: frontmatter rules, structure, a full example, scripts, testing and common mistakes.
7 min read

Quick answer
How do I write a SKILL.md for Blender?
Create a folder named after the skill, add a SKILL.md with a short name and a description of when to use it, then write numbered instructions for the Blender job: units, naming, the bpy steps and the checks to run. Add tested scripts as separate files, and edit the skill whenever Claude gets something wrong.
Pick one job, not a philosophy
The skills that work are narrow. "Everything about our Blender pipeline" becomes a long document that Claude half-follows. "Prepare a prop for export to Unity" is a job Claude can run start to finish and check.
Good first candidates are the jobs you repeat weekly:
- cleaning and exporting props
- setting up a new scene with your units, collections and camera
- batch-renaming and organising an imported kit
- checking a file before handing it to someone else
Write one skill per job. They're cheap, because until a skill triggers only its name and description sit in Claude's context, at roughly 100 tokens each according to Anthropic's Agent Skills overview.
The folder
A skill is a folder whose name matches the skill. For Claude Code:
- one project:
.claude/skills/blender-prop-export/SKILL.md - all your projects:
~/.claude/skills/blender-prop-export/SKILL.md
Supporting files sit beside it, for example:
.claude/skills/blender-prop-export/SKILL.md.claude/skills/blender-prop-export/naming.md.claude/skills/blender-prop-export/scripts/apply_and_origin.py
For claude.ai or Claude Desktop, you upload the folder as a custom skill. Skills don't sync between surfaces, so keep one copy in a repo and upload from there.
The frontmatter
Two fields are required, and both have rules worth knowing before the upload fails:
name: at most 64 characters, lowercase letters, numbers and hyphens only. It can't contain the words "anthropic" or "claude", soclaude-blenderis rejected butblender-prop-exportis fine.description: non-empty, at most 1,024 characters, no XML tags.
Claude Code accepts more optional fields, listed in the Claude Code skills docs. The useful ones for Blender work are:
disable-model-invocation: truestops Claude from triggering the skill by itself, so it runs only when you type/blender-prop-export. Use it for anything that writes files.allowed-toolslimits what Claude can use while the skill runs.when_to_useadds extra trigger context next to the description.argumentsandargument-hintlet you pass a value, such as an asset name, when you call the skill.
Writing the description
The description decides whether the skill ever runs, so it matters more than anything below it. Write it in the language you'd actually type, and say both what the skill does and when to use it:
- Weak: "Blender helper."
- Better: "Use when cleaning up, preparing or exporting a Blender prop for the Unity project. Applies scale, origins, naming and the project's FBX settings, then reports triangle counts."
The body: steps, settings, checks
Keep the body procedural. Claude follows a numbered list far more reliably than an essay. A structure that works:
- Goal: one sentence.
- Before you start: what to read or ask, for example "Get the scene summary first. Ask for the asset name if the objects are unnamed."
- Steps: numbered, with exact values.
- Export: exact settings.
- Check and report: what to verify and what to print.
- Never: two or three hard limits, such as "never delete objects without listing them first".
A full example
Here is a complete SKILL.md for a Unity prop workflow, shown line by line:
---name: blender-prop-exportdescription: Use when cleaning up, preparing or exporting a Blender prop for the Unity project. Applies scale, origins, naming and FBX settings, then reports triangle counts.disable-model-invocation: true---# Prop exportGoal: every selected mesh leaves Blender ready to drop into Unity.## Before you start- Get the scene summary. If nothing is selected, ask which objects to export.- Read naming.md for the prefixes.## Steps1. Apply rotation and scale on each selected mesh.2. Set the origin to the bottom centre of the bounds (run scripts/apply_and_origin.py).3. Rename meshes SM_<Asset>_<Part> and materials M_<Asset>.4. Recalculate normals outside.## Export- FBX, one file per asset, into //export/.- Apply Scalings: FBX All. Forward: -Z. Up: Y. Apply Transform: on.- Smoothing: Face. Add Leaf Bones: off. Path Mode: Copy, Embed Textures on.## Check and report- List each file with its triangle count and material count.- Flag any mesh over 15,000 triangles or with more than 2 materials.## Never- Never delete or join objects unless asked.- Never save over the .blend; save a copy with _export appended.
Every value in that file is one you choose, not a Blender default. The point is that they're written down once.
Put long material in separate files
Anything Claude only sometimes needs goes in its own file, and the skill says when to read it: "For prop prefixes, read naming.md." That third level of loading is what keeps a skill fast. Good candidates:
- a naming reference (see AI 3D asset naming conventions for a starting point)
- polycount budgets per asset type
- engine-specific export notes for Unity, Unreal and Godot
Scripts: when to write Python yourself
Claude writes bpy code well, but it writes it fresh each time, and it sometimes reaches for an operator that changed between Blender versions. If a step must behave identically every run, such as setting origins, applying transforms or batch export, put a tested script in scripts/ and tell the skill to run it. Scripts run through bash or Blender MCP's code tool, and only their output enters the conversation.
Test the script once in Blender's Scripting workspace on your version before you ship the skill. Can Claude write Blender Python scripts? covers how to review what Claude writes.
Test it on a real file
- Connect Blender MCP (setup guide) and open a test scene. Save a copy first, because these tools run code in your file.
- Call the skill:
/blender-prop-export. - Watch what Claude does and read its report.
- Every time it deviates, change the wording of the skill, not just the chat. If it named a mesh
SM_crateinstead ofSM_Crate, write the casing rule into the skill. - Run it again on a different scene.
Two or three rounds usually turn a rough skill into one you trust.
Mistakes that make skills fail
- A vague description. The skill never triggers, or triggers on unrelated requests.
- A long essay instead of steps. Claude skims prose and follows lists.
- No check step. Claude reports "done" without looking. Ask for counts you can verify.
- Hard-coded paths from one machine. Use paths relative to the
.blend(//export/) so the skill works for your team. - Secrets in the skill. Never put API keys in
SKILL.md. It's a plain text file that gets shared. - Installing someone else's skill unread. Skills can carry scripts, so read every file first.
What a SKILL.md can't do
It can't connect Claude to Blender. That's MCP's job, explained in Claude skills for Blender. It can't make Claude perfect at organic modelling. And it can't be enforced: it's instructions, not a validator. For hard guarantees, put the logic in a script and have the skill run it.
Next: give the skill something to export
A prop-export skill is most useful when props arrive quickly. Generate them in Vi3W from text, an image or a sketch. Use Clean shape to hit a face budget, then download GLB or FBX and let your skill take it from there. With the Vi3W MCP server, which launched today, Claude can request the model from the same chat. More ideas are in Claude skill for game-ready asset checks.
Frequently asked questions
claude blender skill md
A Claude Blender SKILL.md is a Markdown file with name and description frontmatter and your Blender instructions underneath. Claude reads it when a Blender task matches the description, and uses it alongside Blender MCP's tools.
what does skill md look like
It looks like a short Markdown document: a YAML block between two --- lines holding name and description, then headings and numbered steps. Anything longer goes in separate files the skill points to.
skill.md best practices
Write the description in the words you'd use to ask for the task, keep the body short and procedural, move long references and scripts into their own files, end with a check step, and only install skills whose files you have read.
how to write skill md
Start from one job you repeat, write the frontmatter, list the steps in order with the exact settings, add what to check before finishing, then test it on a real file and fix the wording where Claude went wrong.
Last reviewed

