feat(distribution): plugin ships the rules as a skill; skill file refs work outside a checkout

After #289 the plugin installed the skills, but the rules needed a second,
hand-maintained clone imported from CLAUDE.md, and 7 skills pointed at
repo-root paths (`snippets/...`, `examples/...`) that Claude resolves against
the user's project, where they do not exist. The rules summary promised links
that were plain text.

- scripts/build_claude_rules.py now also writes
  claude/skills/blender-rules/SKILL.md (name + trigger description; same body
  as claude/blender-rules.md), and every "Full rule:" is an absolute GitHub
  link. --check covers both outputs.
- .claude-plugin/plugin.json "skills": ["./claude/skills/"]; per the plugin
  manifest reference this adds to the default skills/ scan. Kept outside
  skills/ so the 16-skill inventory and Cursor manifest are unchanged.
- 38 bare repo paths in 7 SKILL.md files became absolute GitHub links
  (blob for files, tree for directories), each verified to exist.
- tests/check_skill_refs.py (in validate-claude-packaging): no bare repo
  path in skills or the rules summaries, and every repo link resolves.
  Falsified: the pre-change ai-mesh-cleanup skill reports its bare
  `examples/...` paths.
- validate-claude-packaging checks the plugin.json skills entries exist and
  validates SKILL.md frontmatter in every declared skills dir.
- README Quick start / Cursor section and the landing install step: the rules
  arrive with the plugin as the blender-rules skill; the CLAUDE.md import is
  now the optional always-on path.

Closes #334

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.claude-plugin/plugin.json

@@ -9,6 +9,9 @@
   "homepage": "https://github.com/TMHSDigital/Blender-Developer-Tools",
   "repository": "https://github.com/TMHSDigital/Blender-Developer-Tools",
   "license": "CC-BY-NC-ND-4.0 AND MIT",
