@leejungkiin/awkit 1.5.5 → 1.6.0

package/skill-packs/threejs/skills/threejs-lights/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: threejs-lights
+description: "three.js lighting: AmbientLight, HemisphereLight, DirectionalLight, PointLight, SpotLight, RectAreaLight, LightProbe, IESSpotLight, ProjectorLight, shadow subtypes, and addon helpers such as RectAreaLightUniformsLib, RectAreaLightTexturesLib, LightProbeGenerator, TiledLighting. Use when configuring direct/indirect light, shadows, probes, or area lights; for IES file loading use threejs-loaders; for node-based light graphs use threejs-node-tsl; for debug helpers use threejs-helpers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Enabling `castShadow` / `receiveShadow`, shadow map size, bias, normal bias, camera frusta for shadow casters
+- Physical lights: intensity, distance/decay, angle/penumbra for spots, rect area setup
+- `LightProbe` for irradiance-style probes; `IESSpotLight` with IES data
+
+**IMPORTANT: lights vs loaders vs node-tsl**
+
+| Topic | Skill |
+|-------|--------|
+| Light classes and shadows | **threejs-lights** |
+| Loading IES/HDR files | **threejs-loaders** |
+| LightNode / TSL lighting | **threejs-node-tsl** |
+
+**Trigger phrases include:**
+
+- "DirectionalLight", "SpotLight", "RectAreaLight", "castShadow", "shadow map"
+- "阴影", "点光源", "面光源", "LightProbe"
+
+## How to use this skill
+
+1. **Base recipe**: ambient/hemisphere fill + directional sun + local points/spots.
+2. **Shadows**: enable on renderer, mark casters/receivers, tune map size vs performance, adjust bias to remove acne/peter-panning.
+3. **RectArea**: initialize addon libs per docs page before using light type.
+4. **Probes**: place probes; generate data via addon generator when applicable; relate to materials env reflections (**threejs-materials**, **threejs-textures**).
+5. **IES**: load profile via loader skill, attach to `IESSpotLight` per docs.
+6. **Performance**: limit shadow-casting lights; use layers (**threejs-objects**) to exclude objects.
+
+### Example: Shadow setup with validation
+
+```javascript
+// 1. Enable shadows on renderer
+renderer.shadowMap.enabled = true;
+
+// 2. Configure light as shadow caster
+const light = new THREE.DirectionalLight(0xffffff, 1);
+light.castShadow = true;
+light.shadow.mapSize.set(2048, 2048);
+light.shadow.bias = -0.0001; // Adjust to remove shadow acne
+
+// 3. Validate: verify shadow appears before tuning bias
+// Set castShadow on meshes, receiveShadow on ground
+mesh.castShadow = true;
+ground.receiveShadow = true;
+```
+
+See [examples/workflow-directional-shadow.md](examples/workflow-directional-shadow.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Lights | https://threejs.org/docs/Light.html |
+| Directional | https://threejs.org/docs/DirectionalLight.html |
+| Spot | https://threejs.org/docs/SpotLight.html |
+| Rect area | https://threejs.org/docs/RectAreaLight.html |
+
+## Scope
+
+- **In scope:** Core lights, shadow maps, probes, listed addons for rect area and probe generation.
+- **Out of scope:** CSM deep theory (see addon Csm docs if user names it); baked lightmaps in DCC.
+
+## Common pitfalls and best practices
+
+- Shadow map resolution must match scene scale—tiny shadows on huge worlds look blocky.
+- Point light shadows are six-face expensive—use wisely.
+- `RectAreaLight` without required libs yields black or wrong shading—verify init.
+- Mismatched physical units (intensity vs exposure) with **threejs-renderers** tone mapping causes blown or dim scenes.
+- Shadow **bias** / **normalBias** trade-offs: acne vs peter-paning—tune with helper frusta (**threejs-helpers**).
+
+## Documentation and version
+
+Light and shadow classes live under [Lights](https://threejs.org/docs/#Lights) in [three.js docs](https://threejs.org/docs/). `RectAreaLight` and probe addons depend on extra init from **Addons → Lights**; IES profiles require **threejs-loaders** for file fetch before the light API is usable.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link the concrete light type (`DirectionalLight`, `SpotLight`, …) and shadow pages when shadows are on.
+2. Separate **IES loading** to **threejs-loaders** and **LightNode** topics to **threejs-node-tsl**.
+3. Give practical shadow map size / bias guidance with **threejs-helpers** for frustum visualization.
+4. Mention `renderer.shadowMap.enabled` alongside light `castShadow` (see **threejs-renderers**).
+5. Note performance cost of multiple shadow-casting lights.
+
+## References
+
+- https://threejs.org/docs/#Lights
+- https://threejs.org/docs/DirectionalLight.html
+- https://threejs.org/docs/SpotLight.html
+- https://threejs.org/docs/LightShadow.html
+
+## Keywords
+
+**English:** lights, shadows, directional, spotlight, rectarea, lightprobe, three.js
+
+**中文：** 灯光、阴影、平行光、聚光灯、面光源、LightProbe、three.js

package/skill-packs/threejs/skills/threejs-lights/examples/workflow-directional-shadow.md

@@ -0,0 +1,17 @@
+# Workflow: directional sun with shadows
+
+## Steps
+
+1. `renderer.shadowMap.enabled = true;` (**threejs-renderers**).
+
+2. Create `DirectionalLight`, `light.castShadow = true`, position and `target`.
+
+3. Tune `light.shadow.mapSize`, `camera` frustum on `light.shadow.camera` for your scene bounds.
+
+4. Mark meshes: `mesh.castShadow` / `receiveShadow` as needed.
+
+5. Adjust `bias` / `normalBias` if acne or peter-panning appears.
+
+6. Use `CameraHelper(light.shadow.camera)` temporarily (**threejs-helpers**).
+
+Official reference: https://threejs.org/docs/DirectionalLight.html

package/skill-packs/threejs/skills/threejs-loaders/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: threejs-loaders
+description: "three.js asset I/O using LoadingManager, Cache, FileLoader, image and texture loaders, GLTFLoader with DRACOLoader and KTX2Loader, and common format loaders under Addons; symmetric exporters such as GLTFExporter and texture/buffer exporters. Use when loading or exporting models, HDR, LUT, fonts, or compressed textures; for runtime Texture object parameters after load use threejs-textures; for scene graph placement use threejs-objects."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `GLTFLoader`, `DRACOLoader`, `KTX2Loader`, `FBXLoader`, `OBJLoader`, progress and error handling
+- `LoadingManager` for global progress, `Cache` for HTTP caching control
+- Export: `GLTFExporter`, `OBJExporter`, HDR/KTX2 export pipelines
+- IES, UltraHDR, or domain-specific loaders listed under Addons Loaders in docs
+
+**IMPORTANT: loaders vs textures**
+
+- **threejs-loaders** = fetch/decode/parse files into three objects.
+- **threejs-textures** = `Texture`/`DataTexture` parameters, sampling, PMREM after you already have image buffers.
+
+**IMPORTANT: loaders vs dev-setup**
+
+- Import path issues belong to **threejs-dev-setup**; this skill assumes imports resolve.
+
+**Trigger phrases include:**
+
+- "GLTFLoader", "DRACO", "KTX2", "LoadingManager", "export gltf"
+- "加载模型", "导出", "进度条"
+
+## How to use this skill
+
+1. **Pick loader** by format; prefer glTF for PBR interchange when possible.
+2. **Wire LoadingManager** for multi-asset batches; surface `onStart`/`onLoad`/`onProgress`/`onError`.
+3. **glTF + Draco**: instantiate `DRACOLoader`, set decoder path, attach to `GLTFLoader.setDRACOLoader` per current docs.
+4. **glTF + KTX2**: configure `KTX2Loader` with transcoder path and connect to `GLTFLoader` when using Basis textures.
+5. **Export**: use `GLTFExporter` with options matching round-trip needs; note large scenes and binary vs JSON.
+6. **Security**: only load user URLs with validation; mention CORS for cross-origin assets.
+7. **After load**: traverse scene for materials/meshes—hand off material tuning to **threejs-materials**.
+
+See [examples/workflow-gltf-draco.md](examples/workflow-gltf-draco.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Core Loaders | https://threejs.org/docs/LoadingManager.html |
+| Core Loaders | https://threejs.org/docs/GLTFLoader.html |
+| Addons Exporters | https://threejs.org/docs/GLTFExporter.html |
+| Addons Loaders | https://threejs.org/docs/DRACOLoader.html |
+
+Extended list: [references/official-sections.md](references/official-sections.md).
+
+## Scope
+
+- **In scope:** Loader and exporter classes, manager/cache, format choice, plugin wiring for Draco/KTX2, export basics.
+- **Out of scope:** Server-side transcoding pipelines; physics or game engine asset tooling outside three docs.
+
+## Common pitfalls and best practices
+
+- Draco/KTX2 **decoder paths** must match deployed files; broken paths fail silently until onError surfaces.
+- Duplicate texture instances after merge—consider `renderer.initTexture` implications when cloning materials.
+- Exporters may not round-trip custom shaders; document limitations.
+- Always dispose geometries/materials when replacing loaded scenes to avoid GPU leaks.
+
+## Documentation and version
+
+Loader and exporter APIs (especially `GLTFLoader` + `DRACOLoader` / `KTX2Loader` wiring) change between three.js versions. Follow [Loaders](https://threejs.org/docs/#Loaders) and **Addons → Loaders / Exporters** in [three.js docs](https://threejs.org/docs/); decoder WASM paths are deployment-specific, not library-version alone.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `LoadingManager`, `GLTFLoader`, or the relevant format page on https://threejs.org/docs/.
+2. Separate **loading** (this skill) from **texture/material tuning** after decode (**threejs-textures**, **threejs-materials**).
+3. Document Draco/KTX2 **decoder path** and CORS when assets fail silently.
+4. Mention exporter limitations (custom shaders, extensions) honestly.
+5. Encourage `dispose()` when replacing entire loaded scenes.
+
+## References
+
+- https://threejs.org/docs/#Loaders
+- https://threejs.org/docs/LoadingManager.html
+- https://threejs.org/docs/GLTFLoader.html
+- https://threejs.org/docs/GLTFExporter.html
+
+## Keywords
+
+**English:** gltf, gltfloader, dracoloader, ktx2, loadingmanager, cache, exporter, asset pipeline, three.js
+
+**中文：** GLTFLoader、加载器、Draco、KTX2、导出、资源、进度、three.js

package/skill-packs/threejs/skills/threejs-loaders/examples/workflow-gltf-draco.md

@@ -0,0 +1,22 @@
+# Workflow: GLTFLoader with DRACOLoader
+
+## Preconditions
+
+- **threejs-dev-setup** resolves `three/addons/loaders/GLTFLoader.js` and `DRACOLoader.js`.
+- Draco decoder WASM/js files are hosted at a known URL prefix (often copied to `public/draco/`).
+
+## Steps
+
+1. Create `DRACOLoader()` and `setDecoderPath('/draco/')` (adjust to deployment).
+
+2. Create `GLTFLoader()` and `loader.setDRACOLoader(dracoLoader)`.
+
+3. Call `loader.load('model.glb', onLoad, onProgress, onError)`.
+
+4. In `onLoad`, use `gltf.scene` as root **Object3D**; animations → **threejs-animation**; materials may need color pipeline checks → **threejs-renderers** / **threejs-textures**.
+
+5. Dispose previous scene graphs when swapping models.
+
+## Note
+
+Exact API names follow the current [GLTFLoader](https://threejs.org/docs/GLTFLoader.html) page—verify when upgrading three.js major versions.

package/skill-packs/threejs/skills/threejs-loaders/references/official-sections.md

@@ -0,0 +1,27 @@
+# Loaders and exporters (frequently used)
+
+**Core**
+
+- https://threejs.org/docs/Loader.html
+- https://threejs.org/docs/LoadingManager.html
+- https://threejs.org/docs/Cache.html
+- https://threejs.org/docs/FileLoader.html
+- https://threejs.org/docs/TextureLoader.html
+- https://threejs.org/docs/GLTFLoader.html
+
+**Addons (examples)**
+
+- https://threejs.org/docs/DRACOLoader.html
+- https://threejs.org/docs/KTX2Loader.html
+- https://threejs.org/docs/FBXLoader.html
+- https://threejs.org/docs/OBJLoader.html
+- https://threejs.org/docs/HDRLoader.html
+- https://threejs.org/docs/RGBELoader.html (if listed under HDRLoader migration in your version—check index)
+
+**Exporters**
+
+- https://threejs.org/docs/GLTFExporter.html
+- https://threejs.org/docs/OBJExporter.html
+- https://threejs.org/docs/EXRExporter.html
+
+Refresh against https://threejs.org/docs/#Loaders and **Addons → Exporters** for your installed version.

package/skill-packs/threejs/skills/threejs-materials/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: threejs-materials
+description: "Classic three.js materials (non-Node): MeshStandardMaterial, MeshPhysicalMaterial, Phong/Lambert/Toon/Basic, Line/Points/Sprite materials, MeshMatcapMaterial, MeshNormalMaterial, depth/distance materials, ShaderMaterial and RawShaderMaterial. Use when tuning PBR maps, transparency, depth write, skinning flags, or writing GLSL in ShaderMaterial; for TSL/NodeMaterial/WebGPU shader graphs use threejs-node-tsl instead."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Choosing among built-in mesh materials, map slots (albedo, normal, roughness, metalness, ao, emissive), `envMap`
+- Transparency sorting issues, `alphaTest`, `depthWrite`, blending modes, side/double-sided rendering
+- `ShaderMaterial` / `RawShaderMaterial` uniforms, includes, and compatibility with lights pipeline
+- Line, points, sprite materials for vector overlays and particles
+
+**IMPORTANT: classic materials vs node-tsl**
+
+| Need | Skill |
+|------|--------|
+| Standard PBR with maps, physical clearcoat/sheen | **threejs-materials** |
+| TSL nodes, `NodeMaterial`, WebGPU-first shading, compute-style graph | **threejs-node-tsl** |
+| Migrating ShaderMaterial → TSL | **threejs-node-tsl** (conceptual), keep ShaderMaterial here until cutover |
+
+**Trigger phrases include:**
+
+- "MeshStandardMaterial", "MeshPhysicalMaterial", "ShaderMaterial", "transparent", "alphaTest"
+- "PBR", "物理材质", "透明", "自定义着色器"
+
+## How to use this skill
+
+1. **Select class** by lighting model: `MeshBasic` (unlit), Lambert/Phong (legacy lit), Standard/Physical (PBR).
+2. **Assign maps** and ensure **color space** correctness for albedo vs data maps (link threejs-textures).
+3. **Environment**: set `envMap` from cube or equirect; align `metalness`/`roughness`; consider `MeshPhysicalMaterial` for transmission/IOR when needed.
+4. **Transparency**: order objects or use `alphaTest`/`depthWrite` trade-offs; mention sorting limitations.
+5. **ShaderMaterial**: minimize re-lit work unless intentional; document required lights and `lights: true` flag behavior per version docs.
+6. **Performance**: share materials across meshes; avoid cloning per frame.
+7. **Skinning/morph**: set `skinning`/`morphTargets` where applicable—mesh side in **threejs-objects**.
+
+### Example: Transparency with alphaTest vs depthWrite
+
+```javascript
+// Option A: alphaTest — hard cutoff, no sorting issues
+const matA = new THREE.MeshStandardMaterial({
+  map: texture, alphaMap: alphaTexture,
+  alphaTest: 0.5, transparent: true
+});
+
+// Option B: depthWrite false — soft transparency, needs manual sorting
+const matB = new THREE.MeshStandardMaterial({
+  map: texture, transparent: true, opacity: 0.6,
+  depthWrite: false // prevents depth-fighting but requires back-to-front sorting
+});
+```
+
+See [examples/workflow-pbr-transparent.md](examples/workflow-pbr-transparent.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Materials (core) | https://threejs.org/docs/Material.html |
+| PBR | https://threejs.org/docs/MeshStandardMaterial.html |
+| Physical | https://threejs.org/docs/MeshPhysicalMaterial.html |
+| Custom GLSL | https://threejs.org/docs/ShaderMaterial.html |
+
+## Scope
+
+- **In scope:** Non-Node materials listed under Core **Materials** in docs (except `*NodeMaterial`).
+- **Out of scope:** Full Nodes catalog (threejs-node-tsl); post pass materials inside composer (threejs-postprocessing).
+
+## Common pitfalls and best practices
+
+- Wrong normal map `normalMapType` or tangent space breaks lighting; verify geometry has tangents or use appropriate mode.
+- Premultiplied alpha vs straight alpha mismatches cause fringe halos on foliage.
+- `MeshPhysicalMaterial` `transmission` needs thickness and good env—combine with **threejs-textures** / PMREM.
+- Too many unique materials hurts sorting and batching—merge where possible.
+
+## Documentation and version
+
+PBR and `ShaderMaterial` behavior track the [Materials](https://threejs.org/docs/#Materials) section in [three.js docs](https://threejs.org/docs/). Color management and default `envMap` handling changed in modern releases—always pair material answers with renderer/output settings from **threejs-renderers** when colors look wrong.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `MeshStandardMaterial`, `MeshPhysicalMaterial`, or `ShaderMaterial` pages as appropriate.
+2. Force a clear choice vs **threejs-node-tsl** when the user asks for “shaders” or “nodes”.
+3. Separate map **roles** (albedo vs roughness vs normal) and `colorSpace` expectations with **threejs-textures**.
+4. Call out transparency and `depthWrite` trade-offs for sorted rendering.
+5. Note that `*NodeMaterial` types belong to the node skill, not this one.
+
+## References
+
+- https://threejs.org/docs/#Materials
+- https://threejs.org/docs/MeshStandardMaterial.html
+- https://threejs.org/docs/MeshPhysicalMaterial.html
+- https://threejs.org/docs/ShaderMaterial.html
+
+## Keywords
+
+**English:** meshstandardmaterial, meshphysicalmaterial, shadermaterial, pbr, transparency, envmap, materials, three.js
+
+**中文：** 材质、PBR、MeshStandardMaterial、物理材质、透明、环境贴图、ShaderMaterial、three.js

package/skill-packs/threejs/skills/threejs-materials/examples/workflow-pbr-transparent.md

@@ -0,0 +1,15 @@
+# Workflow: PBR mesh with transparency
+
+## Steps
+
+1. Start from `MeshStandardMaterial` with `transparent: true`, `opacity < 1`, or texture alpha.
+
+2. Decide sorting strategy: opaque first, then transparent; or use `alphaTest` for cutouts (foliage).
+
+3. For refractive glass-like look, consider `MeshPhysicalMaterial` with `transmission`—verify thickness and env map (see **threejs-textures** for PMREM).
+
+4. If depth artifacts appear, tune `depthWrite` (often `false` for transparent) and render order.
+
+5. Validate under correct `outputColorSpace` on renderer (**threejs-renderers**).
+
+This file is guidance only—parameter names follow the current [MeshStandardMaterial](https://threejs.org/docs/MeshStandardMaterial.html) page.

package/skill-packs/threejs/skills/threejs-math/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: threejs-math
+description: "three.js math library: Vector2/3/4, Matrix3/4, Quaternion, Euler, Color, Box2/Box3, Sphere, Plane, Ray, Line3, Triangle, Frustum, Cylindrical/Spherical coords, MathUtils, and Interpolant base classes; addon math utilities such as OBB, Octree, Capsule, ConvexHull, MeshSurfaceSampler. Use for transforms, intersection tests, and spatial queries; for keyframe interpolation tied to AnimationMixer use threejs-animation; for picking implementation use threejs-objects with Raycaster."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Vector/matrix math order, `applyQuaternion`, `lookAt`, world vs local transforms
+- Bounding volumes `Box3`/`Sphere`, containment/intersection tests
+- `Ray` vs `Plane` vs `Frustum` tests (without full picking pipeline)
+
+**IMPORTANT: math vs objects vs animation**
+
+| Need | Skill |
+|------|--------|
+| Raw math types | **threejs-math** |
+| `Raycaster` + layers picking | **threejs-objects** |
+| QuaternionKeyframeTrack playback | **threejs-animation** |
+
+**Trigger phrases include:**
+
+- "Vector3", "Matrix4", "Quaternion", "Box3", "Ray", "Frustum"
+- "向量", "矩阵", "四元数", "包围盒"
+
+## How to use this skill
+
+1. **Conventions**: multiply vectors by matrices on the left as three.js examples show; call `updateMatrixWorld` before world-space queries (**threejs-objects**).
+2. **Bounding**: `Box3().setFromObject(object)` for rough bounds; refine per need.
+3. **Collision-ish checks**: `ray.intersectBox`, `sphere.containsPoint`, etc., per docs.
+4. **Addon structures**: `Octree`/`OBB` for games—cite addon pages, avoid copying full API tables here.
+5. **Color**: `Color` conversions relate to materials/textures—cross-link.
+6. **Random sampling**: `MeshSurfaceSampler` for distributing points on meshes.
+
+### Example: Ray-AABB intersection test
+
+```javascript
+import * as THREE from 'three';
+
+const ray = new THREE.Ray(
+  new THREE.Vector3(0, 1, 0),  // origin
+  new THREE.Vector3(0, 0, -1)  // direction
+);
+const box = new THREE.Box3(
+  new THREE.Vector3(-1, -1, -5),
+  new THREE.Vector3(1, 1, -3)
+);
+
+const hit = ray.intersectBox(box, new THREE.Vector3());
+if (hit) {
+  console.log('Intersection at:', hit);
+}
+```
+
+See [examples/workflow-ray-aabb.md](examples/workflow-ray-aabb.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Math | https://threejs.org/docs/Vector3.html |
+| Math | https://threejs.org/docs/Matrix4.html |
+| Math | https://threejs.org/docs/Quaternion.html |
+| Math | https://threejs.org/docs/Ray.html |
+
+## Scope
+
+- **In scope:** Core Math types; addon math entries as pointers.
+- **Out of scope:** Keyframe track evaluation beyond type references (animation skill).
+
+## Common pitfalls and best practices
+
+- Euler gimbal lock—prefer quaternions for arbitrary rotations.
+- Reusing temporary vectors reduces GC thrash in hot loops.
+- Frustum culling helpers vary—verify against your three version.
+
+## Documentation and version
+
+Core math types are listed under [Math](https://threejs.org/docs/#Math); addon utilities (`Octree`, `OBB`, …) appear under **Addons → Math** in [three.js docs](https://threejs.org/docs/). [Global](https://threejs.org/docs/#Global) also lists constants (e.g. wrapping, blending) sometimes needed alongside materials.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link the concrete type (`Vector3`, `Matrix4`, `Quaternion`, …) from the docs.
+2. Send `AnimationMixer` / track math to **threejs-animation** when time-sampled.
+3. Send `Raycaster` picking flows to **threejs-objects** when interaction is the goal.
+4. Mention numeric stability (epsilon) where comparisons matter.
+5. Point to **Addons → Math** for game-oriented structures when users need spatial acceleration.
+
+## References
+
+- https://threejs.org/docs/#Math
+- https://threejs.org/docs/MathUtils.html
+- https://threejs.org/docs/Ray.html
+
+## Keywords
+
+**English:** vector, matrix, quaternion, euler, box3, sphere, ray, frustum, three.js
+
+**中文：** 向量、矩阵、四元数、欧拉角、包围盒、射线、three.js

package/skill-packs/threejs/skills/threejs-math/examples/workflow-ray-aabb.md

@@ -0,0 +1,11 @@
+# Workflow: test Ray against Box3
+
+## Steps
+
+1. Build `THREE.Ray(origin, direction)`; ensure `direction` is normalized if using distance-sensitive APIs.
+
+2. Compute world-space `Box3` for an object: `new THREE.Box3().setFromObject(mesh)`.
+
+3. `const hit = ray.intersectBox(box, targetPoint);` — check return value per [Ray](https://threejs.org/docs/Ray.html).
+
+4. For mesh-accurate picking, prefer `Raycaster` in **threejs-objects** instead of manual triangle tests unless you optimize custom cases.

package/skill-packs/threejs/skills/threejs-node-tsl/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: threejs-node-tsl
+description: "three.js node-based shading: Nodes API surface, NodeMaterial and MeshStandardNodeMaterial-style families, TSL (Three.js Shading Language) entry at TSL.html, WebGPURenderer pairing, and core PostProcessing (class) versus addon EffectComposer at a high level. Use when authoring shaders as graphs, using TSL builtins, compute-oriented nodes, or modern WebGPU pipelines; for classic ShaderMaterial GLSL use threejs-materials; for stock EffectComposer passes use threejs-postprocessing; for WebGLRenderer-only tuning use threejs-renderers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `NodeMaterial`, `TSL`, imports from `three/nodes` or WebGPU entry points in docs
+- Building materials or post effects from nodes instead of string GLSL
+- `WebGPURenderer`, `PostProcessing` (core class) in a node-centric pipeline
+
+**IMPORTANT: node-tsl vs materials vs postprocessing**
+
+| Situation | Skill |
+|-----------|--------|
+| Standard PBR tuning, no nodes | **threejs-materials** |
+| TSL graph, NodeMaterial, WGSL path | **threejs-node-tsl** |
+| Classic `EffectComposer` + Pass classes | **threejs-postprocessing** |
+| Node post passes listed under Addons TSL in docs | **threejs-node-tsl** + **threejs-postprocessing** awareness |
+
+**Trigger phrases include:**
+
+- "TSL", "NodeMaterial", "three/nodes", "WebGPU", "node builder"
+- "节点材质", "着色语言 TSL"
+
+## How to use this skill
+
+1. **Decide path**: WebGPU + nodes vs WebGL + classic materials—do not hybridize blindly.
+2. **Anchor docs**: start from [Nodes index](https://threejs.org/docs/#Nodes) and [TSL.html](https://threejs.org/docs/TSL.html); use [NodeMaterial](https://threejs.org/docs/NodeMaterial.html) for material entry.
+3. **Progressive disclosure**: keep SKILL.md navigational; long symbol lists live in [references/official-links.md](references/official-links.md) and [references/tsl-vs-classic.md](references/tsl-vs-classic.md); see [examples/workflow-tsl-entry.md](examples/workflow-tsl-entry.md) for navigation habits.
+4. **Renderer**: enable `WebGPURenderer` per docs; fall back notes belong in **threejs-renderers**.
+5. **Debugging**: use version-stamped examples in three.js repo; avoid copying deprecated import paths.
+6. **Post stack**: if user names `PostProcessing` core class vs addon composer, clarify table in **threejs-renderers** / **threejs-postprocessing**.
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Nodes | https://threejs.org/docs/#Nodes |
+| TSL | https://threejs.org/docs/TSL.html |
+| NodeMaterial | https://threejs.org/docs/NodeMaterial.html |
+| WebGPU renderer | https://threejs.org/docs/WebGPURenderer.html |
+
+## Scope
+
+- **In scope:** Nodes/TSL discovery, architecture, renderer pairing, where to look next, migration hints from ShaderMaterial.
+- **Out of scope:** Pasting entire TSL symbol tables into SKILL.md; guaranteeing API stability across rapid releases—always cite "current docs".
+
+## Common pitfalls and best practices
+
+- Three.js node APIs evolve quickly—tie answers to a **version** or "current docs".
+- Do not confuse **core** `PostProcessing` class with **addons** `EffectComposer`—names collide in conversation.
+- WGSL vs GLSL expectations differ; TSL abstracts but limits still apply.
+- Keep graphs modular; use references for lookup instead of bloating agent context.
+
+## Documentation and version
+
+The [Nodes](https://threejs.org/docs/#Nodes) index and [TSL](https://threejs.org/docs/TSL.html) page are large and **fast-moving**. Treat https://threejs.org/docs/ as the source of truth for the user’s installed three.js; prefer linking [NodeMaterial](https://threejs.org/docs/NodeMaterial.html) and [WebGPURenderer](https://threejs.org/docs/WebGPURenderer.html) over paraphrasing long symbol lists.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Anchor on [TSL.html](https://threejs.org/docs/TSL.html) and/or `#Nodes` rather than inventing API names.
+2. Contrast **threejs-materials** (classic) vs node/TSL path explicitly.
+3. Warn that WebGPU + nodes examples may require recent minors—cite version when known.
+4. Point to [references/tsl-vs-classic.md](references/tsl-vs-classic.md) and [references/official-links.md](references/official-links.md) for long lookups.
+5. Disambiguate core `PostProcessing` vs addon `EffectComposer` (**threejs-postprocessing**).
+
+## References
+
+- https://threejs.org/docs/#Nodes
+- https://threejs.org/docs/TSL.html
+- https://threejs.org/docs/NodeMaterial.html
+- https://threejs.org/docs/WebGPURenderer.html
+
+## Keywords
+
+**English:** tsl, node material, nodes, webgpu, wgsl, three.js shading language, node builder, nodematerial
+
+**中文：** TSL、节点材质、WebGPU、着色语言、NodeMaterial、three.js

package/skill-packs/threejs/skills/threejs-node-tsl/examples/workflow-tsl-entry.md

@@ -0,0 +1,13 @@
+# Workflow: finding the right TSL entry
+
+## Steps
+
+1. Open https://threejs.org/docs/TSL.html and locate the function or node category matching the effect (lighting, texture, math).
+
+2. Cross-check [Nodes](https://threejs.org/docs/#Nodes) for class-style nodes if TSL links to underlying node types.
+
+3. Pair with `WebGPURenderer` setup from **threejs-renderers**.
+
+4. For post effects expressed as nodes, compare with addon `EffectComposer` path in **threejs-postprocessing** and pick one pipeline per project.
+
+Do not duplicate upstream example code here—link to the official example filename instead.

package/skill-packs/threejs/skills/threejs-node-tsl/references/official-links.md

@@ -0,0 +1,8 @@
+# Official entry points (Nodes / TSL)
+
+Use these pages as the source of truth; the Nodes catalog is large—link out instead of duplicating.
+
+- https://threejs.org/docs/#Nodes
+- https://threejs.org/docs/TSL.html
+- https://threejs.org/docs/NodeMaterial.html
+- https://threejs.org/docs/Node.html

package/skill-packs/threejs/skills/threejs-node-tsl/references/tsl-vs-classic.md

@@ -0,0 +1,23 @@
+# TSL / NodeMaterial vs classic materials
+
+## When to prefer classic (`threejs-materials`)
+
+- You need widely documented PBR with `MeshStandardMaterial` / `MeshPhysicalMaterial`.
+- Target is WebGL-only deployments without WebGPU.
+- Team maintains GLSL `ShaderMaterial` with known light setups.
+
+## When to prefer TSL / Node path (`threejs-node-tsl`)
+
+- You adopt `WebGPURenderer` and node-based materials in examples.
+- You want composable shader pieces without huge GLSL strings.
+- You follow new three.js examples that import from node/TSL modules.
+
+## Migration sanity
+
+- Rebuild lighting model expectations: not every classic knob maps 1:1 on day one.
+- Keep references to official migration notes in the three.js repository for your version.
+
+## Links
+
+- https://threejs.org/docs/TSL.html
+- https://threejs.org/docs/ShaderMaterial.html