feat: every skill lists the snippets that serve it, from snippets/skills.json

Examples reached skills through a generated, validated section, but snippets
were linked by hand, and three smoke-tested ones (register-classes-factory,
pointerproperty-binding, foreach-get-vertices) were linked from no skill, so
agents that find content through skills never saw them. snippets/skills.json
maps each snippet to its skills; build_examples_index.py writes a Snippets
list into the generated section and fails (Validate) on a snippet that maps to
no skill or is missing from the mapping (both falsified).

Closes #524

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LpkeXRvikhJZSVGBFM91Dv
Signed-off-by: TM Hospitality Strategies <TMHospitalityStrategies@gmail.com>

Author: TMHSDigital

CONTRIBUTING.md

@@ -138,6 +138,7 @@ showcase/
 1. Add a `.py` file under `snippets/`, e.g. `snippets/depsgraph-evaluated-mesh.py`.
 2. Keep it 5 to 75 lines, fully working code, with a header comment naming the snippet and citing the relevant Blender doc URL or research section.
 3. Add an entry to `tests/smoke/snippet_checks.py`: a `check` that calls the snippet's functions and asserts one observable fact, and a `falsify` (old, new) source edit that must make the check fail. Content Smoke (`.github/workflows/content-smoke.yml`) runs the snippet in place on 4.5 and 5.2; Validate fails a snippet without an entry. Run it locally with `blender --background --factory-startup --python tests/smoke/run_content.py -- --only <name>`.
+4. Map it to the skills it serves in `snippets/skills.json`, then run `python scripts/build_examples_index.py`: each skill's generated section lists its snippets, and Validate fails a snippet that maps to no skill.
 
 ## Adding a Template
 

scripts/build_examples_index.py

@@ -1,12 +1,17 @@
 #!/usr/bin/env python3
 """Generate examples/index.json and each skill's "Runnable examples" section.
 
+The same generated section also lists the snippets that serve the skill
+(snippets/skills.json, #524), so a smoke-tested snippet is never shipped
+without a skill that points an agent at it.
+
 One file describes every example (#377): its script, the skills it proves,
 whether it ships a gallery render, the oldest Blender it runs on, the command
 to run it, every smoke falsifier with its expected exit, and the README's
 exit-code table. Inputs, all hand-edited elsewhere:
 
     examples/skills.json         example -> skills it proves (edit this one)
+    snippets/skills.json         snippet -> skills it serves (and this one)
     tests/smoke/catalog.json     scripts, min_version, falsifiers
     examples/gallery.json        which examples render
     examples/<name>/README.md    one-line summary and exit-code table
@@ -149,14 +154,35 @@ def build_index() -> tuple[list[dict], list[str]]:
     return index, errors
 
 
+def load_snippets(skills: list[str]) -> tuple[dict[str, list[str]], list[str]]:
+    """skill -> snippet files, and the mapping's errors."""
+    errors: list[str] = []
+    mapping = json.loads((ROOT / "snippets" / "skills.json").read_text(encoding="utf-8"))
+    mapping.pop("_comment", None)
+    files = sorted(p.name for p in (ROOT / "snippets").glob("*.py"))
+    for name in sorted(set(files) - set(mapping)):
+        errors.append(f"snippets/{name} is missing from snippets/skills.json")
+    for name in sorted(set(mapping) - set(files)):
+        errors.append(f"snippets/skills.json lists {name}, which is not a snippet")
+    by_skill: dict[str, list[str]] = {}
+    for name, listed in sorted(mapping.items()):
+        if not listed:
+            errors.append(f"snippets/skills.json: {name} maps to no skill; point one at it")
+        for s in listed:
+            if s not in skills:
+                errors.append(f"snippets/skills.json: {name} names unknown skill {s!r}")
+            by_skill.setdefault(s, []).append(name)
+    return by_skill, errors
+
+
 def _flag(f: dict) -> str:
     args = " ".join(f["args"])
     if f.get("expect_sidecar_fail"):
         return f"`{args}` (harness fails the sidecar)"
     return f"`{args}` (exit {f['expect_exit']})"
 
 
