blender-add-on-development

Develop, debug, and upgrade Blender add-ons/plugins and `bpy` scripts with Blender 4.x and 5.x compatibility. Use when tasks involve generating new add-on co...

Security Scan

The skill's code, instructions, and requirements match its stated purpose (scaffolding and advising on Blender add-ons); it does not request unrelated credentials, install arbitrary software, or contact external endpoints.

Purpose & Capability

Name/description (Blender add-on development) align with the included files and instructions: scaffolding script, compatibility references, and guidance for Blender 4.x/5.x. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md instructs the agent to read local references, generate code with scripts/scaffold_addon.py, run py_compile, and optionally run local Blender headless smoke tests if Blender is present. It does not instruct reading arbitrary system files, exfiltrating data, or calling external endpoints.

Install Mechanism

No install spec is present (instruction-only plus a local scaffold script). Nothing is downloaded or extracted from external URLs, so there is no install-time code injection risk.

Credentials

The skill requests no environment variables or credentials. The only runtime dependency it mentions is an optional local Blender binary (used only for optional smoke tests), which is appropriate for the stated purpose.

Persistence & Privilege

always is false and the skill does not request persistent system-wide changes or modify other skills. It only writes files to a user-specified output directory when the scaffold script is run.

Assessment

This skill appears coherent and safe for its purpose, but follow normal caution: review any generated add-on code before installing it into Blender, choose the output directory deliberately (the scaffold writes files there and may overwrite with --force), and only run Blender smoke tests using a Blender binary you control. The agent may invoke this skill autonomously (platform default) — that is expected, but if you want to restrict autonomous runs, disable model invocation in the agent settings. If you need higher assurance, run the scaffold script and any tests inside an isolated environment or temporary project folder first.

Blender Plugin Development

Quick Start

1. Confirm target Blender versions (minimum and maximum expected).
2. Read references/blender4_to_5_compat.md before writing or patching code.
3. Scaffold a new add-on package with scripts/scaffold_addon.py when requested.
4. Implement requested behavior with explicit compatibility guards for 4.x and 5.x.
5. Validate syntax and registration flow before returning code.

Workflow

1) Scope the task

• Extract target behavior, UI location, operator names, and data model.
• Ask for Blender version range if unspecified; default to >= 4.0 with 5.x awareness.
• Decide whether output should be:
  • A full add-on package.
  • A standalone bpy script.
  • A migration patch to existing code.

2) Generate a baseline when creating a new add-on

• Run:
  • python3 scripts/scaffold_addon.py --name "<Addon Name>" --output <target-dir>
• Customize generated __init__.py, operators.py, ui.py, and compat.py for the feature request.
• Keep bl_info["blender"] at the minimum supported version (for this skill, usually (4, 0, 0) or higher).

3) Implement compatibility-safe code

• Use bpy.app.version gates only when behavior truly diverges.
• Prefer compatibility wrappers in compat.py over scattered version checks.
• Avoid APIs called out as removed/deprecated in references/blender4_to_5_compat.md.
• For operator context overrides, use context.temp_override(...).
• For assets, prefer context.asset and AssetRepresentation.
• For GPU drawing in 5.x, avoid bgl and migrate to gpu.

4) Validate before returning code

• Run python3 -m py_compile on changed Python files.
• If Blender binaries are available, run headless smoke tests:
  • blender --background --factory-startup --python <smoke_test.py>
• Check register/unregister order and operator bl_idname format.
• Confirm no removed API names remain in generated output.

Script Generation Patterns

• Generate small, composable files:
  • operators.py for operators.
  • ui.py for panels/menus.
  • compat.py for version shims.
  • __init__.py for bl_info and registration entrypoints.
• Use idempotent register/unregister functions.
• Keep class lists explicit (tuple of classes) and unregister in reverse order.
• Report actionable failures with self.report({"ERROR"}, "...") inside operators.
• Avoid hard-coded context assumptions in poll() and execute().

Required Compatibility Rules

• Avoid dict-like access for runtime-defined RNA properties in 5.0 when accessing add-on-defined data; use supported property access patterns documented in Blender 5.0 release notes.
• Never depend on bundled private modules listed in Blender 5.0 notes (for example, bl_ui_utils, rna_info).
• Treat scene.use_nodes as deprecated and avoid using it for new code.
• Avoid UILayout.template_asset_view() in new code; use asset-shelf-compatible APIs.
• Keep code ready for Blender 6.0 removals by addressing documented 5.0 deprecations proactively.

Resources (optional)

scripts/

• scripts/scaffold_addon.py: Generate a Blender 4/5-ready add-on package skeleton.

references/

• references/blender4_to_5_compat.md: Blender 4.0 and 5.0 compatibility map with official sources.
• references/script_generation_patterns.md: Reusable patterns for operators, panels, and background scripts.