facebook · rohan-tessl · Mar 24, 2026
diff --git a/.claude/skills/click-target/SKILL.md b/.claude/skills/click-target/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: click-target
-description: Find and click a target object in XR. Use when testing UI interactions, clicking buttons, or verifying interactable elements work correctly.
+description: "Find and click a target object in XR using emulated controllers. Use when testing UI interactions, clicking buttons, tapping elements, selecting objects, or verifying interactable elements work correctly in VR/AR/WebXR scenes."
 disable-model-invocation: true
 ---
 

diff --git a/.claude/skills/iwsdk-planner/SKILL.md b/.claude/skills/iwsdk-planner/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: iwsdk-planner
-description: IWSDK project planning and best practices guide. Use when planning new IWSDK features, designing systems/components, reviewing IWSDK code architecture, or when the user asks about IWSDK patterns, ECS design, signals, or reactive programming in this codebase.
+description: "IWSDK project planning and best practices guide providing architectural patterns, code review checklists, and implementation guidelines. Use when planning new IWSDK features, designing systems/components, reviewing IWSDK code architecture, or when the user asks about IWSDK patterns, ECS design, signals, or reactive programming in this codebase."
 ---
 
 # IWSDK Project Planner

diff --git a/.claude/skills/iwsdk-ui-panel/SKILL.md b/.claude/skills/iwsdk-ui-panel/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: iwsdk-ui-panel
-description: Develop and iterate on IWSDK UI panels efficiently. Use when working on PanelUI components, debugging UI layout, or improving UI design in IWSDK applications.
+description: "Develop and iterate on IWSDK UI panels efficiently using ScreenSpace preview and backdrop techniques. Use when working on PanelUI components, creating panel layouts, configuring component styling, debugging UI layout, or improving UI design in IWSDK applications."
 allowed-tools: Read, Edit, Write, Bash(npm *)
 ---
 

diff --git a/.claude/skills/test-all/SKILL.md b/.claude/skills/test-all/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-all
-description: 'Parallel test orchestrator. Runs all 9 test suites concurrently via Task sub-agents and mcp-call.mjs. Handles build, example setup, dev servers, agent launch, polling, retries, and result aggregation.'
+description: "Parallel test orchestrator that runs all 9 IWSDK test suites concurrently via Task sub-agents and mcp-call.mjs. Handles build, example setup, dev servers, agent launch, polling, retries, and result aggregation. Use when running all tests, executing the full test suite, validating changes across all IWSDK packages, or performing CI-style parallel testing."
 argument-hint: '[--skip <test-name>] [--only <test-name>]'
 ---
 

diff --git a/.claude/skills/test-audio/SKILL.md b/.claude/skills/test-audio/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-audio
-description: 'Test audio system (AudioSource loading, playback state, stop, spatial audio) against the audio example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK audio system covering AudioSource loading, playback state, stop, and spatial audio against the audio example via mcp-call.mjs WebSocket CLI. Use when testing audio playback, verifying sound system behavior, debugging AudioSource issues, or validating spatial audio in IWSDK applications."
 argument-hint: '[--suite loading|playback|stop|all]'
 ---
 

diff --git a/.claude/skills/test-ecs-core/SKILL.md b/.claude/skills/test-ecs-core/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-ecs-core
-description: 'Test ECS core functionality (system registration, components, Transform sync, pause/step/resume, system toggle, entity discovery, snapshots) against the poke example using mcp-call.mjs WebSocket CLI.'
+description: "Test ECS core functionality covering system registration, components, Transform sync, pause/step/resume, system toggle, entity discovery, and snapshots against the poke example via mcp-call.mjs WebSocket CLI. Use when testing entity-component system behavior, debugging ECS registration, or validating core IWSDK framework functionality."
 argument-hint: '[--suite systems|components|transform|lifecycle|toggle|discovery|snapshot|stability|all]'
 ---
 

diff --git a/.claude/skills/test-environment/SKILL.md b/.claude/skills/test-environment/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-environment
-description: 'Test environment system (DomeGradient, IBLGradient, default lighting, component schemas) against the poke example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK environment system covering DomeGradient, IBLGradient, default lighting, and component schemas against the poke example via mcp-call.mjs WebSocket CLI. Use when testing lighting environments, validating gradient components, debugging scene lighting setup, or verifying environment configuration in IWSDK."
 argument-hint: '[--suite gradient|ibl|defaults|all]'
 ---
 

