Blender MCP Quality Skill

Production-grade AI skill for 3D modeling, rigging, animation & rendering in Blender 5.1

Features • Quick Start • What's Inside • Usage • Contributing • License

🤔 The Problem

AI coding assistants can control Blender through the 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 deprecated action.fcurves but the AI still uses 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 | |---|---| | 🔍 Validation | Mandatory post-creation checks: poly count, manifold geometry, ground-plane snap, BVH intersection | | 📐 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 | | ⚠️ 24 Common Mistakes | Lookup table of errors and their fixes, all verified against 5.1 API docs |

🚀 Quick Start

Requirements: Blender 5.1 + 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:

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 — enforcement rule that tells the AI to always load the skill

Open the project folder in your AI coding assistant, connect to Blender via blender-mcp, and the skill is active.

📖 What's Inside

The skill file (SKILL.md) contains 12 sections (~900 lines) covering every aspect of Blender 5.1 scripting:

SKILL.md
├── 1.  Mandatory Post-Creation Validation Script
├── 2.  Polygon Budget Guidelines
├── 3.  Correct Blender 5.1 Python API Usage
├── 4.  Object Placement & Spatial Correctness
├── 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
└── 12. Common Mistakes to Avoid (24 entries)

🎮 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. ✅ Build the mesh within polygon budget
2. ✅ Place bones inside each mesh part
3. ✅ Apply auto-weights, then fix eyes/small parts manually
4. ✅ Animate using the Slotted Action API (not the deprecated pattern)
5. ✅ Set up lighting, camera, and render config with correct enums
6. ✅ Run the full validation script and report results

🔗 Related Projects

| Project | Description | |---|---| | blender-mcp | The MCP server that connects AI assistants to Blender | | Blender 5.1 Python API | Official API documentation | | Model Context Protocol | The protocol standard for AI tool integration |

🤝 Contributing

Contributions are welcome! If you'd like to help improve this skill, check out CONTRIBUTING.md for guidelines on reporting issues, submitting changes, and what we need help with.

📜 License

This project is licensed under the MIT License — use it, modify it, share it.