blender-python-addon — Claude Code skill: what it does, how to install
blender-python-addon — a skill for Claude Code that establishes best practices for Blender add-on development via the bpy API. Triggers when writing operators, UI panels, or bmesh routines.
Apache-2.0 111 installs ★ 312 updated 2026-10-08
npx skills add Mindrally/skills --skill blender-python-addon -a claude-codeWhat blender-python-addon does
The skill guides the assistant through structuring Blender add-ons with the bpy API. It specifies the setup for blender_manifest.toml in Blender 4.2+ extensions or the bl_info dictionary in legacy versions, along with paired register() and unregister() lifecycle functions in __init__.py.
It covers operator patterns under bpy.types.Operator using poll(), invoke(), and execute() hooks, UI panels with bpy.types.Panel, and settings management via PropertyGroup. For geometry tasks, it instructs the agent to batch modifications using bmesh, avoiding blocking UI loops with modal state timers.
Testing relies on running Blender with the --factory-startup flag to verify clean installation, execution, and unregistration.
What it helps with
- scaffold Blender add-ons using blender_manifest.toml or bl_info
- implement bpy.types.Operator classes with poll and execute hooks
- build sidebar panels using bpy.types.Panel
- register scene properties via PropertyGroup without global variables
Example prompts for the agent
- Create a Blender operator that randomizes vertex colors on the active mesh
- Build a 3D Viewport sidebar panel with a button to run my operator
- Write safe register and unregister functions for my custom property group
How to install blender-python-addon
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill blender-python-addon -a claude-code2Manually: put the files in place
~/.claude/skills/blender-python-addon/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/blender-python-addon/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill blender-python-addon -a codex2Manually: put the files in place
.agents/skills/blender-python-addon/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill blender-python-addon -a cursor2Manually: put the files in place
.cursor/skills/blender-python-addon/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Mindrally/skills blender-python-addon2Manually: put the files in place
.github/skills/blender-python-addon/SKILL.md1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill blender-python-addon -a gemini-cli2Platform CLI
gemini skills install https://github.com/Mindrally/skills --path blender-python-addonManually: put the files in place
.devin/skills/blender-python-addon/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Mindrally/skills --skill blender-python-addon -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about blender-python-addon
How to install blender-python-addon in Claude Code?
Run npx skills add Mindrally/skills --skill blender-python-addon -a claude-code or save the definition to ~/.claude/skills/blender-python-addon/SKILL.md.
What does blender-python-addon do?
It guides code generation for Blender extensions and add-ons, ensuring proper registration patterns, clean unregister loops, and correct bpy API calls.
How does Blender 4.2+ packaging differ from older releases?
Blender 4.2 and newer versions package extensions with blender_manifest.toml, while legacy releases define metadata inside the bl_info dictionary in __init__.py.
Source text
SKILL.md · Apache-2.0
---
name: blender-python-addon
description: "Best practices for writing Blender Python add-ons using the bpy API, covering operators, panels, properties, registration, and API-safe scripting. Use when creating a Blender add-on, defining bpy.types.Operator or Panel classes, registering PropertyGroup settings, writing register()/unregister() functions, working with bmesh, or debugging add-ons in Blender's Python console."
metadata:
maintainer: Mindrally
source: https://github.com/Mindrally/skills
---
# Blender Python Add-on Development
This skill covers building Blender add-ons with the `bpy` API, including add-on structure, operators, panels, properties, safe scene manipulation, and testing across Blender versions.
## Workflow for Building a Blender Add-on
1. **Scaffold the add-on** — Create a package with `__init__.py` as the entry point, and a `blender_manifest.toml` (Blender 4.2+ extensions) or `bl_info` dict (legacy add-ons) describing name, version, and supported Blender version.
2. **Define data** — Create `PropertyGroup` classes for grouped settings and register them on the appropriate ID type (e.g., `bpy.types.Scene.my_addon = PointerProperty(type=MyAddonSettings)`).
3. **Implement operators** — Subclass `bpy.types.Operator` for each user action; implement `poll()` for availability, `invoke()` for interactive setup, and `execute()` for the actual work.
4. **Build UI panels** — Subclass `bpy.types.Panel` to expose operators and properties in the appropriate editor (3D viewport sidebar, properties editor, etc.).
5. **Register everything** — List all classes in a `classes` tuple and register/unregister them in matching `register()`/`unregister()` functions; register property pointers alongside their classes.
6. **Test in a clean profile** — Launch Blender with `--factory-startup`, install the add-on, enable it, exercise each operator, then disable it and confirm nothing is left behind.
7. **Package and ship** — Zip the add-on folder (or build a `.zip` extension package) and verify it installs cleanly via Blender's Preferences > Add-ons (or Extensions) panel.
## Add-on Structure
- Keep the add-on's entry point in `__init__.py` with clear `register()` and `unregister()` functions that mirror each other exactly (everything registered must be unregistered, in reverse order).
- Group operators, panels, properties, preferences, and utility code into separate modules once the add-on grows past a trivial size; import and register them from `__init__.py`.
- Use `bl_info` (pre-4.2 legacy add-ons) or `blender_manifest.toml` (4.2+ extensions) matching the target Blender version and packaging model — don't mix conventions.
- Keep UI labels concise and use `bpy.app.translations` or the `"Category"`/label conventions so user-facing text can be localized where the project supports it.
## API Usage
- Use `bpy.types.Operator` for actions, `bpy.types.Panel` for UI layout, and `bpy.types.PropertyGroup` for grouped, related settings.
- Define `bl_idname` (lowercase, `category.action` format, e.g. `object.apply_custom_modifier`), `bl_label`, and `bl_options` (e.g., `{'REGISTER', 'UNDO'}`) explicitly on every operator.
- Validate context in `poll()` before allowing an operator to run — check for an active object, correct mode, or valid selection so the operator button greys out instead of erroring.
- Use `invoke()` for interactive setup (showing a dialog, reading mouse position) and `execute()` for the actual operation; `invoke()` should call `self.execute(context)` when it doesn't need extra interaction.
- Return `{'FINISHED'}` on success or `{'CANCELLED'}` on failure/user-abort consistently — never return a bare `None` or an unrecognized string.
- Use `bpy.context.evaluated_depsgraph_get()` and `object.evaluated_get(depsgraph)` when reading final scene state that includes modifiers, shape keys, or other dependency-graph-driven results.
### Example: Operator, Panel, and Registration
```python
bl_info = {
"name": "Random Vertex Color",
"author": "Example",
"version": (1, 0, 0),
"blender": (4, 0, 0),
"category": "Mesh",
}
import bpy
import random
class MESH_OT_random_vertex_color(bpy.types.Operator):
"""Assign a random color to the active vertex color layer"""
bl_idname = "mesh.random_vertex_color"
bl_label = "Randomize Vertex Colors"
bl_options = {"REGISTER", "UNDO"}
@classmethod
def poll(cls, context):
obj = context.active_object
return (
obj is not None
and obj.type == "MESH"
and obj.mode == "OBJECT"
and obj.data.color_attributes.active_color is not None
)
def execute(self, context):
obj = context.active_object
color_layer = obj.data.color_attributes.active_color
for data in color_layer.data:
data.color = (random.random(), random.random(), random.random(), 1.0)
obj.data.update()
self.report({"INFO"}, f"Randomized colors on '{obj.name}'")
return {"FINISHED"}
class VIEW3D_PT_random_vertex_color(bpy.types.Panel):
bl_label = "Vertex Color Tools"
bl_idname = "VIEW3D_PT_random_vertex_color"
bl_space_type = "VIEW_3D"
bl_region_type = "UI"
bl_category = "Tool"
def draw(self, context):
layout = self.layout
layout.operator(MESH_OT_random_vertex_color.bl_idname, icon="COLOR")
classes = (
MESH_OT_random_vertex_color,
VIEW3D_PT_random_vertex_color,
)
def register():
for cls in classes:
bpy.utils.register_class(cls)
def unregister():
for cls in reversed(classes):
bpy.utils.unregister_class(cls)
if __name__ == "__main__":
register()
```
## Data and Properties
- Register custom properties through `PropertyGroup` classes instead of stuffing loose global state into module-level variables, which don't survive file reload and aren't undo-safe.
- Store add-on preferences (API keys, default paths, UI toggles that persist across files) in an `AddonPreferences` subclass registered with `bl_idname` matching the add-on's module name.
- Use `PointerProperty`, `CollectionProperty`, and fully-typed properties (`StringProperty`, `FloatProperty`, `BoolProperty`, etc.) with explicit `name=` and `description=` so tooltips and the Python API are self-documenting.
- Clean up custom properties, `bpy.app.handlers` entries, timers, and keymaps during `unregister()` — anything added to a `bpy.types.*` class or a handler list must be explicitly removed.
## Safety and Performance
- Never run destructive scene operations (deleting objects, overwriting files) without explicit user action — no silent auto-execution on load for anything destructive.
- Avoid blocking the UI thread in modal operators; use `context.window_manager.event_timer_add()` with a modal state machine for long-running operations instead of a tight loop.
- Batch mesh edits and use the `bmesh` module (`bmesh.from_edit_mesh`, `bmesh.new()`) when programmatically editing mesh data instead of looping over `mesh.vertices` one at a time for structural changes.
- Avoid repeatedly scanning large scenes or recomputing expensive data inside `draw()` methods — `draw()` runs on every UI redraw, so cache results and invalidate them only when the underlying data changes.
- Keep file paths configurable and resolve them with Blender path utilities (`bpy.path.abspath`, `bpy.utils.resource_path`) instead of hardcoding OS-specific paths.
## Testing and Debugging
- Test in both a clean Blender profile (`blender --factory-startup`) to catch hidden dependencies on other add-ons, and in a representative production scene to catch performance and data-shape issues.
- Add smoke tests that import the add-on module, call `register()`, run each core operator via `bpy.ops`, then call `unregister()` cleanly with no errors or leftover state.
- Use `self.report({'ERROR'}, "message")` or `{'WARNING'}`/`{'INFO'}` for user-facing operator feedback instead of printing to the console, which most users never see.
- Keep version-specific API differences (e.g., API changes between Blender 3.x and 4.x) isolated behind small helper functions so the rest of the add-on doesn't need version checks scattered throughout.
## Common Mistakes
- Forgetting to unregister classes, handlers, timers, and keymaps in `unregister()`, leaving Blender in a broken state after disabling the add-on.
- Mutating Blender data (adding objects, changing mesh data) from inside a `Panel.draw()` method — `draw()` must only read data and lay out UI.
- Assuming an active object, a non-empty selection, or a specific mode (Object/Edit/Sculpt) exists without checking `context` first.
- Hardcoding absolute asset paths that only exist on the developer's machine instead of using relative paths or `bpy.utils.resource_path`.
© Mindrally · Apache-2.0 · Mindrally/skills