Imported from TMHSDigital/Blender-Developer-Tools (AGENTS.md). Install upstream with npx skills add TMHSDigital/Blender-Developer-Tools. Copyright stays with the author.

AGENTS.md

Guidance for AI coding agents working on the Blender Developer Tools repository.

Division of labor: this file carries fleet-standard governance and workflow rules — branching, commits, merge and CI-evidence policy, release automation, authoring standards. CLAUDE.md carries repo-specific operational facts an agent needs at runtime — content inventory, Blender runtime discovery, git staging hazards, and the example-shipping quality gates. Read both; neither repeats the other.

Repository overview

Skills, rules, snippets, starter templates, and runnable smoke-gated examples for Blender Python development. The repo targets Blender 5.2 LTS (current stable) with a Blender 4.5 LTS fallback. Blender 5.1 is prior stable. There is no MCP server. It ships a .cursor-plugin/plugin.json manifest so the ecosystem drift checker classifies it as a cursor-plugin. This is content the AI loads when the user asks Blender questions or works on Blender add-ons in Cursor or Claude Code.

The content base is 16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 26 showcase pieces (counts are CI-enforced against README.md) and the manifest). The full inventory tables and per-item purposes live in CLAUDE.md. Example anatomy and authoring rules: copy examples/bmesh-gear/; showcase conventions: showcase/README.md. The render look is specified in docs/VISUAL-STYLE.md; the canonical run prompt is docs/new-example-prompt.md.

Repository structure

Blender-Developer-Tools/
  skills/<skill-name>/SKILL.md   # 16 skill files
  rules/<rule-name>.mdc          # 9 rule files
  templates/<template-name>/     # 3 starter templates
  snippets/<snippet-name>.py     # 27 standalone Python snippets
  examples/<name>/               # 59 runnable smoke-gated examples (+ gallery.json)
  examples/gallery_framing.py    # shared Layer 1 framing measurement (render path only)
  showcase/<name>/               # budget-conformance props (sibling of examples/)
  showcase/gallery.json          # this tree's gallery index; merged into docs/gallery/
  scripts/build_gallery.py       # generates docs/gallery/ (stdlib only)
  scripts/site/                  # vendored landing-page build (build_site.py + template)
  docs/gallery/                  # committed generated gallery pages + hero assets
  docs/new-example-prompt.md     # canonical example-creation prompt
  .github/workflows/             # validate, blender-smoke, drift-check, release, pages, label-sync, stale
  .github/dependabot.yml
  AGENTS.md, CLAUDE.md, README.md, ROADMAP.md, CHANGELOG.md
  CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
  VERSION                        # source of truth for the repo version
  LICENSE                        # CC-BY-NC-ND-4.0

Branching and commit model

Single main branch. No develop or release branches. Work on a focused feature branch off an up-to-date main. Never force-push or bypass hooks.
Conventional commits drive the auto-release workflow. It scans the commit subjects since the last tag and releases only when at least one is release-worthy:
- feat: triggers a minor bump
- fix: triggers a patch bump
- feat!: / fix!: / BREAKING CHANGE triggers a major bump
- Other types (chore:, docs:, ci:, refactor:, etc.) do not cut a release: the workflow runs, decides there is nothing to release, and exits without a tag or version bump. A mixed push still releases if any commit in range is a feat:/fix:.
- [skip ci] in the head commit still bypasses the workflow entirely. With the commit-type gate above it is now an optional override, not a requirement for non-release commits.
Commit messages should describe the why, not the what, and carry a DCO Signed-off-by: trailer matching the commit author (see CONTRIBUTING.md).
Stage with explicit paths only — never git add -A or git add .. The reason is a repo-specific hazard documented in CLAUDE.md § Git staging.

Merge policy and CI evidence

Squash-merge with branch deletion is the standard. The PR becomes one commit on main; delete the remote feature branch after merge, then fast-forward local main.
Smoke jobs do not re-run on the merge SHA. blender-smoke.yml triggers on pull_request (plus a weekly schedule and manual dispatch) — there is no push trigger. The correct post-merge evidence for example changes is: both Blender smoke jobs (5.2 LTS and 4.5 LTS) passed on the PR head SHA that became the sole squash-merged commit, with the actual binary versions confirmed in the job logs.
Post-merge, verify green on main: Release (release.yml), Validate (validate.yml), Ecosystem drift check (drift-check.yml), and Deploy GitHub Pages (pages.yml; paths-filtered, so it does not trigger for every change).
Socket Security checks ("Socket Security: Project Report" and "Socket Security: Pull Request Alerts") run on PRs via the Socket GitHub App. No override policy has been decided: a pending or failing Socket check is unresolved — wait before merging.
Release-owned fields are never hand-edited: VERSION, CHANGELOG.md, the CLAUDE.md **Version:** line, the ROADMAP.md **Current:** line, and the manifest "version" in .cursor-plugin/plugin.json. Generated gallery pages under docs/gallery/ are regenerated via scripts/build_gallery.py, never hand-edited.
Evidence over assertion: PR bodies must label what was proven by live run versus established by inspection only.

