@leejungkiin/awkit 1.7.6 → 1.7.8

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.

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

package/skills/threejs-objects/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: threejs-objects
+description: "three.js scene graph objects: Object3D transforms and hierarchy, Group, Mesh, InstancedMesh, SkinnedMesh, BatchedMesh, LOD, Line/LineLoop/LineSegments, Points, Sprite, Bone, Skeleton, ClippingGroup; interaction via Raycaster, Layers masks, and EventDispatcher patterns. Use when building scene hierarchies, picking objects with Raycaster, or configuring instanced/skinned meshes; for pure vector math use threejs-math; for skeletal clips use threejs-animation."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Parent/child relationships, `position/rotation/scale`, `matrixAutoUpdate`, `updateMatrixWorld`
+- Choosing mesh types: static vs instanced vs skinned vs batched LOD
+- **Picking**: `Raycaster.setFromCamera`, `intersectObjects`, recursive flag, face/uv results
+- **Layers**: selective visibility for cameras/lights/objects
+
+**IMPORTANT: objects vs math**
+
+| Need | Skill |
+|------|--------|
+| Scene graph + picking | **threejs-objects** |
+| Box/ray math only | **threejs-math** |
+
+**Trigger phrases include:**
+
+- "Object3D", "InstancedMesh", "SkinnedMesh", "Raycaster", "layers"
+- "父子节点", "射线拾取", "图层"
+
+## How to use this skill
+
+1. **Compose** scenes with `Group` and transforms; minimize deep hierarchies where possible.
+2. **Instancing** — set per-instance matrices; understand `count` and frustum culling behavior.
+3. **SkinnedMesh** — bind skeleton; clips in **threejs-animation**; skinning material flags in **threejs-materials**.
+4. **Picking** — normalize device coords, set ray from camera, filter by layers, validate intersections are sorted by distance before processing.
+5. **Events** — `EventDispatcher` on custom objects; patterns only, not DOM frameworks.
+6. **Clipping** — `ClippingGroup` usage per docs when user needs sectional cuts.
+7. **Dispose** — call `dispose()` on geometries/materials/textures when removing objects permanently.
+
+### Example: Raycaster picking with validation
+
+```javascript
+import * as THREE from 'three';
+
+const raycaster = new THREE.Raycaster();
+const pointer = new THREE.Vector2();
+
+function onPointerMove(event) {
+  // Normalize device coordinates (-1 to +1)
+  pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
+  pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;
+}
+
+function pick(camera, scene) {
+  raycaster.setFromCamera(pointer, camera);
+  const intersections = raycaster.intersectObjects(scene.children, true);
+
+  // Validate: intersections are sorted by distance (nearest first)
+  if (intersections.length > 0) {
+    console.log('Nearest hit:', intersections[0].object.name,
+                'at distance:', intersections[0].distance);
+  }
+  return intersections;
+}
+```
+
+See [examples/workflow-raycaster-pick.md](examples/workflow-raycaster-pick.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Core | https://threejs.org/docs/Object3D.html |
+| Objects | https://threejs.org/docs/Mesh.html |
+| Objects | https://threejs.org/docs/InstancedMesh.html |
+| Core | https://threejs.org/docs/Raycaster.html |
+
+## Scope
+
+- **In scope:** Object3D graph, renderable object types, raycasting, layers, dispatcher basics.
+- **Out of scope:** Physics engines; XR input mapping (**threejs-webxr**).
+
+## Common pitfalls and best practices
+
+- Forgetting `updateMatrixWorld` before world-space ray tests on moved objects.
+- Raycaster without `layers` set picks unintended objects—set masks consistently on camera and objects.
+- InstancedMesh raycast hits need per-instance handling—check docs for your version.
+
+## Documentation and version
+
+`Object3D`, mesh types, `Raycaster`, and `Layers` are documented under [Objects](https://threejs.org/docs/#Objects) and [Core](https://threejs.org/docs/Raycaster.html) in [three.js docs](https://threejs.org/docs/). Behavior of picking and layers can shift slightly—link the exact page for the user’s three.js line.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `Object3D`, `Mesh`, `InstancedMesh`, `Raycaster`, or `Layers` as needed.
+2. Pair skeletal animation with **threejs-animation** and skinned mesh setup.
+3. Route pure linear-algebra questions without a scene graph to **threejs-math**.
+4. Route XR input to **threejs-webxr** when sessions/controllers are involved.
+5. Mention `dispose()` for geometries/materials when removing objects permanently.
+
+## References
+
+- https://threejs.org/docs/Object3D.html
+- https://threejs.org/docs/Raycaster.html
+- https://threejs.org/docs/Layers.html
+- https://threejs.org/docs/InstancedMesh.html
+
+## Keywords
+
+**English:** object3d, mesh, instancedmesh, skinnedmesh, raycaster, layers, scene graph, three.js
+
+**中文：** 场景图、Object3D、Mesh、实例化、骨骼网格、射线拾取、图层、three.js

package/skills/threejs-objects/examples/workflow-raycaster-pick.md

@@ -0,0 +1,17 @@
+# Workflow: pick mesh with Raycaster
+
+## Steps
+
+1. `const raycaster = new THREE.Raycaster(); const pointer = new THREE.Vector2();`
+
+2. On pointer event: `pointer.x = (x / width) * 2 - 1; pointer.y = -(y / height) * 2 + 1;`
+
+3. `raycaster.setFromCamera(pointer, camera);`
+
+4. `const hits = raycaster.intersectObjects(scene.children, true);` — tune recursive/layers.
+
+5. Read `hits[0].object`, `face`, `uv`, `distance` per application.
+
+6. Throttle on pointermove if needed for performance.
+
+Details: https://threejs.org/docs/Raycaster.html

package/skills/threejs-postprocessing/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: threejs-postprocessing
+description: "Addon screen-space post-processing for three.js using EffectComposer, Pass base class, RenderPass, and stock passes such as UnrealBloomPass, SSAOPass, SSRPass, BokehPass, OutlinePass, FXAAPass/SMAAPass, TAARenderPass, and ShaderPass; references the Shaders addon group for underlying shader modules. Use when building composer chains for bloom, SSAO, or other screen-space effects; not for basic renderer tone mapping alone (threejs-renderers)."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `EffectComposer`, `RenderPass`, stacking passes, resize of composer
+- Bloom, SSAO, SSR, DOF, outline, glitch, film grain, TAA—**addon** pass names
+- `ShaderPass` with shader modules from Addons **Shaders** group
+
+**IMPORTANT: postprocessing vs renderers vs node-tsl**
+
+| Pipeline | Skill |
+|----------|--------|
+| Classic composer + passes | **threejs-postprocessing** |
+| Renderer output color/tone only | **threejs-renderers** |
+| Node/TSL post nodes | **threejs-node-tsl** |
+
+**Trigger phrases include:**
+
+- "EffectComposer", "RenderPass", "UnrealBloomPass", "SSAOPass", "后期"
+- "泛光", "环境光遮蔽", "描边"
+
+## How to use this skill
+
+1. **Chain** — `RenderPass` → effect passes → output; ensure size matches renderer and DPR changes.
+2. **Resize** — call `composer.setSize` alongside renderer resize workflows.
+3. **Half-float** — many passes expect appropriate render target types; cite docs for your version.
+4. **Performance** — each pass has cost; profile with `renderer.info` to check draw calls and triangles.
+5. **Validate output** — render a simple test scene through the composer first to verify passes work before adding complexity.
+6. **Shader modules** — link Addons **Shaders** list instead of inlining huge GLSL in SKILL.
+7. **Output** — final pass should align color management with renderer (**threejs-renderers**).
+8. **Contrast** — mention core `PostProcessing` class separately to avoid name collision confusion.
+
+### Example: EffectComposer with bloom and debugging
+
+```javascript
+import * as THREE from 'three';
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+
+const bloomPass = new UnrealBloomPass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  1.5, // strength
+  0.4, // radius
+  0.85 // threshold
+);
+composer.addPass(bloomPass);
+
+// Resize handler — must match renderer size
+window.addEventListener('resize', () => {
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  composer.setSize(window.innerWidth, window.innerHeight);
+});
+
+// Render loop: use composer.render() instead of renderer.render()
+function animate() {
+  composer.render();
+}
+renderer.setAnimationLoop(animate);
+```
+
+See [examples/workflow-composer-bloom.md](examples/workflow-composer-bloom.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Postprocessing | https://threejs.org/docs/EffectComposer.html |
+| Postprocessing | https://threejs.org/docs/RenderPass.html |
+| Postprocessing | https://threejs.org/docs/UnrealBloomPass.html |
+| Shaders (addon modules) | https://threejs.org/docs/module-CopyShader.html |
+
+## Scope
+
+- **In scope:** Addon postprocessing passes and composer wiring; pointers to shader modules.
+- **Out of scope:** Custom full-screen pipeline design outside three docs; engine-level frame graphs.
+
+## Common pitfalls and best practices
+
+- Forgetting composer resize produces smeared or low-res effects.
+- Pass order matters—bloom often after main scene pass, outline may need masks.
+- Some passes need depth—ensure depth buffer availability per pass docs.
+
+## Documentation and version
+
+Addon passes live under [Postprocessing](https://threejs.org/docs/#Postprocessing) and **Shaders** modules in [three.js docs](https://threejs.org/docs/). Pass constructors and required buffers change across versions—link the specific pass page (e.g. `UnrealBloomPass`) rather than guessing uniform names.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `EffectComposer`, `RenderPass`, or the named pass (`SSAOPass`, …).
+2. Contrast **addon** composer stack with core `PostProcessing` + **threejs-node-tsl** when users mix terms.
+3. Require `setSize` on composer when **threejs-renderers** resizes.
+4. Point to **Shaders** group for raw shader modules used by `ShaderPass`.
+5. Warn about VR frame-time when stacking heavy passes (**threejs-webxr**).
+
+## References
+
+- https://threejs.org/docs/#Postprocessing
+- https://threejs.org/docs/EffectComposer.html
+- https://threejs.org/docs/RenderPass.html
+
+## Keywords
+
+**English:** effectcomposer, renderpass, bloom, ssao, ssr, outline, postprocessing, three.js
+
+**中文：** 后期、EffectComposer、泛光、SSAO、SSR、屏幕空间、three.js

package/skills/threejs-postprocessing/examples/workflow-composer-bloom.md

@@ -0,0 +1,15 @@
+# Workflow: minimal composer with bloom
+
+## Steps
+
+1. Create `EffectComposer(renderer)`.
+
+2. Add `RenderPass(scene, camera)`.
+
+3. Add `UnrealBloomPass` with strength/radius/threshold per [UnrealBloomPass](https://threejs.org/docs/UnrealBloomPass.html).
+
+4. In animation loop: `composer.render()` instead of `renderer.render` for the final path—or follow the exact pattern from current examples (some versions use `composer.render()` only).
+
+5. On resize: `composer.setSize(width, height)`.
+
+Verify against a known three.js example filename from the official repo for your version—API details shift between releases.