diff --git a/.claude/skills/test-grab/SKILL.md b/.claude/skills/test-grab/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-grab
-description: 'Test grab system (distance grab, one-hand grab, two-hand grab) against the grab example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK grab system covering distance grab, one-hand grab, and two-hand grab against the grab example via mcp-call.mjs WebSocket CLI. Use when testing VR/XR grab interactions, validating hand tracking mechanics, debugging grab behavior, or verifying object pickup in IWSDK applications."
 argument-hint: '[--suite distance|onehand|twohand|all]'
 ---
 

diff --git a/.claude/skills/test-interactions/SKILL.md b/.claude/skills/test-interactions/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-interactions
-description: 'Test XR interactions (ray, poke/touch, dual-mode, audio, UI panel) against the poke example using mcp-call.mjs WebSocket CLI.'
+description: "Test XR interactions covering ray, poke/touch, dual-mode, audio, and UI panel behaviors against the poke example via mcp-call.mjs WebSocket CLI. Use when testing VR/AR interaction handlers, validating poke or ray input, debugging spatial interactions, or verifying XR input modes in IWSDK."
 argument-hint: '[--suite ray|poke|dual|audio|ui|all]'
 ---
 

diff --git a/.claude/skills/test-level/SKILL.md b/.claude/skills/test-level/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-level
-description: 'Test level system (LevelRoot, LevelTag, default lighting, scene hierarchy) against the poke example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK level system covering LevelRoot, LevelTag, default lighting, and scene hierarchy against the poke example via mcp-call.mjs WebSocket CLI. Use when testing game levels, validating scene hierarchies, debugging level configurations, or verifying lighting setup in IWSDK applications."
 argument-hint: '[--suite root|tags|lighting|hierarchy|all]'
 ---
 

diff --git a/.claude/skills/test-locomotion/SKILL.md b/.claude/skills/test-locomotion/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-locomotion
-description: 'Test locomotion system (slide, snap turn, teleport, jump) against the locomotion example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK locomotion system covering slide, snap turn, teleport, and jump against the locomotion example via mcp-call.mjs WebSocket CLI. Use when testing VR movement systems, debugging player locomotion, validating teleport or snap turn behavior, or verifying locomotion controls in IWSDK."
 argument-hint: '[--suite slide|turn|teleport|jump|all]'
 ---
 

diff --git a/.claude/skills/test-physics/SKILL.md b/.claude/skills/test-physics/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-physics
-description: 'Test Havok physics system (gravity, rigid bodies, static vs dynamic) against the physics example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK Havok physics system covering gravity, rigid bodies, and static vs dynamic behavior against the physics example via mcp-call.mjs WebSocket CLI. Use when testing physics simulations, debugging Havok integration, validating rigid body behavior, or verifying collision detection in IWSDK."
 argument-hint: '[--suite gravity|static|force|all]'
 ---
 

diff --git a/.claude/skills/test-ui/SKILL.md b/.claude/skills/test-ui/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-ui
-description: 'Test UI system (PanelUI, ScreenSpace) against the poke example using mcp-call.mjs WebSocket CLI.'
+description: "Test IWSDK UI system covering PanelUI and ScreenSpace components against the poke example via mcp-call.mjs WebSocket CLI. Use when testing UI panels, debugging ScreenSpace layouts, validating panel rendering, or verifying UI component behavior in IWSDK applications."
 argument-hint: '[--suite panel|screenspace|follower|all]'
 ---
 

diff --git a/.claude/skills/xr-mode-test/SKILL.md b/.claude/skills/xr-mode-test/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: xr-mode-test
-description: Test XR session lifecycle and mode transitions. Use when verifying XR enter/exit behavior, testing mode-dependent features, or debugging session state issues.
+description: "Test XR session lifecycle and mode transitions including enter/exit and focus/blur events. Use when verifying VR/AR/WebXR session behavior, testing mode-dependent features, debugging session state issues, or validating immersive session initialization."
 disable-model-invocation: true
 ---
 

diff --git a/packages/starter-assets/claude-injections/skills/iwsdk-debug/SKILL.md b/packages/starter-assets/claude-injections/skills/iwsdk-debug/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: iwsdk-debug
-description: Debug continuous behavior in WebXR scenes — physics, animations, collisions, game loops, or any real-time interaction that happens too fast for an agent to observe. Uses ECS pause/step/snapshot/diff to freeze time and inspect state frame by frame.
+description: "Debug continuous behavior in WebXR scenes — physics, animations, collisions, game loops, or any real-time interaction that happens too fast for an agent to observe. Uses ECS pause/step/snapshot/diff to freeze time and inspect state frame by frame. Use when debugging WebXR physics glitches, animation stutters, collision detection issues, or stepping through game loop frames."
 argument-hint: [description of behavior to debug]
 ---
 

