cc-blender-skill
Claude Code skill plugin: drive Blender 5.x like a senior 3D artist via natural language. 10 chain-loadable skills (modeling, materials, lighting, cameras, rendering, animation, export, wireframe-to-3d, pro-workflow). Validated on 6 scene classes.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/roble3-cc-blender-skill)HTML
<a href="/listings/roble3-cc-blender-skill"><img src="/api/listings/roble3-cc-blender-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites: Blender ≥ 4.0 with [BlenderMCP addon](https://github.com/ahujasid/blender-mcp) running on port 9876, Claude Code, Python 3.9+ with `opencv-python numpy scipy Pillow`.
git clone git@github.com:RobLe3/cc-blender-skill.git
cd cc-blender-skill
# Symlink all 30 skills into ~/.claude/skills/
for skill in plugin/skills/*/; do
name=$(basename "$skill")
ln -sfn "$(pwd)/$skill" "$HOME/.claude/skills/$name"
done
# Restart Claude Code to pick up the new top-level skills directory entries.Then ask Claude something like:
Make a 3D model of a teapot and render it with three-point lighting.
Or invoke a specific skill:
/wireframe-to-3d ./glasses_front.png
Full install + verification: [`plugin/README.md`](./plugin/README.md).
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 345 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # cc-blender-skill
- A portable agent skill pack that lets Codex, Claude Code, and compatible skill hosts use Blender like a senior 3D artist through natural language.
- **Version**: **1.4.0** ([CHANGELOG](./CHANGELOG.md)) · adds official-first dual MCP support and checked Unreal collision / Multires cage-export workflows. The existing 30-skill stack, legacy asset integrations, and source-locked validation gates remain. See the [integration test report](./docs/test-results/v1.4.0-integration.md) for verified behavior and known validation gaps.
- **Quick links**: [Install](#quick-install) · [What works (honestly)](#what-works-honestly) · [What doesn't](#what-doesnt-work-yet-honestly) · [Architecture](#architecture-in-one-paragraph) · [Contributing](.github/CONTRIBUTING.md) · [Releases](https://github.com/RobLe3/cc-blender-skill/releases)
- ---
- ## What this is
- Thirty chain-loadable skills turn requests like *"model a sword and render a hero shot with three-point lighting"* into Blender Python executed via either [official Blender Lab MCP](https://www.blender.org/lab/mcp-server/) or [ahujasid Blender MCP](https://github.com/ahujasid/blender-mcp). The shared skill content is agent-agnostic; installation and MCP configuration remain host-specific.
- ```
- User prompt
- ↓
- Agent detects intent → loads text-to-blender (orchestrator)
- ↓
- Orchestrator chain-loads relevant sub-skills
- ↓ ↓ ↓
- modeling, materials, lighting, cameras, rendering, animation, export, wireframe-to-3d, pro-workflow, reference-to-3d, UV/atlas fitting, validation, fit repair, look calibration
- ↓
- Generated Python → mcp__blender__execute_blender_code → Blender → output
- ```
- The plugin is the actual installable thing. It lives at [`plugin/`](./plugin/). Knowledge research that produced it lives at [`knowledge/`](./knowledge/) and [`docs/`](./docs/).
- ---
- ## What's new in v1.4.0
- - **Both MCP backends are supported.** Official Blender Lab MCP is preferred for shared capabilities; existing ahujasid installations still work. Tasks requiring its asset-download/generation tools use ahujasid from the start. The chosen backend stays fixed throughout the task.
- - **Official installation and validation are explicit.** Official MCP requires Blender 5.1+, its add-on and a separate MCP process. Render validation reads the returned file path, not an assumed destination. Existing legacy Blender 4.x caveats remain.
- - **Unreal collision export has a preflight.** Collider names, evaluated geometry, closedness, winding, convexity, primitive restrictions, and same-file selection are checked before the new static FBX route.
- - **Multires baking targets the exported cage.** Level 0 is set before baking and kept through export; temporary scene/context settings are restored afterward. Existing general export defaults are unchanged.
- These are additive integrations, not a claim that every Blender version or Unreal import has been validated. [Testing status and limitations](./docs/test-results/v1.4.0-integration.md).
- ### Thanks, and sorry for the slow response
- Thanks to **[fatalerrorist](https://github.com/fatalerrorist)** for
- [PR #1: official Blender MCP support](https://github.com/RobLe3/cc-blender-skill/pull/1),
- and **[NicoCaltha](https://github.com/NicoCaltha)** for
- [PR #2: Unreal collision meshes and Multires baking](https://github.com/RobLe3/cc-blender-skill/pull/2).
- Both contributions surfaced useful gaps and supplied concrete fixes.
- Sorry it took me a while to respond. I've been head-down in a gazillion other
- projects. I hope these updates make the skill more useful for everyone using it.
- ### v1.4.0 testing status and feedback wanted
- The release candidate has been exercised on Blender 5.1.1 through both MCP
- backends. All 30 skill folders pass Codex metadata validation; 6 host checks,
- 12 Blender export checks, and all 35 core recipe checks pass. Native Codex runs
- also covered skill discovery, materials, rendering, animation, GLB export, and
- checked collision FBX export. See the
- [full evidence and exact limits](./docs/test-results/v1.4.0-integration.md).
- The following still needs community testing:
- - Native **Claude Code** discovery, automatic routing, and explicit skill invocation
- - The complete 225-query trigger set and ten backend-routing scenarios in both clients
- - Unreal Engine import behavior for collision FBX and baked cage normals
- - Blender 4.x and versions newer than the tested Blender 5.1.1 environment
- - Legacy provider downloads/generation and a wider range of real production scenes
- Claude Code users are especially invited to try v1.4.0 and report what actually
- happens. Open a [bug report](https://github.com/RobLe3/cc-blender-skill/issues/new?template=bug_report.yml)
- or submit a PR. Include the agent/client version, Blender version, selected MCP
- backend and versions, installation scope, exact prompt, whether invocation was
- automatic or explicit, expected versus actual behavior, and sanitized logs or
- renders. Please remove credentials, private paths, and proprietary scene data.
- ---
- ## What's new in v1.3.0
- This release adds a generic self-refinement layer for cases where output quality is below expectation. Instead of blindly retrying, the stack now freezes the artifact, diagnoses the failure dimension, decides whether existing skills are sufficient, sanitizes the lesson into publishable generic guidance, validates the skill graph, and only then repairs the product.
- ### Added
- - `quality-refinement-autoloop` — a RALPH-style loop for subpar outputs, repeated failures, skill-gap diagnosis, sanitization, docs/version prep, and release handoff.
- - `closed-surface-uv-coverage` — a hard gate for closed/extruded assets so front caps, back caps, and sidewalls each have real surface coverage rather than overlay-only detail.
- - Animation/look motion skills: `texture-state-animation`, `orbital-hud-motion`, and `animation-quality-gate` for registered texture states, source-derived HUD motion, and contact-sheet QA.
- - Additional source-driven repair skills: `source-part-segmentation`, `texture-driven-mesh-fitting`, `landmark-fit-repair`, and `multiview-constraint-solver`.
- ### Changed
- - `blender-skill-harmonizer` now routes rejected/subpar outputs through the quality-refinement autoloop before further artifact work.
- - UV/texturing guidance now includes closed-surface front/back/side coverage validation.
- - README/plugin docs now describe the expanded 30-skill stack and the publishable self-refinement workflow.
- ---
- ## What's new in v1.2.9
- This release adds a generic, source-driven reconstruction layer on top of the existing natural-language Blender workflow. The important changes are:
- ### Added
- - `blender-skill-harmonizer` — a meta-orchestrator for multi-skill precedence, source-of-truth policy, handoff artifacts, and source-conflict gates.
- - `reference-to-3d` — a source-locked reconstruction workflow for templates, reference sheets, texture packs, and orthographic views.
- - `reference-analysis-validator` — source manifests, part-count gates, masks, overlays, IoU/SSIM/bbox/centroid validation, and fail-before-export checks.
- - `contour-to-mesh` and `orthographic-registration` — silhouette-first mesh construction plus front/side/back/top coordinate contracts.
- - `blender-uv-texturing` and `atlas-uv-fitting` — UV projection, atlas-region mapping, decals, lightmaps, and supplemental-map sanity checks.
- - `multiview-fit-loop` and `fit-repair-optimizer` — render/compare/adjust loops and dependency-aware repair queues.
- - `reference-look-calibration` — measurable source-image look matching for crop, brightness, saturation, hue, accent/glow, materials, lights, and render settings.
- - `mascot-logo-reconstruction` — generic brand mascot/logo orchestration driven by `reference_manifest.json`, not hardcoded project assumptions.
- ### Changed
- - Existing production skills now hand off to the reference-locked stack when the user provides source templates, texture packs, or repeated visual mismatch feedback.
- - The wireframe workflow now has a correction mode for source/texture-driven subjects instead of continuing primitive-first rebuilds.
- - Lighting, material, and rendering skills now defer source-image look matching to `reference-look-calibration` when exact visual match matters.
- - Examples and scripts were sanitized so structural counts, accent hues, guide masks, and validation gates are manifest/report-driven and reusable across projects.
- ---
- ## What works (honestly)
- | Capability | Status | Validation |
- |------------|--------|------------|
- | End-to-end scene build from natural language | ✅ Works first-try on most common subjects | 6 validated scene classes: sword, bottle, chair, aviator, desk lamp, broadcaster avatar |
- | Real-world dimension lookup | ✅ Reference covers 7 categories | swords, chairs, bottles, mugs, tables, lamps, eyewear, characters — `references/common-object-dimensions.md` |
- | Multi-skill chaining | ✅ Validated | wireframe-to-3d → modeling → materials → lighting → camera → render → export |
- | Blender 5.x compat | ⚠️ Bounded live checks on 5.1.1 | Both MCP routes pass all 35 core checks; broader 5.x coverage remains open |
- | Blender 4.x compat | ⚠️ Compat code present, not directly tested | See `plugin/skills/text-to-blender/references/blender-version-compat.md` |
- | Subject-class lighting (metal / glass / wood / fabric / skin / product) | ✅ Subject-aware profiles | Recipe 0a in `blender-lighting/SKILL.md` |
- | Emission material + practical lighting | ✅ Lamp scene validated | Recipe 11b in `blender-materials`, Recipe 0c in `blender-lighting` |
- | Volume-absorption coloured glass | ✅ 5 colour types tuned | Recipe 6b in `blender-materials/SKILL.md` |
- | Trigger-eval description tuning | ✅ 200 starter queries shipped | Each skill has `evals/evals.json`; aggregate 100% TP / 4% FP |
- | Wireframe-to-3d auto-extraction | ⚠️ Works for simple line-art; now has reference-locked correction handoff | Aviator validated; complex designed objects should use the reference-to-3d / contour / registration / validation stack |
- | Reference-locked reconstruction | ✅ Workflow added | Source manifest, contour-to-mesh, orthographic registration, multiview fit loop, repair queue, and overlay validation |
- | Texture-pack / atlas fitting | ✅ Workflow added | UV projection, per-region atlas mapping, alpha decals, supplemental-map sanity checks, lightmap handling |
- | Reference look calibration | ✅ Workflow added | Camera crop, brightness/saturation/hue, accent/glow masks, material/light/render handoff |
- | Skill harmonization | ✅ Workflow added | Meta-orchestrator defines precedence, handoff artifacts, source-conflict gates, and sequential/parallel repair lanes |
- ## What doesn't work yet (honestly)
- - **Design quality ≠ build correctness.** Plugin produces functionally correct objects. Aesthetic refinement (curved chair backs, profile-cut legs, consciously-composed silhouettes) is human-driven — out of scope for automatic generation.
- - **Human faces from primitives.** A sphere + nose + ears + mouth + brows reads as "abstract avatar," not "human." Real human faces require subtractive sculpting. v1.2.1 documents three escape paths: import via `download_polyhaven_asset` / `download_sketchfab_model` / `generate_hyper3d_model_via_text` (then chain), sculpt mode, or commission an artist (`docs/avatar-design-kit/prompts/04-blender-workflow.md`).
- - **Thin-metal specular flare.** Hero shots of thin metal (eyewear arms, jewellery) catch side lighting as bright streaks. Workaround: top-down softbox lighting or crop temple arms out of the frame.
- - **Subjective quality.** Numerical validation passing ≠ render looks right. The orchestrator's mandatory visual-validation checkpoint exists, but the user remains the final oracle.
- - **External user feedback.** Core validation is internal; the newer reference-locked stack still needs broader external examples, and real-use feedback drives v1.x patches.
- ---
- ## Quick install
- Prerequisites: a compatible skill host, a configured Blender MCP backend, and Blender. Official MCP requires Blender ≥5.1; the existing ahujasid route retains Blender ≥4.0 (4.x compatibility code is not live-tested here). Image-processing helpers need Python 3.9+ with `opencv-python numpy scipy Pillow`. See the [agent-host setup](./plugin/skills/text-to-blender/references/agent-hosts.md) and [backend setup](./plugin/skills/text-to-blender/references/mcp-backends.md); enabling an add-on alone is not enough.
- ```bash
- git clone git@github.com:RobLe3/cc-blender-skill.git
- cd cc-blender-skill
- # Codex personal install. Use .agents/skills in a project for project scope.
- mkdir -p "$HOME/.agents/skills"
- for skill in plugin/skills/*/; do
- name=$(basename "$skill")
- test ! -e "$HOME/.agents/skills/$name" && test ! -L "$HOME/.agents/skills/$name" || {
- echo "Refusing to replace $name" >&2; exit 1;
- }
- done
- for skill in plugin/skills/*/; do
- name=$(basename "$skill")
- ln -s "$(pwd)/$skill" "$HOME/.agents/skills/$name"
- done
- ```
- Claude Code installation and project-scoped examples are in the [agent-host guide](./plugin/skills/text-to-blender/references/agent-hosts.md).
- Then ask the agent something like:
- ```
- Make a 3D model of a teapot and render it with three-point lighting.
- ```
- Or invoke a specific skill:
- ```
- $wireframe-to-3d ./glasses_front.png
- ```
- Codex supports `$skill-name` and `/skills`; Claude Code uses its own explicit skill syntax.
- Full install + verification: [`plugin/README.md`](./plugin/README.md).
- ---
- ## Repository structure
- ```
- cc-blender-skill/
- ├── README.md # this file
- ├── CHANGELOG.md # release notes per version
- ├── VERSIONING.md # full per-version rationale
- ├── LICENSE # MIT
- ├── requirements.txt
- ├── .github/ # CONTRIBUTING + issue templates
- │
- ├── plugin/ # ← the installable skill plugin
- │ ├── README.md
- │ ├── manifest.json
- │ └── skills/
- │ ├── text-to-blender/ # orchestrator
- │ ├── blender-skill-harmonizer/ # multi-skill precedence + handoff contracts
- │ ├── quality-refinement-autoloop/ # RALPH-style quality loop + release prep
- │ ├── blender-pro-workflow/ # multi-phase guidance
- │ ├── blender-modeling/ # geometry creation
- │ ├── blender-materials/ # PBR via Principled BSDF
- │ ├── blender-lighting/ # 3-point, HDRI, studio
- │ ├── blender-cameras/ # framing, DoF, animated cameras
- │ ├── blender-rendering/ # Cycles/EEVEE
- │ ├── blender-animation/ # keyframes, F-curves, shape keys
- │ ├── blender-export/ # glTF/FBX/OBJ/USD/STL
- │ ├── wireframe-to-3d/ # specialty: 2D wireframe → 3D
- │ ├── reference-to-3d/ # source-locked reconstruction
- │ ├── reference-analysis-validator/ # masks, metrics, overlays
- │ ├── contour-to-mesh/ # contour-derived mesh generation
- │ ├── orthographic-registration/ # front/side/back/top coordinate contract
- │ ├── blender-uv-texturing/ # UV, projection, baking, lightmaps
- │ ├── atlas-uv-fitting/ # per-part atlas/decal mapping
- │ ├── closed-surface-uv-coverage/ # front/back/side surface coverage audits
- │ ├── mascot-logo-reconstruction/ # generic brand mascot/logo workflow
- │ ├── multiview-fit-loop/ # render/compare/adjust validation loop
- │ ├── fit-repair-optimizer/ # dependency-aware repair queues
- │ ├── reference-look-calibration/ # source-image look matching
- │ ├── source-part-segmentation/ # per-part source masks
- │ ├── texture-driven-mesh-fitting/ # mesh boundaries fit texture/source contours
- │ ├── landmark-fit-repair/ # named feature repair gates
- │ ├── texture-state-animation/ # layered registered texture motion
- │ ├── orbital-hud-motion/ # source-derived HUD/circle motion
- │ └── animation-quality-gate/ # contact-sheet animation QA
- │
- ├── knowledge/ # raw research aggregation (16 domains)
- │ ├── README.md
- │ ├── 01-modeling/00-overview.md
- │ ├── 02-curves-surfaces/00-overview.md
- │ ├── 03-sculpting-retopo/00-overview.md
- │ ├── 04-geometry-nodes/00-overview.md
- │ ├── 05-materials-shading/00-overview.md
- │ ├── 06-uv-texturing/00-overview.md
- │ ├── 07-lighting/00-overview.md
- │ ├── 08-cameras-composition/00-overview.md
- │ ├── 09-animation/00-overview.md
- │ ├── 10-rigging/00-overview.md
- │ ├── 11-rendering/00-overview.md
- │ ├── 12-compositing/00-overview.md
- │ ├── 13-physics-particles/00-overview.md
- │ ├── 14-import-export/00-overview.md
- │ ├── 15-cross-cutting/00-overview.md
- │ └── 16-pro-workflows/00-overview.md
- │
- ├── docs/ # documentation
- │ ├── SKILL_FOUNDATION.md # original research
- │ ├── BLENDER_BEST_PRACTICES.md
- │ ├── BLENDER_INTEGRATION_GUIDE.md
- │ ├── BLENDER_MCP_ALIGNMENT.md
- │ ├── WIREFRAME_SKILL.md
- │ ├── SKILL_RESEARCH_SUMMARY.md
- │ ├── process/ # dev journals (planning, tests, mcp coverage)
- │ │ ├── PLAN.md
- │ │ ├── DEVELOPMENT.md
- │ │ ├── TESTING_PLAN.md
- │ │ ├── IMPLEMENTATION_LOG.md
- │ │ ├── VERIFICATION_REPORT.md
- │ │ ├── MCP_COVERAGE_ASSESSMENT.md
- │ │ ├── BLENDER_TOOLKIT_COMPARISON.md
- │ │ └── INSTALL_BLENDER_MCP.md
- │ └── test-results/ # per-round eval logs
- │ ├── test.md # round 1: 30-test smoke
- │ ├── test_round2.md # round 2: scene-build feedback loop
- │ └── test_round3.md # round 3: trigger-eval self-assessment
- │
- ├── src/ # original wireframe analyzer (still used by skill)
- │ └── wireframe_analyzer.py
- │
- └── skill/ # initial single-skill prototype (now superseded by plugin/)
- └── wireframe-to-3d/
- ```
- ---
- ## Architecture in one paragraph
- Pure-skill design — no Python wrapper class, no custom MCP. The host agent reads the user's intent, loads the relevant skill files with its file-reading capability, generates Blender Python, calls the selected backend's `execute_blender_code`, checks response status and stdout, and reports results. Both backends use a separate MCP process connected to an add-on socket; their protocols and result shapes differ. State lives in `bpy.data` (Blender's global state, persists between calls); Python variables don't (each `execute_blender_code` is a fresh namespace, so we identify objects by stable name like `bpy.data.objects['GEO-sword']`). Naming follows Blender Studio conventions (`GEO-`, `MAT-`, `LGT-` prefixes). Host mappings are documented in [`agent-hosts.md`](./plugin/skills/text-to-blender/references/agent-hosts.md).
- ---
- ## Why this exists
- There are already two Claude+Blender skills:
- - **[ra100/blender-claude-plugin](https://github.com/ra100/blender-claude-plugin)** — 8 generalist Blender API reference skills (geometry nodes, shader nodes, compositor, etc.). Teaches Claude *how* Blender works.
- - **[Dev-GOM/blender-toolkit](https://mcpmarket.com/tools/skills/blender-toolkit)** — Mixamo retargeting via custom WebSocket addon.
- Neither tackles the **task-level orchestration**: "given a natural-language request, produce a finished 3D output." That's what this plugin does. It supports both official Blender Lab MCP and `ahujasid/blender-mcp`, and adds:
- - Pro-workflow sequencing (block-out → camera → lighting → forms → materials → detail → render → composite → export)
- - Recipe libraries per domain with copy-paste-ready Python
- - Decision trees mapped to natural-language intent
- - Naming and validation conventions throughout
- See [`docs/process/BLENDER_TOOLKIT_COMPARISON.md`](./docs/process/BLENDER_TOOLKIT_COMPARISON.md) for the full landscape comparison.
- ---
- ## Honest status
- The plugin shipped through **15+ versions of validation and patches** since the v0.3.0 scaffolding, then expanded with a generic reference-locked reconstruction stack for source/template/texture-driven work. Each version's commit summary in [`CHANGELOG.md`](./CHANGELOG.md) records concrete bugs found and fixed; each user-driven feedback iteration is in [`VERSIONING.md`](./VERSIONING.md) with the patch it produced. The proof renders in [`plugin/skills/text-to-blender/assets/v0.X.0-validation/`](./plugin/skills/text-to-blender/assets/) are honest evidence — no cherry-picking, including failure-state renders.
- The validation pattern is documented in [`docs/process/TESTING_PLAN.md`](./docs/process/TESTING_PLAN.md): cheap-Haiku tester runs deterministic tests + writes structured results, expensive-Opus patcher reads them and applies fixes. ~10× cheaper than running the full loop on a frontier model throughout. Three round logs live in [`docs/test-results/`](./docs/test-results/).
- ### What v1.2.9 adds
- - Generic `blender-skill-harmonizer` meta-layer for multi-skill precedence, source-of-truth policy, and handoff artifacts.
- - Source-locked reconstruction stack: `reference-to-3d`, `reference-analysis-validator`, `orthographic-registration`, `contour-to-mesh`, `multiview-fit-loop`, and `fit-repair-optimizer`.
- - Texture workflow expansion: `blender-uv-texturing` plus `atlas-uv-fitting` for texture packs, decals, UV regions, and supplemental map sanity checks.
- - `reference-look-calibration` for measurable source-image look matching after geometry/UV gates pass.
- - Generic mascot/logo workflow that derives structural counts and visual constraints from `reference_manifest.json` instead of hardcoded project assumptions.
- What v1.2.9 means here: **the stable core remains intact**, scope boundaries (design quality, human faces, thin-metal flare) are documented with escape paths, and the new reference-locked stack is generic, manifest-driven, and ready for broader examples. Real external use will surface edge cases that incremental v1.x patches will address.
- ---
- ## Contributing
- Open issues / PRs at https://github.com/RobLe3/cc-blender-skill — especially welcome:
- - Validation runs ("I tried prompt X, got error Y")
- - Recipe contributions for the long tail (specific materials, lighting setups, camera moves)
- - Trigger-eval JSON files for any sub-skill (helps tune description triggering)
- - Worked example scenes with proof-renders
- ---
- ## License
- MIT.
- ## Author
- [RobLe3](https://github.com/RobLe3) with extensive collaboration with Claude (Sonnet 4.6, Opus 4.7, Haiku 4.5).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.