Content
<div align="center">
<img src="assets/logo.png" alt="Blender MCP Quality Skill" width="200"/>
# Blender MCP Quality Skill
**Production-grade AI skill for 3D modeling, rigging, animation & rendering in Blender 5.1**
[](https://www.blender.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](CONTRIBUTING.md)
[Features](#-features) • [Quick Start](#-quick-start) • [What's Inside](#-whats-inside) • [Usage](#-usage) • [Contributing](#-contributing) • [License](#-license)
</div>
---
## The Problem
AI coding assistants can control Blender through the [blender-mcp](https://github.com/ahujasid/blender-mcp) MCP server — but they frequently produce broken output:
- **Floating body parts** — auto-weights fail silently on multi-part characters
- **Silent animation failures** — Blender 5.1 uses layered/slotted Actions; direct `Action.fcurves` is a legacy path, but assistants still use it
- **Exploding polygon counts** — UV Spheres with 128 segments (16,384 faces!)
- **Objects below ground** — no spatial validation
- **Wrong API calls** — `BLENDER_EEVEE_NEXT` doesn't exist, `calc_normals()` was removed
This skill teaches the AI to do it right — **every time**.
---
## Features
| Category | What the skill enforces |
|---|---|
| **Planning** | Pre-modeling anatomy inventory, proportion estimation, build order, single-step discipline |
| **Validation** | Mandatory post-creation checks: poly count, manifold geometry, ground-plane snap, BVH intersection, contact/gap verification |
| **Polygon Budgets** | Per-object-type limits with correct primitive settings |
| **Rigging** | Bone placement rules, auto-weight cleanup for small parts (eyes, buttons), floating-part detection |
| **Animation** | Blender 5.1 Slotted Action API (`Action→Layer→Strip→Channelbag→FCurves`), reusable helper functions |
| **Materials** | Principled BSDF patterns, color space rules, shading modes |
| **Lighting** | Three-point lighting setup, all light type configurations |
| **Camera** | Setup with TRACK_TO constraints, turntable animation, Follow Path for vehicles |
| **Modifiers** | Correct type enums, application order, pre-rigging workflow |
| **Rendering** | Verified EEVEE/Cycles settings, FFMPEG output configuration |
| **Inspection** | Six-side structured inspection protocol, close-up contact views, connection proofs |
| **30 Common Mistakes** | Lookup table of errors and their fixes, all verified against 5.1 API docs |
| **Domain Patterns** | Failure tables for characters, vehicles, buildings, and mechanical/industrial assets |
---
## Quick Start
**Requirements:** [Blender 5.1](https://www.blender.org/download/) + [blender-mcp](https://github.com/ahujasid/blender-mcp) MCP server + any AI coding assistant that supports MCP (OpenCode, Google Antigravity, Codex, Claude Code, Cursor, etc.)
### Installation
This repository is structured as a ready-to-use project. Clone it and start working:
```bash
git clone https://github.com/Mik1703/blender-mcp-quality.git
cd blender-mcp-quality
```
That's it. The repo already includes:
- `.agents/skills/blender-mcp-quality/SKILL.md` — the skill file the AI reads automatically
- `AGENTS.md` — project rule file for agents that support AGENTS.md-style conventions
Open the project folder in your AI coding assistant, connect to Blender via [blender-mcp](https://github.com/ahujasid/blender-mcp), and the skill is active.
---
## What's Inside
The skill file (`SKILL.md`) contains **14 sections** (~1,150 lines) covering every aspect of Blender 5.1 scripting:
```
SKILL.md
0. Pre-Modeling Planning (anatomy, proportions, build order)
1. Mandatory Post-Creation Validation Script
2. Polygon Budget Guidelines
3. Correct Blender 5.1 Python API Usage
4. Object Placement & Spatial Correctness (with contact/gap verification)
5. Materials & Shading
6. Lighting & Camera Setup
7. Modifiers
8. Armature & Rigging (with weight cleanup)
9. Animation (Slotted Action API)
10. Render Settings
11. Post-Completion Workflow (with six-side inspection protocol)
12. Common Mistakes to Avoid (30 entries)
13. Common Failure Patterns by Domain
```
---
## Usage
Once installed, the AI will automatically follow the skill whenever it interacts with Blender. Here's an example prompt you can try:
> Clear the scene. Create a low-poly cartoon robot character — box body, cylinder arms and legs, sphere head with eyes. Keep it under 3,000 polygons. Give it an armature with proper bone hierarchy. Create a 24-frame walk cycle. Add three-point lighting and a tracking camera. Apply colorful cartoon materials. Render settings at 1080p 24fps EEVEE.
The AI will:
1. **Plan** the anatomy, proportions, and build order before touching Blender
2. Build the mesh within polygon budget
3. Place bones **inside** each mesh part
4. Apply auto-weights, then **fix eyes/small parts manually**
5. Animate using the **Slotted Action API** (not the deprecated pattern)
6. Set up lighting, camera, and render config with correct enums
7. Run the **full validation script** and report results
8. **Inspect** from six sides to catch hidden defects
---
## Related Projects
| Project | Description |
|---|---|
| [blender-mcp](https://github.com/ahujasid/blender-mcp) | The MCP server that connects AI assistants to Blender |
| [Blender 5.1 Python API](https://docs.blender.org/api/5.1/) | Official API documentation |
| [Model Context Protocol](https://modelcontextprotocol.io/) | The protocol standard for AI tool integration |
---
## Contributing
Contributions are welcome! If you'd like to help improve this skill, check out [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting issues, submitting changes, and what we need help with.
---
## License
This project is licensed under the [MIT License](LICENSE) — use it, modify it, share it.
---
<div align="center">
Star this repo if it helped your Blender AI workflow!
</div>