diff --git a/packages/starter-assets/claude-injections/skills/iwsdk-planner/SKILL.md b/packages/starter-assets/claude-injections/skills/iwsdk-planner/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: iwsdk-planner
-description: IWSDK project planning and best practices guide. Use when planning new IWSDK features, designing systems/components, reviewing IWSDK code architecture, or when the user asks about IWSDK patterns, ECS design, signals, or reactive programming in this codebase.
+description: "IWSDK project planning and best practices guide providing architectural patterns, code review checklists, and implementation guidelines. Use when planning new IWSDK features, designing systems/components, reviewing IWSDK code architecture, or when the user asks about IWSDK patterns, ECS design, signals, or reactive programming in this codebase."
 ---
 
 # IWSDK Project Planner

diff --git a/packages/starter-assets/claude-injections/skills/iwsdk-ui/SKILL.md b/packages/starter-assets/claude-injections/skills/iwsdk-ui/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: iwsdk-ui
-description: Develop and iterate on IWSDK PanelUI components. Use when the user wants to create, modify, debug, or improve UI panels in their IWSDK application. Covers UIKITML editing, full-screen preview with ScreenSpace, and visual verification.
+description: "Develop and iterate on IWSDK PanelUI components with UIKITML editing, full-screen ScreenSpace preview, and visual verification. Use when creating, modifying, debugging, or improving UI panels, dashboard interfaces, or widget layouts in IWSDK applications."
 argument-hint: [panel-name or description of changes]
 ---
 

diff --git a/pr_description.md b/pr_description.md
@@ -0,0 +1,44 @@
+Hey @felixtrz 👋
+
+I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:
+
+![Skill Review Score Card](score_card.png)
+
+| Skill | Before | After | Change |
+|-------|--------|-------|--------|
+| test-level | 47% | 89% | +42% |
+| test-ui | 59% | 95% | +36% |
+| test-grab | 55% | 89% | +34% |
+| test-environment | 55% | 81% | +26% |
+| test-all | 64% | 89% | +25% |
+| test-audio | 64% | 89% | +25% |
+| test-interactions | 64% | 89% | +25% |
+| test-locomotion | 75% | 100% | +25% |
+| test-ecs-core | 64% | 81% | +17% |
+| test-physics | 73% | 89% | +16% |
+| xr-mode-test | 88% | 100% | +12% |
+| iwsdk-debug | 91% | 100% | +9% |
+| click-target | 88% | 95% | +7% |
+
+<details>
+<summary>Changes made</summary>
+
+The main improvement across all skills was adding explicit **"Use when..."** trigger clauses to frontmatter descriptions. This is the single most impactful change for skill discoverability — it tells Claude exactly when to select each skill.
+
+**Specific changes:**
+- **Test skills (test-all, test-audio, test-ecs-core, test-environment, test-grab, test-interactions, test-level, test-locomotion, test-physics, test-ui):** Added "Use when..." clauses with natural language trigger terms (e.g., "testing VR movement systems", "debugging player locomotion") alongside the technical terms already present
+- **click-target:** Expanded trigger terms to include "tapping", "selecting", "VR/AR/WebXR" variations
+- **xr-mode-test:** Added "VR/AR/WebXR" alternative terms and "immersive session initialization" triggers
+- **iwsdk-debug:** Added explicit "Use when..." clause for debugging physics glitches, animation stutters, collision issues
+- **iwsdk-ui-panel:** Added specific capabilities ("ScreenSpace preview", "backdrop techniques", "creating panel layouts")
+- **iwsdk-ui:** Reorganized description to lead with capabilities, added "dashboard interfaces" and "widget layouts" trigger terms
+- **iwsdk-planner (both copies):** Added concrete action verbs ("providing architectural patterns, code review checklists, and implementation guidelines")
+- **All descriptions:** Normalized to quoted string format in frontmatter
+
+</details>
+
+Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.
+
+Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@rohan-tessl](https://github.com/rohan-tessl) - if you hit any snags.
+
+Thanks in advance 🙏