TMHSDigital · Oct 5, 2026 · Oct 5, 2026
@@ -123,7 +123,7 @@ Each skill lives at `skills/<skill-name>/SKILL.md`. Frontmatter is YAML:
 ```yaml
 ---
 name: <kebab-case-skill-name>
-description: <one-line, under 200 chars>
+description: "<what it covers>. Use when <the situations, API names and error strings that should load it>."  # <= 1024 chars, enforced
 standards-version: 1.10.0
 ---
 ```

@@ -61,7 +61,7 @@ showcase/
    ```yaml
    ---
    name: procedural-materials-and-shaders
-   description: One-line description, under 200 chars.
+   description: "What it covers. Use when the user mentions X, does Y, or hits error Z."
    standards-version: <current meta-repo STANDARDS_VERSION>
    ---
    ```

@@ -1,6 +1,6 @@
 ---
 name: addon-scaffolding
-description: Scaffold a Blender add-on against the Extensions Platform format with blender_manifest.toml, modular file layout, and the register_classes_factory pattern. Targets Blender 5.2 LTS with 4.5 LTS fallback.
+description: "Scaffold a Blender add-on as an Extensions Platform package: blender_manifest.toml, modular file layout, register_classes_factory, symmetric register/unregister. Use when the user starts a new add-on or extension, writes or fixes blender_manifest.toml, asks which layout or registration pattern to use on Blender 4.5 LTS or 5.x, or has classes that fail to register or unregister cleanly. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: ai-mesh-cleanup
-description: Ordered cleanup for an imported generated mesh. Unit scale, transform apply, origin, normals, evaluated triangle count, decimate to budget, convex collider. Targets 5.2 LTS with 4.5 LTS fallback.
+description: "Ordered cleanup for an imported generated or scanned mesh before it goes to an engine: scene units, apply rotation and scale, origin to base, recalculate normals, evaluated triangle count, decimate to a budget, convex collider. Use when the user has a GLB, glTF or FBX that is not engine-ready, mentions unit scale, unapplied transforms, triangle budget, LODs or a collision hull, or is about to run mesh operations on an import without checking its scale. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: bake-high-to-low
-description: Cage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map. Cycles CPU, selected-to-active, active image node, UV layer, save_render. Targets 5.2 LTS with 4.5 LTS fallback.
+description: "Cage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map with bpy.ops.object.bake (Cycles, selected-to-active, active Image Texture node, UV layer, save_render). Use when the user wants a normal map from a dense mesh onto a game-resolution or decimated LOD, mentions cage_extrusion or use_selected_to_active, or gets a bake that returns CANCELLED, comes out black or flat, or fails with 'No active UV layer found'. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: bl-info-migration
-description: Migrate a legacy bl_info-format add-on to the Extensions Platform. Three concrete steps, before-and-after diff, dual-format pattern for backward compatibility, and answers to "is bl_info still supported?" Targets Blender 5.2 LTS.
+description: "Migrate a legacy bl_info add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern. Use when the user has a bl_info dictionary in __init__.py, asks whether bl_info is deprecated or still supported, wants to publish to extensions.blender.org or ship an extension .zip, or sees warnings about legacy add-ons at install time. Targets 5.2 LTS; manifests work from 4.2."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: custom-properties
-description: Define and bind Blender custom properties via bpy.props using the type annotation form, with PropertyGroup for grouping, PointerProperty for binding, and the four storage location options for Scene/Object/WindowManager/AddonPreferences. Targets 5.2 LTS.
+description: "Define and bind custom properties with bpy.props annotations, PropertyGroup and PointerProperty, and choose where to store them (Scene, Object, WindowManager, AddonPreferences). Use when the user attaches settings or data to datablocks so it survives save and load, is unsure where add-on settings belong, or writes a property as an assignment instead of an annotation and gets a deprecation warning or a _PropertyDeferred value. Targets 5.2 LTS."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: depsgraph-and-evaluated-data
-description: Read the actual evaluated geometry the user sees by going through the dependency graph rather than reading raw `obj.data`. Covers `evaluated_get`, `to_mesh`, `to_mesh_clear`, and the lifetime rules that prevent crashes and memory leaks. Targets Blender 5.2 LTS.
+description: "Read the evaluated geometry the user actually sees through the dependency graph instead of raw obj.data: evaluated_depsgraph_get, evaluated_get, to_mesh and to_mesh_clear lifetimes. Use when the user writes an exporter, measurement or inspection script, reports that modifiers, shape keys, armatures or geometry nodes are missing from exported or measured geometry, or reads obj.data.vertices and gets the undeformed base mesh. Targets 5.2 LTS."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: drivers-and-app-handlers
-description: Drive properties from expressions or other properties via the Driver API, and react to scene events via the bpy.app.handlers callbacks. Covers driver_namespace for Python functions, the new exit_pre handler in 5.1, and the must-be-fast contract for any handler.
+description: "Drive properties from expressions with the Driver API (driver_add, driver_namespace for custom Python functions) and react to events with bpy.app.handlers (load_post, save_pre, frame_change_post, depsgraph_update_post, exit_pre in 5.1+). Use when the user wants one property to follow another, runs code on load, save, frame change or exit, or has a driver failing with NameError or the Python security block, including drivers that die after reopening a file."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: engine-export-presets
-description: Unity, Godot, and Unreal glTF/FBX export presets. glTF is engine-neutral by spec (+Y up, meters, export_yup=True for every engine; Unreal converts to cm on import); FBX uses axis_forward/axis_up plus centimeter scale. Targets 5.2 LTS with 4.5 LTS fallback.
+description: "Export presets for Unity, Godot and Unreal. glTF is +Y up and meters by spec, so every engine gets export_yup=True with no scale bake (Unreal converts to centimeters on import); FBX takes axis_forward/axis_up plus global_scale. Use when the user exports for a game engine, mentions export_yup, axis_forward, axis_up, global_scale, Y-up or centimeters, passes FBX axis kwargs to export_scene.gltf, or gets a model that imports lying on its back or 100x too large. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: geometry-nodes-python
-description: Programmatically construct Geometry Nodes trees in Blender 5.x via bpy.data.node_groups, interface socket creation, node instantiation by RNA name, link wiring, and applying as a NODES modifier. Includes Bundles for grouped sockets.
+description: "Build Geometry Nodes trees from Python: node_groups.new, tree.interface sockets, nodes by RNA identifier, links, Repeat and for-each zones, Bundles, and applying the tree as a NODES modifier including the 5.1 vs 5.2 modifier input API. Use when the user generates a GeometryNodeTree in a script, sets modifier inputs from Python, or hits 'Node type ... undefined' or socket identifier errors. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: headless-batch-scripting
-description: Run Blender headless via blender --background --python script.py for batch jobs. What changes without a UI, how to avoid UI-dependent operators, the temp_override pattern when ops must be used, and argparse after the -- separator.
+description: "Run Blender unattended with blender --background --python, arguments after the -- separator, --factory-startup and --python-exit-code, and temp_override for operators that need context. Use when the user renders, exports or processes .blend files from a CLI, CI job or batch script, passes arguments to a Blender script, or hits 'poll() failed, context is incorrect' or a job that exits 0 despite a Python traceback. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: mesh-editing-and-bmesh
-description: Performant mesh manipulation in Blender. When to use bpy.data vs bpy.ops vs bmesh, the canonical bm.new/free pattern, foreach_set bulk vertex injection, and depsgraph evaluation for modifier-applied geometry. Targets 5.2 LTS.
+description: "Create, edit and read meshes efficiently: when to use bpy.data, bpy.ops or bmesh, the bmesh.new / try / finally / free pattern, foreach_get and foreach_set for bulk data, and evaluated meshes for modifier results. Use when the user writes mesh-generating or mesh-editing Python, mentions bmesh, from_pydata, foreach_set or mesh.vertices, has a slow script looping over bpy.ops.mesh or per-vertex assignments, or a bmesh script that misbehaves on its second run. Targets 5.2 LTS."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: operators
-description: Author Blender operators with bpy.types.Operator, bl_idname conventions, the poll/invoke/execute/modal lifecycle, REGISTER and UNDO options, and defensive context handling. Targets 5.2 LTS with 4.5 LTS compatibility.
+description: "Author bpy.types.Operator classes: bl_idname naming, poll / invoke / execute / modal lifecycle, bl_options (REGISTER, UNDO, INTERNAL, BLOCKING), operator properties and defensive context handling. Use when the user creates an operator for a button, menu, keymap or script, asks why its properties are missing from the Adjust Last Operation (redo) panel or why Ctrl-Z ignores it, or gets poll failures or None context objects. Targets 5.2 LTS with 4.5 LTS compatibility."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: procedural-materials-and-shaders
-description: Build materials and shader graphs from Python by enabling nodes, instantiating shader nodes, setting socket default values, and wiring links. Targets Blender 5.2 LTS EEVEE Next and Cycles. Avoids the (deferred to 2027) Layered Textures roadmap.
+description: "Build materials and shader node graphs from Python: bpy.data.materials, node_tree, Principled BSDF and its 4.0+ socket names, default values, links and shader node groups, for EEVEE and Cycles. Use when the user creates or edits materials in a script, generates many material variations, hits a KeyError on a Principled BSDF input such as Specular or Emission, or asks about EEVEE vs Cycles differences or the deferred Layered Textures system. Targets 5.2 LTS."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: slotted-actions-animation
-description: Animate from Python under the Slotted Actions architecture (data model shipped in Blender 4.4). Action contains Layers contain Strips contain Channelbags. Cross-version channelbag access - action_ensure_channelbag_for_slot is new in 5.0; on 4.4/4.5 LTS use strip.channelbag(slot, ensure=True) or the still-present legacy action.fcurves.
+description: "Create and edit animation from Python under Slotted Actions (Blender 4.4+): Action, slots, layers, strips, channelbags. Bind the action slot, then reach F-curves through a channelbag; action_ensure_channelbag_for_slot exists only on 5.0+, so use strip.channelbag(slot, ensure=True) on 4.5 LTS. Use when the user inserts keyframes or builds F-curves in a script, hits AttributeError on action.fcurves in 5.x, or has keys that exist but never play back. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: ui-panels
-description: Author Blender UI panels with bpy.types.Panel, declarative draw(), bl_space_type and bl_region_type, layout primitives like row/column/split, and conditional UI via .enabled. Targets 5.2 LTS.
+description: "Author bpy.types.Panel UI: bl_space_type, bl_region_type, bl_category sidebar tabs, declarative draw(), layout row, column and split, sub-panels, and conditional UI with enabled and active. Use when the user adds an N-panel tab or properties-editor panel, exposes add-on properties or operator buttons, or has a panel that does not appear, shows the wrong labels or warns about a missing _PT_ in its bl_idname. Targets 5.2 LTS."
 standards-version: 1.10.0
 ---
 

