Skip to content

fix(skills): put trigger phrasing in every skill description - #418

Merged
TMHSDigital merged 1 commit into
mainfrom
fix/skill-trigger-descriptions
Oct 5, 2026
Merged

TMHSDigital merged 1 commit into
mainfrom
fix/skill-trigger-descriptions

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Closes #357. Closes #396.

Problem

Claude Code and Cursor decide whether to load a skill from its frontmatter description alone.

  • All 16 skills kept their triggers in a body ## Trigger section that the model can't see at selection time.
  • 0 of 16 descriptions had a "Use when…" clause.
  • The documented "under 200 chars" limit (AGENTS.md, CONTRIBUTING.md) was already broken by 12 skills, was never enforced, and would have blocked the fix.

Change

Evidence (local; no Blender needed)

  • python tests/check_frontmatter.py: skill and rule frontmatter valid. All 16 descriptions yaml.safe_load cleanly. Longest is 501 chars.
  • Falsified: with "Use when" replaced by "Handy when" in ui-panels, the check prints ::error::skills/ui-panels/SKILL.md: description has no 'Use when ...' trigger clause and exits 1. Restored, it passes.
  • Landing page: build_site._summarize() (340-char, whole-sentence cut) shows only the first, "what it covers" sentence(s) for every skill (128–293 chars). The trigger clause doesn't clutter the cards.

Not measured: the change in skill-selection rate. That is what the eval harness in #373 would quantify.

🤖 Generated with Claude Code

@github-actions github-actions Bot added skills 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: 141 passed, 3 skipped, 0 failed;136 passed, 6 skipped, 0 failed;143 passed, 1 skipped, 0 failed;142 passed, 0 skipped, 0 failed;

Claude Code and Cursor choose a skill from its frontmatter description
alone. All 16 skills kept their triggers (API names, error strings) in a
body "## Trigger" section the model cannot see at selection time, and
none had a "Use when" clause, so the skills fired less often than they
should.

Each description now says what the skill covers, then "Use when ..."
with the API names and literal error messages that should load it
(e.g. "No active UV layer found", "poll() failed, context is
incorrect", AttributeError on sequence_editor.sequences). The
slotted-actions description also stops recommending bare action.fcurves
on 4.5 (#385), and engine-export-presets matches #346.

The documented "under 200 chars" limit was already broken by 12 skills
and never enforced, and it would have blocked this. check_frontmatter
now enforces <= 1024 characters (the Agent Skills cap) and a "Use when"
clause; AGENTS.md and CONTRIBUTING.md show the new shape.

Closes #357
Closes #396

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@TMHSDigital
TMHSDigital force-pushed the fix/skill-trigger-descriptions branch from e815d6f to 88e364f Compare October 5, 2026 00:29
@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: 143 passed, 1 skipped, 0 failed;142 passed, 0 skipped, 0 failed;141 passed, 3 skipped, 0 failed;136 passed, 6 skipped, 0 failed;

@TMHSDigital
TMHSDigital merged commit 5e0299c into main Oct 5, 2026
13 checks passed
@TMHSDigital
TMHSDigital deleted the fix/skill-trigger-descriptions branch October 5, 2026 00:45
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 skills

Projects

None yet

1 participant