@@ -105,7 +105,7 @@ showcase/
 
 3. Aim for 150 to 350 lines covering the canonical pattern, common AI mistakes, version-correctness notes, and one or two worked code examples. Cite Blender API doc URLs where relevant. Avoid encyclopedic API tours.
 4. The skill `name` in frontmatter must match the directory name exactly (CI enforces this).
-5. Every ```python block must compile (`tests/check_content_catalog.py`). Put `<!-- smoke: run -->` on the line directly above a block that is self-contained, so Content Smoke executes it on 4.5 and 5.2 in a factory-startup scene: no input files, no render, and it ends with `assert`s on what it built. Tag at least one block per skill where the API allows it.
+5. Every ```python block must compile (`tests/check_content_catalog.py`). Put `<!-- smoke: run -->` on the line directly above a block that is self-contained, so Content Smoke executes it on 4.5 and 5.2 in a factory-startup scene: no input files, no render, and it ends with `assert`s on what it built. Tag at least one block per skill where the API allows it; Validate requires it unless `tests/smoke/skill_blocks.json` gives the skill a `compile_only` reason naming the example that proves it, and the total tagged count may not drop below that file's `floor` (raise the floor when you tag more).
 6. Map at least one example to the skill in `examples/skills.json`; an example mapped to no skill fails Validate.
 
 ## Adding a Rule
 
@@ -24,6 +24,7 @@ The Python pattern for building a Geometry Nodes tree has four phases:
 3. Wire nodes with `tree.links.new`.
 4. Add a NODES modifier on the target object that points at the group.
 
+<!-- smoke: run -->
 ```python
 import bpy
 
 
@@ -211,6 +211,7 @@ Notes:
 
 ## Detecting Blender version in scripts
 
+<!-- smoke: run -->
 ```python
 import bpy
 
 
@@ -60,6 +60,7 @@ This skill is an index. Each row points at the skill, rule or runnable example t
 
 Keep one code path and branch only where the table says *branch*:
 