+  "skills": [
+    "./claude/skills/"
+  ],
   "keywords": [
     "claude-code",
     "blender",

.github/workflows/validate.yml

@@ -245,8 +245,19 @@ jobs:
           elif not os.path.isdir(os.path.join(entries[0].get('source', ''), 'skills')):
               errors.append('marketplace.json source must point at a directory containing skills/')
 
-          # Claude Code discovers skills/<name>/SKILL.md; each needs name + description.
-          for path in sorted(glob.glob('skills/*/SKILL.md')):
+          # Claude Code discovers skills/<name>/SKILL.md plus every extra
+          # directory in plugin.json "skills" (the generated blender-rules
+          # skill); each SKILL.md needs name + description.
+          extra = plugin.get('skills', [])
+          skill_dirs = ['skills']
+          for d in extra:
+              if not (isinstance(d, str) and d.startswith('./') and os.path.isdir(d)):
+                  errors.append(f'plugin.json skills entry {d!r} must be an existing ./ directory')
+              else:
+                  skill_dirs.append(d)
+          if './claude/skills/' not in extra:
+              errors.append('plugin.json skills must include ./claude/skills/ (the rules skill)')
+          for path in sorted(p for d in skill_dirs for p in glob.glob(os.path.join(d, '*', 'SKILL.md'))):
               parts = open(path, encoding='utf-8').read().replace('\r\n', '\n').split('---')
               front = parts[1] if len(parts) > 2 else ''
               for key in ('name:', 'description:'):
@@ -277,9 +288,12 @@ jobs:
             exit 1
           fi
 
-      - name: Check claude/blender-rules.md is regenerated from rules/*.mdc
+      - name: Check claude/blender-rules.md and the rules skill are regenerated from rules/*.mdc
         run: python3 scripts/build_claude_rules.py --check
 
+      - name: Check skill file references resolve outside a checkout
+        run: python3 tests/check_skill_refs.py
+
   validate-counts:
     name: Validate content counts
     runs-on: ubuntu-latest

README.md

@@ -61,14 +61,14 @@ git clone https://github.com/TMHSDigital/Blender-Developer-Tools.git
 ```
 
 - **Cursor** — open your project with this checkout available and copy (or symlink) `rules/*.mdc` into your project's `.cursor/rules/`. The rules apply automatically by glob scope; skills are referenced by name in chat.
-- **Claude Code** — install as a plugin, then run `/skills` to see all 16 skills:
+- **Claude Code** — install as a plugin, then run `/skills` to see all 16 skills plus `blender-rules`:
 
   ```text
   /plugin marketplace add TMHSDigital/Blender-Developer-Tools
   /plugin install blender-developer-tools@blender-developer-tools
   ```
 
-  Claude Code does not read Cursor `.mdc` rules. For the rules, add one line to your project's `CLAUDE.md` that imports the generated summary from a checkout: `@/path/to/Blender-Developer-Tools/claude/blender-rules.md`. Without the plugin, copy `skills/*` into your project's `.claude/skills/` instead.
+  Claude Code does not read Cursor `.mdc` rules, so the plugin ships them as the `blender-rules` skill (generated from `rules/`), which Claude loads when it writes or reviews bpy code. No second clone is needed. To keep the rules in context all the time instead, add `@/path/to/Blender-Developer-Tools/claude/blender-rules.md` to your project's `CLAUDE.md` from a checkout. Without the plugin, copy `skills/*` and `claude/skills/*` into your project's `.claude/skills/`.
 - **Get Blender** — download **5.2 LTS** (primary target) or **4.5 LTS** (supported fallback) from [blender.org/download/lts](https://www.blender.org/download/lts/); current stable lives at [blender.org/download](https://www.blender.org/download/). The `blender` command below is that binary — on macOS it is inside the app bundle at `/Applications/Blender.app/Contents/MacOS/Blender`.
 - **Run an example** — every example is a self-checking headless script (exit non-zero on failure, no GPU needed for the check):
 
@@ -81,7 +81,7 @@ blender --background --python examples/bmesh-gear/bmesh_gear.py --
 Releases ship often; [CHANGELOG.md](CHANGELOG.md) lists what each one changed.
 
 - **Claude Code plugin** — `/plugin marketplace update blender-developer-tools` refreshes the marketplace and its plugins (from a shell: `claude plugin update blender-developer-tools@blender-developer-tools`). Remove it with `/plugin uninstall blender-developer-tools`, then `/plugin marketplace remove blender-developer-tools`.
-- **Checkout** (Cursor rules, the Claude rules import, examples) — `git pull` in the clone. Copied `.mdc` files do not update themselves: symlink `rules/*.mdc` into `.cursor/rules/` instead of copying, or re-copy after each pull. To uninstall, delete the copied or linked rules and the `@.../blender-rules.md` line from your `CLAUDE.md`.
+- **Checkout** (Cursor rules, the optional always-on Claude rules import, examples) — `git pull` in the clone. Copied `.mdc` files do not update themselves: symlink `rules/*.mdc` into `.cursor/rules/` instead of copying, or re-copy after each pull. To uninstall, delete the copied or linked rules and the `@.../blender-rules.md` line from your `CLAUDE.md`.
 
 ## Supported Blender versions
 
@@ -1486,7 +1486,7 @@ The `.mdc` files in `rules/` apply automatically when Cursor opens a Blender Pyt
 - `no-unapplied-modifiers-on-export`: flags export of objects with live modifiers when the export does not request evaluated geometry
 - `use-correct-axis-rna-per-exporter`: flags `export_scene.gltf` calls that pass FBX `axis_forward` / `axis_up`, and `export_scene.fbx` calls that pass glTF `export_yup`
 
-Cursor: copy `rules/*.mdc` into `.cursor/rules/`. Claude Code: install the plugin (see [Quick start](#quick-start)) and import `claude/blender-rules.md` from your `CLAUDE.md`.
+Cursor: copy `rules/*.mdc` into `.cursor/rules/`. Claude Code: install the plugin (see [Quick start](#quick-start)); it ships the rules as the `blender-rules` skill.
 
 ## Using the templates
 

claude/blender-rules.md

@@ -9,52 +9,52 @@ full version with Wrong/Right examples.
 
 Flag bmesh.new() calls without a paired bm.free() in a try/finally block. BMesh allocates C-side memory that Python's garbage collector cannot reclaim; missing free() leaks and eventually crashes Blender.
 
-Applies to: `**/*.py`. Full rule: `rules/always-free-bmesh.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/always-free-bmesh.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/always-free-bmesh.mdc).
 
 ## no-unapplied-modifiers-on-export
 
 Flag an export call on objects that still carry unapplied modifiers when the export arguments do not request evaluated geometry. The engine then receives the authored cage, not the modifier result.
 