Blender version targeting

Primary: Blender 5.2 LTS (current stable). All examples assume 5.2 unless otherwise stated.
Prior stable: Blender 5.1. Skills document 5.1-only contracts where they still matter; weekly smoke keeps a 5.1 leg.
Fallback: Blender 4.5 LTS. Skills and the extension template note 4.5 compatibility where it matters (slotted actions bridge, property delete, manifest fields, NodesModifier dict inputs).

When a 4.x and 5.x API genuinely diverge, skills must show both code paths, not just the 5.x one. The slotted-actions-animation skill is the load-bearing example. Local binary discovery and version-reporting rules are in CLAUDE.md § Blender runtime discovery.

Skills

Each skill lives at skills/<skill-name>/SKILL.md. Frontmatter is YAML:

---
name: <kebab-case-skill-name>
description: <one-line, under 200 chars>
standards-version: 1.10.0
---

name must match the directory name. description is what the AI sees when deciding whether to load the skill.

Skills should cite Blender API doc URLs where they reference specific RNA classes, operators, or modules. Avoid encyclopedic API tours; the goal is the canonical pattern plus the common AI mistakes.

Rules

Rules are .mdc files in rules/. Frontmatter:

---
description: <one-line>
alwaysApply: true
standards-version: 1.10.0
---

Rules encode anti-patterns. Each rule should show the wrong way, the right way, and a one-paragraph rationale. 30 to 80 lines is the right size.

CI/CD workflows

validate.yml runs file structure checks plus a validate-counts job that asserts the README aggregate counts (skills, rules, templates, snippets, and examples) match filesystem reality. The counts language in README.md is load-bearing: the job greps for it.
validate.yml also runs a validate-manifest job that checks .cursor-plugin/plugin.json against reality: every listed path must exist, every skill, rule, snippet, template, and example on disk must be listed, and the manifest version must equal VERSION. The release pipeline owns the manifest version line (see release.yml below) — never hand-edit it.
blender-smoke.yml executes every shipped example (check-only, no render) plus snippet/template smoke tests inside REAL headless Blender, on 5.2 LTS and 4.5 LTS for every PR. 5.1 is weekly cron, the opt-in needs-5.1 PR label (pull_request types include labeled), or workflow_dispatch with a series input. Auto-label does not apply needs-5.1. Contributor-facing notes for the smoke lever, the deliberate lack of a push trigger, Pages path filters, and the three-role exit-code convention live in CONTRIBUTING.md. Examples run through tests/smoke/run_example.py (catalog: tests/smoke/catalog.json). SKIP is exit 77 plus a SMOKE_SKIP: reason, and only when --min-version is above this Blender; exit 0 with that marker is a vacuous pass and fails. Post-exit sidecars are opt-in (--expect-sidecar). A leg with zero PASSes is red. A new example is not shipped until it has a catalog row.
drift-check.yml consumes Developer-Tools-Directory/.github/actions/ drift-check@v1.15 to enforce ecosystem standards-version markers.
release.yml auto-bumps the version, tags, force-updates floating tags v0 and v0.1, and runs release-doc-sync@v1 to rewrite CHANGELOG.md, CLAUDE.md **Version:**, and ROADMAP.md **Current:**. It also rewrites the "version" line in .cursor-plugin/plugin.json so the manifest tracks each release. Triggered on push to main for content-changing paths only.
label-sync.yml self-heals labels via gh label create --force per label, then applies them to the PR.
pages.yml builds the landing page from the locally vendored template at scripts/site/ (originally scaffolded from Developer-Tools-Directory's site-template, now owned by this repo — the fleet template only scaffolds new tools) plus the examples gallery via scripts/build_gallery.py, then deploys docs/. docs/index.html, docs/fonts/, and docs/assets/ are build outputs and gitignored; docs/gallery/ is committed.

Where to look for canonical references

Blender 5.2 LTS Python API: https://docs.blender.org/api/current/
Blender 5.1 Python API: https://docs.blender.org/api/5.1/
Blender 4.5 LTS Python API: https://docs.blender.org/api/4.5/
Extensions Platform reference: https://docs.blender.org/manual/en/latest/advanced/extensions/index.html
Release notes (developer.blender.org): https://developer.blender.org/
Live MCP session vs headless harness policy: CLAUDE.md § "Live MCP vs Headless Harness" — headless is the only source of truth for evidence.

When information conflicts, prefer the docs over Stack Overflow or older add-on source. The 2.x to 4.x to 5.x churn around Actions, Extensions, and property handling has invalidated a lot of community content.

License

CC-BY-NC-ND-4.0. See LICENSE.

Blender-Developer-Tools

About