+<!-- smoke: run -->
 ```python
 import bpy
 
 
@@ -45,6 +45,7 @@ On 4.4 / 4.5 LTS, ensure the channelbag yourself with `strip.channelbag(slot, en
 
 Import path (5.0+) verified against the Blender 5.1 API reference: `bpy_extras.anim_utils.action_ensure_channelbag_for_slot(action, slot)`. See [`bpy_extras.anim_utils`](https://docs.blender.org/api/current/bpy_extras.anim_utils.html).
 
+<!-- smoke: run -->
 ```python
 import bpy
 
@@ -80,6 +81,12 @@ def get_channelbag_for_object(obj):
         obj.animation_data.action_slot = slot
 
     return get_channelbag_for_slot(action, slot)
+
+# Usage: every F-curve write goes through the slot's channelbag, on 4.5 and 5.x.
+cbag = get_channelbag_for_object(bpy.context.active_object)
+fc = cbag.fcurves.new(data_path="location", index=2)
+fc.keyframe_points.insert(1, 0.0)
+assert bpy.context.active_object.animation_data.action_slot is not None
 ```
 
 The version boundary that matters is `bpy.app.version >= (5, 0, 0)` (legacy removed / ensure-helper added), **not** `hasattr(action, "slots")` — `action.slots` is present on 4.4 and 4.5 too, so that check does not distinguish 4.5 from 5.x.
 
@@ -18,6 +18,7 @@ Use this skill when the user:
 
 ## High-level shape
 
+<!-- smoke: run -->
 ```python
 import bpy
 
 
@@ -4,12 +4,15 @@
   with a ``check`` and a ``falsify`` (old, new) whose ``old`` occurs in the
   snippet, so tests/smoke/run_content.py can never silently skip a snippet.
 - Every ```python block in skills/*/SKILL.md compiles. Blocks tagged with a
-  ``<!-- smoke: run -->`` line are also executed by run_content.py in Blender;
-  this reports how many are tagged.
+  ``<!-- smoke: run -->`` line are also executed by run_content.py in Blender.
+- Ratchet (#525, tests/smoke/skill_blocks.json): at least ``floor`` blocks are
+  tagged, and every skill has a tagged block or a ``compile_only`` entry saying
+  why its blocks cannot run standalone and which example proves it instead.
 
 Exit 1 with one ::error:: line per problem.
 """
 import glob
+import json
 import os
 import re
 import sys
@@ -48,29 +51,56 @@ def check(root=ROOT, cases=None):
                 errors.append(f"{name}: falsify string {fals[0]!r} is not in the snippet")
 
     blocks = tagged = 0
+    per_skill = {}
     for path in sorted(glob.glob(os.path.join(root, "skills", "*", "SKILL.md"))):
         rel = os.path.relpath(path, root).replace(os.sep, "/")
         with open(path, encoding="utf-8") as fh:
             text = fh.read()
-        tagged += len(TAG.findall(text))
+        n_tagged = len(TAG.findall(text))
+        tagged += n_tagged
+        per_skill[os.path.basename(os.path.dirname(path))] = n_tagged
         for m in FENCE.finditer(text):
             blocks += 1
             start = text.count("\n", 0, m.start(1)) + 1
             try:
                 compile(m.group(1), rel, "exec")
             except SyntaxError as e:
                 errors.append(f"{rel}:{start + (e.lineno or 1) - 1}: python block does not compile: {e.msg}")
+    errors += check_ratchet(root, per_skill, tagged)
     return errors, blocks, tagged
 
 
+def check_ratchet(root, per_skill, tagged):
+    path = os.path.join(root, "tests", "smoke", "skill_blocks.json")
+    if not os.path.isfile(path):
+        return []
+    with open(path, encoding="utf-8") as fh:
+        cfg = json.load(fh)
+    floor, allow = cfg["floor"], cfg.get("compile_only", {})
+    errors = []
+    if tagged < floor:
+        errors.append(f"only {tagged} SKILL.md blocks are tagged <!-- smoke: run -->, below the "
+                      f"floor of {floor} in tests/smoke/skill_blocks.json")
+    for skill, n in sorted(per_skill.items()):
+        if n == 0 and not allow.get(skill, "").strip():
+            errors.append(f"skills/{skill}: no block is tagged <!-- smoke: run --> and "
+                          "tests/smoke/skill_blocks.json gives no compile_only reason")
+        if n and skill in allow:
+            errors.append(f"skills/{skill} has a tagged block; drop its compile_only entry "
+                          "in tests/smoke/skill_blocks.json")
+    for skill in sorted(set(allow) - set(per_skill)):
+        errors.append(f"tests/smoke/skill_blocks.json: compile_only names unknown skill {skill!r}")
+    return errors
+
+
 def main():
     errors, blocks, tagged = check()
     for e in errors:
         print(f"::error::{e}")
     if errors:
         return 1
     print(f"{len(CASES)} snippets catalogued with falsifiers; {blocks} skill python blocks compile, "
-          f"{tagged} tagged for execution")
+          f"{tagged} tagged for execution (ratchet in tests/smoke/skill_blocks.json)")
     return 0
 
 
 
@@ -0,0 +1,19 @@
+{
+  "_comment": "Ratchet for SKILL.md python blocks that Content Smoke executes (<!-- smoke: run -->, #525). tests/check_content_catalog.py fails when fewer blocks are tagged than `floor` (raise the floor when you tag more), and when a skill has no tagged block and no entry in `compile_only`. A compile_only entry says why the skill's blocks cannot run standalone in a fresh factory scene and which runnable example proves the skill instead; tag a block and drop the entry when one can.",
+  "floor": 14,
+  "compile_only": {
+    "addon-scaffolding": "Blocks are files of an add-on package (relative imports, register()); proven by examples/addon-register-lifecycle.",
+    "ai-mesh-cleanup": "Blocks are steps over an imported GLB and helpers defined in the first block; proven by examples/coincident-vert-weld, collision-hull-proxy, degenerate-bevel-weld, lod-decimate-chain.",
+    "bake-high-to-low": "Blocks are steps of one Cycles bake that need a high/low pair and UVs; proven by examples/bake-normal-high-to-low.",
+    "bl-info-migration": "Blocks are package layouts and import forms, not runnable scripts; proven by examples/addon-register-lifecycle.",
+    "custom-properties": "Blocks are add-on class and register() fragments; proven by examples/addon-register-lifecycle and cross-version-property-delete.",
+    "depsgraph-and-evaluated-data": "Blocks define helpers called on caller-supplied objects; proven by examples/armature-bend, boolean-exact-volume, depsgraph-export.",
+    "drivers-and-app-handlers": "Blocks are register()/handler fragments and steps on a caller-supplied object; proven by examples/driver-wave and exit-pre-sidecar.",
+    "engine-export-presets": "Blocks are export calls on a prepared selection; proven by examples/export-preset-axis, gltf-export-roundtrip, unapplied-scale-gltf.",
+    "extension-runtime-and-packaging": "Blocks read __package__ and extension_path_user, which exist only inside an installed extension; proven by examples/extension-package-lifecycle.",
+    "gpu-drawing-and-overlays": "Blocks need a GPU context (draw handlers, or gpu.init() which exists only on 5.2+); proven by examples/gpu-offscreen-draw.",
+    "operators": "Blocks are Operator classes and execute() bodies that need registration and an operator context; proven by examples/prop-origin-transform and temp-override-join.",
+    "timers-modal-and-threading": "Timers never fire under --background, and the blocks call caller-supplied done()/download(); proven by examples/timers-modal-threading in a windowed child Blender.",
+    "ui-panels": "Blocks are Panel draw() bodies that run only inside a UI redraw; proven by examples/addon-register-lifecycle."
+  }
+}
@@ -154,6 +154,21 @@ def test_falsify_that_changes_nothing(self):
         e = self.run_check({"s.py": {"check": "pass", "falsify": ("x = 1", "x = 1")}})
         self.assertTrue(any("changes something" in m for m in e), e)
 
+    def test_ratchet_needs_a_run_block_or_a_reason(self):
+        # #525: a skill with no executed block must say why, and the tagged count cannot drop
+        case = {"s.py": {"check": "pass", "falsify": ("x = 1", "x = 2")}}
+        tagged = "# K\n\n<!-- smoke: run -->\n```python\nx = 1\n```\n"
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            write(root, "snippets/s.py", "x = 1\n")
+            write(root, "skills/k/SKILL.md", "# K\n\n```python\nx = 1\n```\n")
+            write(root, "tests/smoke/skill_blocks.json", json.dumps({"floor": 1, "compile_only": {}}))
+            errs = ccc.check(str(root), case)[0]
+            self.assertTrue(any("below the floor" in e for e in errs), errs)
+            self.assertTrue(any("no compile_only reason" in e for e in errs), errs)
+            write(root, "skills/k/SKILL.md", tagged)
+            self.assertEqual(ccc.check(str(root), case)[0], [])
+
     def test_skill_block_that_does_not_compile_reports_its_line(self):
         skill = "# K\n\ntext\n\n```python\nok = 1\nif True\n    pass\n```\n"
         e = self.run_check({"s.py": {"check": "pass", "falsify": ("x = 1", "x = 2")}}, skill=skill)