-Applies to: `**/*.py`. Full rule: `rules/no-unapplied-modifiers-on-export.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/no-unapplied-modifiers-on-export.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-unapplied-modifiers-on-export.mdc).
 
 ## prefer-data-over-ops-in-loops
 
 Flag bpy.ops.* calls inside iteration over many objects, meshes, or frames. Each bpy.ops call triggers a full depsgraph evaluation and UI redraw; loops slow down by orders of magnitude. Use bpy.data.* and bmesh instead.
 
-Applies to: `**/*.py`. Full rule: `rules/prefer-data-over-ops-in-loops.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/prefer-data-over-ops-in-loops.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/prefer-data-over-ops-in-loops.mdc).
 
 ## prefer-temp-override-over-context-copy
 
 Flag uses of `bpy.context.copy()` to override context for an operator call. Passing a context dict to an operator was deprecated in Blender 3.2 and removed in 4.0, so it already fails on the 4.5 LTS fallback. Use `bpy.context.temp_override(**overrides)` as a context manager instead.
 
-Applies to: `**/*.py`. Full rule: `rules/prefer-temp-override-over-context-copy.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/prefer-temp-override-over-context-copy.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/prefer-temp-override-over-context-copy.mdc).
 
 ## target-extensions-platform-format
 
 Flag new Blender add-ons that ship only a legacy bl_info dict without a blender_manifest.toml. New add-ons must use the Extensions Platform format. bl_info may appear alongside as a fallback for backward compatibility, but the manifest is the source of truth.
 
-Applies to: `**/__init__.py`, `**/blender_manifest.toml`. Full rule: `rules/target-extensions-platform-format.mdc`.
+Applies to: `**/__init__.py`, `**/blender_manifest.toml`. Full rule: [`rules/target-extensions-platform-format.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/target-extensions-platform-format.mdc).
 
 ## type-annotate-props-and-defend-context
 
 Flag two related anti-patterns. (1) bpy.props defined as class-level assignments instead of type annotations (deprecated since 2.8). (2) Code that touches bpy.context.active_object without guarding for None.
 
-Applies to: `**/*.py`. Full rule: `rules/type-annotate-props-and-defend-context.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/type-annotate-props-and-defend-context.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/type-annotate-props-and-defend-context.mdc).
 
 ## use-correct-axis-rna-per-exporter
 
 Flag export_scene.gltf calls that pass FBX axis_forward or axis_up, and export_scene.fbx calls that pass glTF export_yup. The two exporters do not share axis RNA.
 
-Applies to: `**/*.py`. Full rule: `rules/use-correct-axis-rna-per-exporter.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/use-correct-axis-rna-per-exporter.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/use-correct-axis-rna-per-exporter.mdc).
 
 ## use-foreach-set-for-bulk-data
 
 Flag Python loops that set vertex coordinates, normals, UVs, or other bulk per-element data one element at a time. For meshes of more than a few thousand elements, this is 100x to 1000x slower than `mesh.vertices.foreach_set("co", flat_array)`, which writes through to C-level storage in one pass.
 
-Applies to: `**/*.py`. Full rule: `rules/use-foreach-set-for-bulk-data.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/use-foreach-set-for-bulk-data.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/use-foreach-set-for-bulk-data.mdc).
 
 ## validate-imported-mesh-scale
 
 Flag a glTF or FBX import followed by mesh operations with no transform_apply and no unit-scale check. Generated files often arrive with non-identity object scale or a non-meter scene scale; mesh edits then bake the wrong size.
 
-Applies to: `**/*.py`. Full rule: `rules/validate-imported-mesh-scale.mdc`.
+Applies to: `**/*.py`. Full rule: [`rules/validate-imported-mesh-scale.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/validate-imported-mesh-scale.mdc).

