@leejungkiin/awkit 1.7.6 → 1.7.7

package/skills/threejs-helpers/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: threejs-helpers
+description: "Debug and visualization helpers in three.js Core Helpers (AxesHelper, GridHelper, CameraHelper, light helpers, SkeletonHelper, bounding box helpers, PlaneHelper, PolarGridHelper, ArrowHelper) and Addons Helpers (VertexNormalsHelper, VertexTangentsHelper, RectAreaLightHelper, LightProbeHelper, ViewHelper, OctreeHelper, TextureHelper, PositionalAudioHelper, AnimationPathHelper, RapierHelper). Use only for development and editor overlays—not for shipping art; for gizmo-style manipulation use threejs-controls."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Visualizing axes, grids, camera frusta, shadow cameras, light directions
+- Showing skeleton bones, bounding boxes, normals/tangents for mesh inspection
+- Light probe or rect area visualization via helper classes
+
+**IMPORTANT: helpers vs production meshes**
+
+- Helpers are **debug** objects; do not use as final scene geometry.
+
+**Trigger phrases include:**
+
+- "AxesHelper", "GridHelper", "CameraHelper", "SkeletonHelper", "VertexNormalsHelper"
+- "辅助线", "法线显示", "包围盒调试"
+
+## How to use this skill
+
+1. **Attach** helper to the object it describes (e.g., `CameraHelper(light.shadow.camera)`).
+2. **Update** when targets move — some helpers need per-frame refresh.
+3. **Gate behind debug flags** — remove helpers in production builds to save draw calls.
+4. **Performance** — helpers add draw calls; disable when profiling performance issues.
+5. **Addons** — import from `three/addons/helpers/...` paths per **threejs-dev-setup**.
+
+### Example: Debug flag pattern for conditional helpers
+
+```javascript
+import * as THREE from 'three';
+
+const DEBUG = import.meta.env.DEV; // Vite-style; adapt for your bundler
+const debugGroup = new THREE.Group();
+debugGroup.visible = DEBUG;
+scene.add(debugGroup);
+
+// Add helpers only in development
+if (DEBUG) {
+  debugGroup.add(new THREE.AxesHelper(5));
+  debugGroup.add(new THREE.GridHelper(10, 10));
+
+  // Shadow camera helper for directional light
+  const shadowHelper = new THREE.CameraHelper(directionalLight.shadow.camera);
+  debugGroup.add(shadowHelper);
+}
+
+// Toggle helpers at runtime via console or GUI
+// debugGroup.visible = !debugGroup.visible;
+```
+
+See [examples/workflow-light-camera-helpers.md](examples/workflow-light-camera-helpers.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Helpers | https://threejs.org/docs/AxesHelper.html |
+| Helpers | https://threejs.org/docs/GridHelper.html |
+| Helpers | https://threejs.org/docs/CameraHelper.html |
+| Helpers | https://threejs.org/docs/SkeletonHelper.html |
+
+## Scope
+
+- **In scope:** Core + Addons helpers for visualization.
+- **Out of scope:** Production meshes or shipping art (**threejs-geometries**, **threejs-lights**); orbit/transform gizmo behavior (**threejs-controls**); editor UX parity with DCC tools; physics debug beyond helper stubs.
+
+## Common pitfalls and best practices
+
+- Too many helpers obscures view—toggle per subsystem.
+- Wrong attachment parent misaligns helper transforms.
+- Helpers inherit scene graph transforms—parent under a debug group to batch hide/show.
+- Some helpers duplicate geometry cost; strip in production or use `#ifdef DEBUG` style flags.
+- `CameraHelper` for shadow cameras must reference `light.shadow.camera`, not the main view camera.
+
+## Documentation and version
+
+Helpers are listed under [Helpers](https://threejs.org/docs/#Helpers) (core) and **Addons → Helpers** in [three.js docs](https://threejs.org/docs/). They are for **debug** only; production meshes and lighting should use real geometry/lights (**threejs-geometries**, **threejs-lights**).
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link the helper class (`AxesHelper`, `CameraHelper`, …) being used.
+2. State that helpers are not shipping art—strip or gate behind debug flags.
+3. Pair shadow/light helpers with **threejs-lights** tuning workflows.
+4. Mention performance cost when many helpers are enabled.
+5. Import paths follow **threejs-dev-setup** addon conventions.
+
+## References
+
+- Manual (debug workflow context): https://threejs.org/manual/
+- Docs index (Helpers group): https://threejs.org/docs/#Helpers
+- Examples: https://threejs.org/docs/DirectionalLightHelper.html
+
+## Keywords
+
+**English:** helper, debug, axes, grid, skeleton, normals, light helper, three.js
+
+**中文：** 辅助、调试、坐标轴、网格、骨架、法线、Helper、three.js

package/skills/threejs-helpers/examples/workflow-light-camera-helpers.md

@@ -0,0 +1,13 @@
+# Workflow: shadow + camera debug
+
+## Steps
+
+1. `const ch = new THREE.CameraHelper(light.shadow.camera); scene.add(ch);`
+
+2. `const lh = new THREE.DirectionalLightHelper(light, size); scene.add(lh);`
+
+3. Remove helpers once shadow frustum is tuned (**threejs-lights**).
+
+4. Use `SkeletonHelper(boneRoot)` for skinning issues (**threejs-animation** / **threejs-objects**).
+
+Official pages: CameraHelper, DirectionalLightHelper.

package/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/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/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/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/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/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/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/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/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.