-def skill_section(skill: str, index: list[dict]) -> str:
+def skill_section(skill: str, index: list[dict], snippets: dict[str, list[str]] | None = None) -> str:
     lines = [BEGIN, "## Runnable examples", ""]
     mine = [e for e in index if skill in e["skills"]]
     if not mine:
@@ -172,6 +198,12 @@ def skill_section(skill: str, index: list[dict]) -> str:
             since = f" Blender {e['min_version']}+." if e["min_version"] != "4.5" else ""
             lines.append(f"- [`{e['name']}`]({REPO_URL}/tree/main/examples/{e['name']}): {e['summary']}"
                          f"{since} Falsify: {first}.")
+    mine_snippets = (snippets or {}).get(skill, [])
+    if mine_snippets:
+        lines += ["", "### Snippets", "",
+                  "Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 "
+                  "with a check and a falsifier.", ""]
+        lines += [f"- [`snippets/{n}`]({REPO_URL}/blob/main/snippets/{n})" for n in mine_snippets]
     lines += ["", END]
     return "\n".join(lines)
 
@@ -193,13 +225,17 @@ def main(argv=None) -> int:
     ap.add_argument("--check", action="store_true")
     a = ap.parse_args(argv)
     index, errors = build_index()
+    snippets, snippet_errors = load_snippets(
+        sorted(p.parent.name for p in (ROOT / "skills").glob("*/SKILL.md")))
+    errors += snippet_errors
     if errors:  # a broken mapping cannot render the skill sections
         for e in errors:
             print(f"::error::{e}", file=sys.stderr)
         return 1
     want ={ROOT / "examples" / "index.json": json.dumps(index, indent=2, ensure_ascii=False) + "\n"}
     for p in sorted((ROOT / "skills").glob("*/SKILL.md")):
-        want[p] = render_skill(p.read_text(encoding="utf-8"), skill_section(p.parent.name, index))
+        want[p] = render_skill(p.read_text(encoding="utf-8"),
+                               skill_section(p.parent.name, index, snippets))
     stale = [p for p, text in want.items()
              if not p.is_file() or p.read_text(encoding="utf-8") != text]
     if a.check:

skills/addon-scaffolding/SKILL.md

@@ -223,6 +223,12 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 
 - [`addon-register-lifecycle`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/addon-register-lifecycle): Check-only witness for the first things every add-on author writes. Falsify: `--drop-manifest` (exit 3).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/register-classes-factory.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/register-classes-factory.py)
+
 <!-- examples:end -->
 
 ## References

skills/ai-mesh-cleanup/SKILL.md

@@ -262,6 +262,15 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 - [`prop-origin-transform`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/prop-origin-transform): Street pedestal origin-to-base-center + data-API scale apply + matrix_parent_inverse for a flanged conduit elbow. Falsify: `--skip-mpi` (exit 8).
 - [`unapplied-scale-gltf`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/unapplied-scale-gltf): Synthesizes unapplied non-uniform object scale on a unit cube, then asserts the glTF exporter contract. Falsify: `--identity` (exit 3).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/convex_hull_collider.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/convex_hull_collider.py)
+- [`snippets/decimate_to_budget.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/decimate_to_budget.py)
+- [`snippets/gltf_draco_export.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/gltf_draco_export.py)
+- [`snippets/lod_chain.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/lod_chain.py)
+
 <!-- examples:end -->
 
 ## References

skills/bake-high-to-low/SKILL.md

@@ -172,4 +172,13 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 
 - [`bake-normal-high-to-low`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/bake-normal-high-to-low): A collapse-decimated hatch plate receiving a Cycles cage-baked tangent normal map from a ribbed high-poly source Falsify: `--flat-source` (exit 5).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/bake_normal_high_to_low.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/bake_normal_high_to_low.py)
+- [`snippets/decimate_to_budget.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/decimate_to_budget.py)
+- [`snippets/save_baked_image.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/save_baked_image.py)
+- [`snippets/setup_bake_target_image.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/setup_bake_target_image.py)
+
 <!-- examples:end -->

