Skip to content

feat(skills): extension-runtime-and-packaging skill, snippet and example - #445

Merged
TMHSDigital merged 1 commit into
mainfrom
feat/extension-runtime-skill
Oct 5, 2026
Merged

TMHSDigital merged 1 commit into
mainfrom
feat/extension-runtime-skill

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Closes #380.

What ships

  • Skill extension-runtime-and-packaging covers what breaks an extension after its first run:
    • bundled wheels instead of pip;
    • user data in extension_path_user instead of beside __file__;
    • the network permission plus bpy.app.online_access;
    • bl_ext.<repo>.<id> package names;
    • blender --command extension validate / build / server-generate in CI.
  • Snippet snippets/extension-user-data.py: a settings file in the extension's user directory, plus an online_access guard.
  • Check-only example examples/extension-package-lifecycle: builds, lists, installs, upgrades (0.1.0 → 0.2.0) and removes the repo's extension template. Every step runs in a throwaway BLENDER_USER_RESOURCES. Falsifiers: --validate-only (exit 4) and --data-next-to-file (exit 7).
  • Wiring: catalog row; examples/skills.json entry (→ this skill and headless-batch-scripting); Cursor manifest; counts (17 skills, 28 snippets, 65 examples, 9 check-only).
  • Generator fix: build_examples_index.py now unquotes a stripped link whose text is a path. This example's README lead made check_skill_refs fail on a bare templates/... path in the generated section.

Measured facts the skill relies on

All on local 4.5.11 LTS, 5.1.2 and 5.2.1 LTS, unless a row says otherwise:

Fact Result
validate / build with a wheels entry whose file is missing 0 / 1 (no zip) on all three: validate is not a release gate
validate with platforms = ["win64"], or schema_version = "9.9.9" 0 (4.5.11 and 5.2.1)
validate with no id, version = "one", type = "plugin", permission teleport, blender_version_min = "4" 1 (4.5.11 and 5.2.1)
Installed __package__ bl_ext.user_default.example_addon
extension_path_user(__package__) extensions/.user/user_default/example_addon, beside the install tree
extension_path_user("probe_ext") (a bare name) ValueError: The "package" does not name an extension (4.5.11 and 5.2.1)
Upgrade 0.1.0 → 0.2.0 Install tree replaced (a file written beside __file__ is gone); user data kept
extension remove Deletes the user directory too
Bundled wheel (hand-built py3-none-any) Lands in extensions/.local/lib/python3.11/site-packages (4.5.11) or python3.13 (5.2.1), already on sys.path
bpy.app.online_access False by default, True under --online-mode

Evidence

Live run: tests/smoke/run_catalog.py over the new row; all PASS.

Binary reports Happy path --validate-only --data-next-to-file
Blender 4.5.11 LTS PASS PASS (exit 4) PASS (exit 7)
Blender 5.1.2 PASS PASS (exit 4) PASS (exit 7)
Blender 5.2.1 LTS PASS PASS (exit 4) PASS (exit 7)

Local checks: tests/run_all.py 31 passed, 0 failed (counts, frontmatter, skill refs, examples index, exit-code README, catalog).

Inspection only:

  • The pip download … --python-version 3.11 --platform win_amd64 line follows the Blender manual's wheels page; it was not run here.
  • --split-platforms is described from extension build --help and the manual; it was not run.

The example starts about a dozen child Blenders, so expect it to be one of the slower smoke rows.

🤖 Generated with Claude Code

Nothing covered what breaks an extension after its first run. New skill
extension-runtime-and-packaging covers:
- bundled wheels instead of pip, matched to Python 3.11 (4.5) and 3.13 (5.2)
- user data in bpy.utils.extension_path_user, never beside __file__
- the network permission plus bpy.app.online_access
- bl_ext package names and relative imports
- blender --command extension validate/build/server-generate in CI

Every claim is measured on 4.5.11, 5.1.2 and 5.2.1 in a throwaway
BLENDER_USER_RESOURCES:
- validate passes a manifest whose wheel file is missing (also an
  unknown platform name and schema_version 9.9.9); only build fails it.
- An upgrade replaces the install tree but keeps extensions/.user/...;
  extension remove deletes it.
- extension_path_user raises ValueError for a non-bl_ext package.
- Wheels land in extensions/.local/lib/pythonX.Y/site-packages, which
  is already on sys.path.

New snippet snippets/extension-user-data.py, and new check-only example
examples/extension-package-lifecycle. The example builds, lists,
installs, upgrades and removes the repo's extension template, with
falsifiers --validate-only (exit 4) and --data-next-to-file (exit 7).
Counts move to 17 skills, 28 snippets and 65 examples (9 check-only).

The example maps to the new skill and headless-batch-scripting in
examples/skills.json. build_examples_index.py now drops the backticks
from a stripped link whose text is a path, so a README lead such as
[`templates/...`](...) no longer leaves a bare repo path in a skill.

Closes #380

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added skills snippets examples Runnable smoke-gated examples under examples/ documentation Improvements or additions to documentation labels Oct 5, 2026
@TMHSDigital

Copy link
Copy Markdown
Owner Author

CI evidence before merge: all checks pass ( 13 pass ). Blender Smoke on PR head: Blender 5.2.2 LTS / Blender 4.5.14 LTS. Summaries (happy path; falsifiers) per leg: 144 passed, 1 skipped, 0 failed;164 passed, 0 skipped, 0 failed;142 passed, 3 skipped, 0 failed;149 passed, 15 skipped, 0 failed;

@TMHSDigital
TMHSDigital merged commit d2cb9e9 into main Oct 5, 2026
13 checks passed
@TMHSDigital
TMHSDigital deleted the feat/extension-runtime-skill branch October 5, 2026 03:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation examples Runnable smoke-gated examples under examples/ skills snippets

Projects

None yet

Development

Successfully merging this pull request may close these issues.

skills: new extension-runtime-and-packaging skill (wheels, extension_path_user, online_access, extension build/validate)

1 participant