claude/skills/blender-rules/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: blender-rules
+description: Blender Python anti-pattern rules (bmesh leaks, bpy.ops in loops, deprecated context-copy overrides, bulk mesh writes, prop annotations and context guards, Extensions manifest, import scale, export modifiers, glTF/FBX axis RNA). Use when writing, reviewing or fixing any bpy / Blender add-on or script code.
+---
+
+# Blender Developer Tools rules (Claude Code)
+
+<!-- Generated by scripts/build_claude_rules.py from rules/*.mdc. Do not edit. -->
+
+Apply these when writing or reviewing Blender Python. Each rule links to the
+full version with Wrong/Right examples.
+
+## always-free-bmesh
+
+Flag bmesh.new() calls without a paired bm.free() in a try/finally block. BMesh allocates C-side memory that Python's garbage collector cannot reclaim; missing free() leaks and eventually crashes Blender.
+
+Applies to: `**/*.py`. Full rule: [`rules/always-free-bmesh.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/always-free-bmesh.mdc).
+
+## no-unapplied-modifiers-on-export
+
+Flag an export call on objects that still carry unapplied modifiers when the export arguments do not request evaluated geometry. The engine then receives the authored cage, not the modifier result.
+
+Applies to: `**/*.py`. Full rule: [`rules/no-unapplied-modifiers-on-export.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-unapplied-modifiers-on-export.mdc).
+
+## prefer-data-over-ops-in-loops
+
+Flag bpy.ops.* calls inside iteration over many objects, meshes, or frames. Each bpy.ops call triggers a full depsgraph evaluation and UI redraw; loops slow down by orders of magnitude. Use bpy.data.* and bmesh instead.
+
+Applies to: `**/*.py`. Full rule: [`rules/prefer-data-over-ops-in-loops.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/prefer-data-over-ops-in-loops.mdc).
+
+## prefer-temp-override-over-context-copy
+
+Flag uses of `bpy.context.copy()` to override context for an operator call. Passing a context dict to an operator was deprecated in Blender 3.2 and removed in 4.0, so it already fails on the 4.5 LTS fallback. Use `bpy.context.temp_override(**overrides)` as a context manager instead.
+
+Applies to: `**/*.py`. Full rule: [`rules/prefer-temp-override-over-context-copy.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/prefer-temp-override-over-context-copy.mdc).
+
+## target-extensions-platform-format
+
+Flag new Blender add-ons that ship only a legacy bl_info dict without a blender_manifest.toml. New add-ons must use the Extensions Platform format. bl_info may appear alongside as a fallback for backward compatibility, but the manifest is the source of truth.
+
+Applies to: `**/__init__.py`, `**/blender_manifest.toml`. Full rule: [`rules/target-extensions-platform-format.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/target-extensions-platform-format.mdc).
+
+## type-annotate-props-and-defend-context
+
+Flag two related anti-patterns. (1) bpy.props defined as class-level assignments instead of type annotations (deprecated since 2.8). (2) Code that touches bpy.context.active_object without guarding for None.
+
+Applies to: `**/*.py`. Full rule: [`rules/type-annotate-props-and-defend-context.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/type-annotate-props-and-defend-context.mdc).
+
+## use-correct-axis-rna-per-exporter
+
+Flag export_scene.gltf calls that pass FBX axis_forward or axis_up, and export_scene.fbx calls that pass glTF export_yup. The two exporters do not share axis RNA.
+
+Applies to: `**/*.py`. Full rule: [`rules/use-correct-axis-rna-per-exporter.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/use-correct-axis-rna-per-exporter.mdc).
+
+## use-foreach-set-for-bulk-data
+
+Flag Python loops that set vertex coordinates, normals, UVs, or other bulk per-element data one element at a time. For meshes of more than a few thousand elements, this is 100x to 1000x slower than `mesh.vertices.foreach_set("co", flat_array)`, which writes through to C-level storage in one pass.
+
+Applies to: `**/*.py`. Full rule: [`rules/use-foreach-set-for-bulk-data.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/use-foreach-set-for-bulk-data.mdc).
+
+## validate-imported-mesh-scale
+
+Flag a glTF or FBX import followed by mesh operations with no transform_apply and no unit-scale check. Generated files often arrive with non-identity object scale or a non-meter scene scale; mesh edits then bake the wrong size.
+
+Applies to: `**/*.py`. Full rule: [`rules/validate-imported-mesh-scale.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/validate-imported-mesh-scale.mdc).

scripts/build_claude_rules.py

@@ -1,10 +1,18 @@
 #!/usr/bin/env python3
-"""Generate claude/blender-rules.md from rules/*.mdc.
+"""Generate the Claude Code copies of rules/*.mdc.
 
-Claude Code does not read Cursor .mdc rules. This writes a plain-markdown
-summary (one section per rule: description, load scope, link to the full rule)
-that a Claude Code user imports from their own CLAUDE.md with
-``@path/to/Blender-Developer-Tools/claude/blender-rules.md``.
+Claude Code does not read Cursor .mdc rules. This writes the same plain-markdown
+summary (one section per rule: description, load scope, link to the full rule
+with its Wrong/Right examples) to two places:
+
+- claude/skills/blender-rules/SKILL.md: a skill the plugin ships
+  (.claude-plugin/plugin.json "skills"), so plugin users get the rules with no
+  second clone; Claude loads it when writing or reviewing bpy code.
+- claude/blender-rules.md: for always-on use, imported from a project's
+  CLAUDE.md with ``@path/to/Blender-Developer-Tools/claude/blender-rules.md``.
+
+Links are absolute GitHub URLs so they open from an installed plugin, a
+checkout, or a CLAUDE.md import alike.
 
     python scripts/build_claude_rules.py          # rewrite the file
     python scripts/build_claude_rules.py --check  # exit 1 if it is stale (CI)
@@ -18,6 +26,14 @@
 
 REPO = Path(__file__).resolve().parent.parent
 OUT = REPO / "claude" / "blender-rules.md"
+SKILL_OUT = REPO / "claude" / "skills" / "blender-rules" / "SKILL.md"
+RULE_URL = "https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/"
+SKILL_FRONT = """---
+name: blender-rules
+description: Blender Python anti-pattern rules (bmesh leaks, bpy.ops in loops, deprecated context-copy overrides, bulk mesh writes, prop annotations and context guards, Extensions manifest, import scale, export modifiers, glTF/FBX axis RNA). Use when writing, reviewing or fixing any bpy / Blender add-on or script code.
+---
+
+"""
 
 
 def parse(path: Path) -> tuple[str, list[str]]:
@@ -50,24 +66,34 @@ def render() -> str:
             "",
             desc,
             "",
-            f"Applies to: {', '.join(f'`{g}`' for g in globs) or 'n/a'}. Full rule: `rules/{path.name}`.",
+            f"Applies to: {', '.join(f'`{g}`' for g in globs) or 'n/a'}. Full rule: [`rules/{path.name}`]({RULE_URL}{path.name}).",
             "",
         ]
     return "\n".join(lines).rstrip("\n") + "\n"
 
 
+def outputs() -> dict[Path, str]:
+    body = render()
+    return {OUT: body, SKILL_OUT: SKILL_FRONT + body}
+
+
 def main() -> int:
-    new = render()
     if "--check" in sys.argv:
-        old = OUT.read_text(encoding="utf-8").replace("\r\n", "\n") if OUT.exists() else ""
-        if old != new:
-            print("claude/blender-rules.md is stale; run python scripts/build_claude_rules.py", file=sys.stderr)
+        stale = []
+        for path, new in outputs().items():
+            old = path.read_text(encoding="utf-8").replace("\r\n", "\n") if path.exists() else ""
+            if old != new:
+                stale.append(path.relative_to(REPO).as_posix())
+        if stale:
+            print(f"{', '.join(stale)} stale; run python scripts/build_claude_rules.py",
+                  file=sys.stderr)
             return 1
-        print("claude/blender-rules.md is up to date")
+        print("claude/blender-rules.md and claude/skills/blender-rules/SKILL.md are up to date")
         return 0
-    OUT.parent.mkdir(exist_ok=True)
-    OUT.write_text(new, encoding="utf-8", newline="\n")
-    print(f"wrote {OUT.relative_to(REPO)}")
+    for path, new in outputs().items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new, encoding="utf-8", newline="\n")
+        print(f"wrote {path.relative_to(REPO)}")
     return 0