@@ -1,6 +1,6 @@
 ---
 name: vse-python
-description: Build Video Sequence Editor timelines from Python. SequenceEditor.strips vs .sequences, new_effect length vs frame_end, and the 5.2 COLOR strip width/height bake from scene resolution.
+description: "Build and inspect Video Sequence Editor timelines from Python: SequenceEditor.strips vs the removed .sequences, new_effect length vs frame_end, strip transforms, and the 5.2 COLOR strip width/height bake from scene resolution. Use when the user scripts the sequencer, hits AttributeError on sequence_editor.sequences in 5.x or a TypeError on new_effect keyword arguments, or renders COLOR strips that ignore transform scale after a resolution change. Targets 5.2 LTS with 4.5 LTS fallback."
 standards-version: 1.10.0
 ---
 

@@ -39,6 +39,9 @@ def need_str(data: dict, key: str, label: str, errors: list[str]) -> None:
         errors.append(f"{label}: '{key}' must be a non-empty string")
 
 
+SKILL_DESCRIPTION_MAX = 1024
+
+
 def check(root: Path) -> list[str]:
     errors: list[str] = []
     for path in sorted((root / "skills").glob("*/SKILL.md")):
@@ -51,6 +54,15 @@ def check(root: Path) -> list[str]:
             need_str(data, key, label, errors)
         if data.get("name") != path.parent.name:
             errors.append(f"{label}: name {data.get('name')!r} != directory {path.parent.name!r}")
+        desc = data.get("description")
+        if isinstance(desc, str):
+            # Agents pick a skill from its description alone, so it must say
+            # when to use it; 1024 is the Agent Skills format's cap (#357, #396).
+            if len(desc) > SKILL_DESCRIPTION_MAX:
+                errors.append(f"{label}: description is {len(desc)} chars, over "
+                              f"{SKILL_DESCRIPTION_MAX}")
+            if "Use when" not in desc:
+                errors.append(f"{label}: description has no 'Use when ...' trigger clause")
     for path in sorted((root / "rules").glob("*.mdc")):
         label = path.relative_to(root).as_posix()
         data, why = front(path)