skills/compositor-nodes/SKILL.md

@@ -180,6 +180,12 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 
 - [`compositor-glare`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/compositor-glare): Bloom where it actually lives — a compositor Glare (Fog Glow) node fed by Render Layers. Falsify: `--threshold-high` (exit 4).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/shader-node-group.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/shader-node-group.py)
+
 <!-- examples:end -->
 
 ## References

skills/custom-properties/SKILL.md

@@ -275,6 +275,13 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 - [`addon-register-lifecycle`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/addon-register-lifecycle): Check-only witness for the first things every add-on author writes. Falsify: `--drop-manifest` (exit 3).
 - [`cross-version-property-delete`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/cross-version-property-delete): Custom ID properties are removed with del, not property_unset. Falsify: `--skip-delete` (exit 7).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/cross-version-property-delete.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/cross-version-property-delete.py)
+- [`snippets/pointerproperty-binding.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/pointerproperty-binding.py)
+
 <!-- examples:end -->
 
 ## References

skills/depsgraph-and-evaluated-data/SKILL.md

@@ -222,6 +222,13 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 - [`solidify-even-thickness`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/solidify-even-thickness): Solidify's use_even_offset on a folded strip. Falsify: `--no-even` (exit 4).
 - [`usd-export-evaluation-mode`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/usd-export-evaluation-mode): The USD exporter evaluation_mode chooses viewport versus render modifier quality. Falsify: `--subdivision BEST_MATCH` (exit 4).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/depsgraph-evaluated-mesh.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/depsgraph-evaluated-mesh.py)
+- [`snippets/usd-export-evaluation-mode.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/usd-export-evaluation-mode.py)
+
 <!-- examples:end -->
 
 ## References

skills/drivers-and-app-handlers/SKILL.md

@@ -330,6 +330,13 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 - [`driver-wave`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/driver-wave): A driver_namespace function driving sixteen organ-pipe heights through SCRIPTED drivers — the sine skyline of the pipe tops is entirely driver-evaluated. Falsify: `--flat-expr` (exit 3).
 - [`exit-pre-sidecar`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/exit-pre-sidecar): `bpy.app.handlers.exit_pre` writes `$BDT_SMOKE_SIDECAR` as Blender dies. Blender 5.1+. Falsify: `--atexit-instead` (harness fails the sidecar).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/app-handler-registration.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/app-handler-registration.py)
+- [`snippets/driver-with-custom-function.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/driver-with-custom-function.py)
+
 <!-- examples:end -->
 
 ## References

skills/engine-export-presets/SKILL.md

@@ -149,6 +149,15 @@ Each example runs headless, asserts the contract, and exits non-zero when it bre
 - [`gltf-skin-roundtrip`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/gltf-skin-roundtrip): A rigged mech scorpion exported to glTF with skins and re-imported, verifying the skinning contract the geometry round-trip left uncovered. Falsify: `--no-skins` (exit 5).
 - [`unapplied-scale-gltf`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/unapplied-scale-gltf): Synthesizes unapplied non-uniform object scale on a unit cube, then asserts the glTF exporter contract. Falsify: `--identity` (exit 3).
 
+### Snippets
+
+Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
+
+- [`snippets/export_preset_godot.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/export_preset_godot.py)
+- [`snippets/export_preset_unity.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/export_preset_unity.py)
+- [`snippets/export_preset_unreal.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/export_preset_unreal.py)
+- [`snippets/gltf_draco_export.py`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/snippets/gltf_draco_export.py)
+
 <!-- examples:end -->
 
 ## References