blendops
AGENTS.md3 starsChanged 6 months agoMITView on GitHub
AI agents working inside this repository (modifying BlendOps itself, not consuming BlendOps) should follow this file. AI agents being asked to install/use BlendOps in another project should follow docs/ai-agent-quickstart.md instead. BlendOps is a portable AI-agent Skills pack for Blender, designed for users who don't know Blender. It is a content layer (SKILL.md-based docs + skills + laws + packs + bundles), not a runtime, not an installer, and not an MCP server. Read docs/README.md for the full hub. Read docs/runtime-stack-strategy.md…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository49 other files it gives its agents.
- acceptance-criteria-builderSkill
- asset-discoverySkill
- asset-fallback-strategySkill
- asset-library-planSkill
- asset-license-checkerSkill
- asset-style-checkSkill
- blender-brainstormingSkill
- blender-recipe-decomposerSkill
- blender-troubleshootingSkill
- blendops-helpSkill
- bridge-conflictsSkill
- camera-compositionSkill
- character-portraitSkill
- cli-appendix-job-outlineSkill
- color-management-decisionSkill
- composition-quality-checkerSkill
- cycles-vs-eevee-decisionSkill
- done-criteriaSkill
- environment-shotSkill
- glb-animation-handoffSkill
- glb-web-handoffSkill
- intent-to-3d-brief-writerSkill
- interior-sceneSkill
- lighting-material-planSkill
- lighting-quality-checkerSkill
- material-quality-checkerSkill
- mobile-glb-budgetSkill
- output-format-decisionSkill
- pack-prerequisite-checkerSkill
- path-one-host-outlineSkill
- plain-language-responseSkill
- polycount-budget-checkerSkill
- pre-handoff-verificationSkill
- preview-reportSkill
- product-grid-scene-plannerSkill
- product-hero-scene-plannerSkill
- r3f-component-planSkill
- recipe-fit-assessorSkill
- render-export-evidenceSkill
- resolution-aspect-decisionSkill
- runtime-attempt-reportSkill
- runtime-path-pickerSkill
- runtime-readinessSkill
- runtime-setupSkill
- scene-readinessSkill
- scope-guardSkill
- stage-gatesSkill
- <skill-name>Skill
- workflow-stage-routerSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Read docs/README.md for the full hub.
- Very specific: line 27
Every SKILL.md (other than skills/_template/SKILL.md) ships with only name and description keys — no version, status, or tags.
- Very specific: line 32
No claim of runtime success, mutation, render, export, GLB, preview, or "Verified" without an evidence file under docs/evals/.
- Very specific: line 37
Don't add a CLI, MCP server, or Blender add-on under any path that BlendOps "owns".
- Distinctive: line 100
Does not install Blender.
- Distinctive: line 101
Does not configure the Anthropic Blender Connector for the user.
- Distinctive: line 102
Does not configure the Blender Lab MCP add-on for the user.
- Very specific: line 103
Does not configure the community mcp-for-blender for the user.
- Very specific: line 104
Does not run Blender, render, export, or produce preview/render/GLB artifacts.
- Very specific: line 105
Does not ship a published npm package or npx installer.
- Distinctive: line 106
Does not have a marketplace listing.
- Very specific: line 108
If you find a doc claiming any of these, that's a bug — fix the doc honestly to mark it Not Run / Not Produced / Not Published.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
AI agents working inside this repository (modifying BlendOps itself, not consuming BlendOps) should follow this file. AI agents being asked to install/use BlendOps in another project should follow
docs/ai-agent-quickstart.mdinstead.
What this repo is
BlendOps is a portable AI-agent Skills pack for Blender, designed for users who don't know Blender. It is a content layer (SKILL.md-based docs + skills + laws + packs + bundles), not a runtime, not an installer, and not an MCP server.
Read docs/README.md for the full hub. Read docs/runtime-stack-strategy.md before saying anything about runtime.
Hard rules when editing this repo
These are enforced by scripts/check-docs.mjs (CI runs it on every PR).
- Runtime model = 2 MCP execution paths + CLI fallback appendix.
- Path 1 — Official Blender Lab MCP (Lab add-on + Lab server in Blender 5.1+; host = (a) Anthropic Connector OR (b) any other MCP client manually configured).
- Path 2 — Community
mcp-for-blender(Blender 3.0+). - CLI fallback (appendix) — direct
blender --background --python. Documented upstream as a first-class Blender CLI surface; no in-repo evidence file yet. - Do not describe Anthropic Connector as standalone. Anthropic's tutorial step 2 explicitly tells the user to install the Blender Lab MCP add-on inside Blender.
- Do not apply the Blender 5.1+ floor to Path 2 or to the CLI appendix. It is bound to the Lab add-on manifest, which only governs Path 1.
- Anthropic Skills frontmatter spec compliance.
- Every
SKILL.md(other thanskills/_template/SKILL.md) ships with onlynameanddescriptionkeys — noversion,status, ortags. name≤ 64 chars, lowercase letters/numbers/hyphens only.description≤ 200 chars (Claude.ai upload limit).
- Every
- Evidence before done.
- No claim of runtime success, mutation, render, export, GLB, preview, or "Verified" without an evidence file under
docs/evals/. - The 5 truth states are
Not Run,Attempted,Produced,Verified,Failed. Not Producedis the default for artifacts.
- No claim of runtime success, mutation, render, export, GLB, preview, or "Verified" without an evidence file under
- No BlendOps-owned runtime.
- Don't add a CLI, MCP server, or Blender add-on under any path that BlendOps "owns".
- Reference upstream (Anthropic, Blender Lab,
mcp-for-blender) only.
- No arbitrary Python as the user-facing surface.
- The runtime paths internally use LLM-generated Python (that's how
bpyworks) — that's fine. - The BlendOps product surface stays workflow + validation + evidence. Never recommend "paste this Python" as the final user output.
- The runtime paths internally use LLM-generated Python (that's how
- Plain language for non-Blender users.
- Final user-facing outputs explain status without Blender jargon. Add brief explanations for unavoidable terms.
Where to look
| Need | Doc |
| Hub (the everything index) | docs/README.md |
| Friendly first-read | docs/start-here.md |
| Runtime path model + history of corrections | docs/runtime-stack-strategy.md |
| Per-path setup walkthrough | docs/external-runtime-setup.md |
| 2-path runtime summary | docs/reference-runtime.md |
Path 2 caveats (community mcp-for-blender) | docs/unofficial-runtime-bridges.md |
| Universal install flow (Mode A/B/C) | docs/ai-agent-install-flow.md |
| Per-target install index (26 targets) | docs/install/README.md |
| Adapter index + registry | docs/adapters/README.md, docs/adapter-registry.md |
| Skill system architecture | docs/skill-system.md |
| Skills (48 total — 16 baseline + 32 expansion across Batches 1–8) | skills/README.md |
| Laws | laws/README.md |
| Packs | packs/README.md |
| Evals + readiness | docs/evals/README.md, docs/release-readiness.md |
| Roadmap + honest "Is BlendOps running yet?" | TODO.md |
Required pre-PR checks
npm run docs:check # ~344 active markdown files (see script footer count)
npm run skills:export # one ZIP + one Claude Code folder per skills/*/SKILL.md (currently 48)Or both at once:
npm run ciAdding new content
| Adding | See |
| A new skill | skills/README.md "How to add a new skill" + skills/_template/SKILL.md |
| A new law | laws/README.md |
| A new install target | docs/install/README.md (start as install doc → graduate to adapter via docs/adapter-registry.md promotion ladder) |
| A new adapter | docs/adapters/adapter-template.md |
| Runtime evidence | Template in docs/evals/blender-connector-read-only-smoke-test.md section "What a clean re-verification would record" |
What this repo does NOT do
- Does not install Blender.
- Does not configure the Anthropic Blender Connector for the user.
- Does not configure the Blender Lab MCP add-on for the user.
- Does not configure the community
mcp-for-blenderfor the user. - Does not run Blender, render, export, or produce preview/render/GLB artifacts.
- Does not ship a published
npmpackage ornpxinstaller. - Does not have a marketplace listing.
If you find a doc claiming any of these, that's a bug — fix the doc honestly to mark it Not Run / Not Produced / Not Published.
License
MIT. See LICENSE.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.