@leejungkiin/awkit 1.5.5 → 1.6.0

package/skill-packs/threejs/skills/threejs-audio/examples/workflow-positional-audio.md

@@ -0,0 +1,15 @@
+# Workflow: positional loop with loader
+
+## Steps
+
+1. Create `AudioListener`, `camera.add(listener)`.
+
+2. `const sound = new THREE.PositionalAudio(listener);`
+
+3. `const loader = new THREE.AudioLoader();` (**threejs-loaders**) `loader.load('file.ogg', buffer => { sound.setBuffer(buffer); sound.setRefDistance(1); sound.play(); });`
+
+4. Add `sound` as child of moving mesh or update position each frame.
+
+5. Connect `AudioAnalyser` only if visualization required—extra CPU.
+
+Browser autoplay: resume context on first click if needed.

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

@@ -0,0 +1,16 @@
+# Audio module (core)
+
+Index: https://threejs.org/docs/#Audio
+
+- https://threejs.org/docs/AudioListener.html
+- https://threejs.org/docs/Audio.html
+- https://threejs.org/docs/PositionalAudio.html
+- https://threejs.org/docs/AudioAnalyser.html
+
+**Loaders (decode buffers — see skill `threejs-loaders`)**
+
+- https://threejs.org/docs/AudioLoader.html
+
+**Addons (positional helper)**
+
+- https://threejs.org/docs/PositionalAudioHelper.html

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

@@ -0,0 +1,96 @@
+---
+name: threejs-camera
+description: "three.js cameras: Camera base, PerspectiveCamera, OrthographicCamera, CubeCamera, ArrayCamera, StereoCamera; projection matrices, aspect, FOV, orthographic frustum sizes, near/far planes, and dynamic environment maps with CubeCamera. Use when placing views, rendering reflections, or multi-view splits; for XR projections and eye matrices use threejs-webxr; for post pass camera tricks use threejs-postprocessing alongside threejs-renderers."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Switching perspective vs orthographic, `fov`, `aspect`, `zoom`, `near`, `far`
+- `CubeCamera` for real-time environment maps or reflections (update rate caveats)
+- `ArrayCamera`/`StereoCamera` for multi-view or stereo off-axis projection (non-XR)
+
+**IMPORTANT: camera vs webxr vs post**
+
+| Topic | Skill |
+|-------|--------|
+| Standard desktop projection | **threejs-camera** |
+| XR reference spaces, IPD | **threejs-webxr** |
+| Offscreen pass cameras inside composer | **threejs-postprocessing** |
+
+**Trigger phrases include:**
+
+- "PerspectiveCamera", "OrthographicCamera", "CubeCamera", "aspect", "near", "far"
+- "透视相机", "正交", "立方体相机"
+
+## How to use this skill
+
+1. **Perspective**: set `aspect` = width/height; update on resize (**threejs-renderers** example workflow).
+2. **Orthographic**: define `left/right/top/bottom` in world units for CAD/2.5D views.
+3. **Near/far**: balance depth precision vs containing scene bounds; relate to fog (**threejs-scenes**).
+4. **CubeCamera**: position at reflection probe; call `update` when scene static enough; use render target outputs per docs.
+5. **Stereo/Array**: advanced; cite docs for eye parameters; defer XR to **threejs-webxr**.
+6. **Projection matrix**: call `updateProjectionMatrix()` after parameter edits.
+7. **Helpers**: `CameraHelper` lives in **threejs-helpers**.
+
+### Example: Resize handler with updateProjectionMatrix
+
+```javascript
+window.addEventListener('resize', () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+See [examples/workflow-perspective-resize.md](examples/workflow-perspective-resize.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Cameras (index) | https://threejs.org/docs/#Cameras |
+| Cameras | https://threejs.org/docs/Camera.html |
+| Perspective | https://threejs.org/docs/PerspectiveCamera.html |
+| Orthographic | https://threejs.org/docs/OrthographicCamera.html |
+| Cube | https://threejs.org/docs/CubeCamera.html |
+| Multi-view | https://threejs.org/docs/ArrayCamera.html |
+| Stereo (non-XR) | https://threejs.org/docs/StereoCamera.html |
+
+## Scope
+
+- **In scope:** Core camera classes and parameters; cube/array/stereo overview.
+- **Out of scope:** WebXR reference spaces, eye matrices, session lifecycle (**threejs-webxr**); shadow map camera tuning (**threejs-lights**); pass-internal cameras in composer (**threejs-postprocessing**).
+
+## Common pitfalls and best practices
+
+- Wrong `aspect` after resize stretches image—always sync with canvas.
+- Too small `near` hurts depth precision in large worlds.
+- `CubeCamera` every frame is expensive—throttle for performance.
+
+## Documentation and version
+
+Camera parameters and `CubeCamera` update behavior follow the [Cameras](https://threejs.org/docs/#Cameras) section of [three.js docs](https://threejs.org/docs/). WebXR uses different projection paths—hand off to **threejs-webxr** when the user mentions headsets or reference spaces.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `PerspectiveCamera`, `OrthographicCamera`, or `CubeCamera` as relevant.
+2. Pair resize with **threejs-renderers** `setSize` / DPR patterns when relevant.
+3. Route `XR`/`WebXRManager` questions to **threejs-webxr** after one-line renderer mention.
+4. Mention `updateProjectionMatrix()` after intrinsic changes.
+5. Use **threejs-helpers** `CameraHelper` for shadow frustum debug when discussing lights.
+
+## References
+
+- https://threejs.org/docs/#Cameras
+- https://threejs.org/docs/PerspectiveCamera.html
+- https://threejs.org/docs/CubeCamera.html
+
+## Keywords
+
+**English:** perspectivecamera, orthographiccamera, cubecamera, projection, aspect, near, far, three.js
+
+**中文：** 相机、透视、正交、投影、近裁剪、远裁剪、CubeCamera、three.js

package/skill-packs/threejs/skills/threejs-camera/examples/workflow-perspective-resize.md

@@ -0,0 +1,13 @@
+# Workflow: perspective camera on window resize
+
+## Steps
+
+1. Store `PerspectiveCamera` reference.
+
+2. On resize: `camera.aspect = width / height; camera.updateProjectionMatrix();`
+
+3. Pair with renderer `setSize` from **threejs-renderers** examples.
+
+4. For orthographic cameras, recompute `left/right/top/bottom` if using fit-to-view logic.
+
+This is the standard pattern used across three.js examples.

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

@@ -0,0 +1,101 @@
+---
+name: threejs-controls
+description: "Addon camera and object manipulation controls: OrbitControls, MapControls, FlyControls, FirstPersonControls, TrackballControls, ArcballControls, DragControls, PointerLockControls, TransformControls; damping, target focal point, and integration with the animation loop. Use for editor-style navigation and gizmos—not a full game character controller stack; pair with Raycaster selection patterns in threejs-objects when transforming selections."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Orbiting/panning/dolly around a target, inertia/damping, min/max distance/polar angles
+- Map-like pan (MapControls) or flying (FlyControls)
+- Transform gizmo translate/rotate/scale with `TransformControls`
+- Dragging objects in plane (DragControls), pointer lock FPS (PointerLockControls)
+
+**IMPORTANT: controls vs webxr**
+
+| Context | Skill |
+|---------|--------|
+| Desktop/browser camera nav | **threejs-controls** |
+| XR controller poses | **threejs-webxr** |
+
+**Trigger phrases include:**
+
+- "OrbitControls", "TransformControls", "MapControls", "PointerLockControls"
+- "轨道", "变换控制器", "漫游"
+
+## How to use this skill
+
+1. **Import** from addons path (**threejs-dev-setup**).
+2. **Construct** with `(camera, domElement)`; for `TransformControls` also attach to renderer events.
+3. **Animation loop**: when `enableDamping`, call `controls.update()` each frame.
+4. **TransformControls**: wire `dragging-changed` to disable Orbit temporarily; sync with selection from **threejs-objects**.
+5. **Constraints**: set min/max distance/angles to avoid flipping or underground views.
+6. **Dispose**: `controls.dispose()` when tearing down.
+
+### Example: OrbitControls with damping
+
+```javascript
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.dampingFactor = 0.05;
+controls.minDistance = 2;
+controls.maxDistance = 50;
+
+// Must call update() each frame when damping is enabled
+function animate() {
+  controls.update();
+  renderer.render(scene, camera);
+}
+renderer.setAnimationLoop(animate);
+```
+
+See [examples/workflow-orbit-damping.md](examples/workflow-orbit-damping.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Controls | https://threejs.org/docs/OrbitControls.html |
+| Controls | https://threejs.org/docs/TransformControls.html |
+| Controls | https://threejs.org/docs/MapControls.html |
+| Controls (index) | https://threejs.org/docs/#Controls |
+
+## Scope
+
+- **In scope:** Official addons controls usage patterns.
+- **Out of scope:** Full physics character motor; mobile gesture frameworks.
+
+## Common pitfalls and best practices
+
+- Forgetting `update()` with damping enabled causes drift never settling.
+- TransformControls fighting with Orbit—pause one while using the other.
+- Pointer lock requires user gesture and exit handling.
+
+## Documentation and version
+
+Controls are under [Controls](https://threejs.org/docs/#Controls) (Addons) in [three.js docs](https://threejs.org/docs/). API details (`enableDamping`, events) evolve—link `OrbitControls` / `TransformControls` pages for the user’s three.js version.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link the specific controls class from the docs.
+2. State `controls.update()` when damping is on, every frame.
+3. Coordinate `TransformControls` with selection / **threejs-objects** raycasting.
+4. Separate desktop navigation from **threejs-webxr** locomotion.
+5. Call `dispose()` on controls when unmounting canvas.
+
+## References
+
+- https://threejs.org/docs/#Controls
+- https://threejs.org/docs/OrbitControls.html
+- https://threejs.org/docs/TransformControls.html
+
+## Keywords
+
+**English:** orbitcontrols, transformcontrols, mapcontrols, damping, camera controls, three.js
+
+**中文：** OrbitControls、轨道、TransformControls、变换控制器、阻尼、three.js

package/skill-packs/threejs/skills/threejs-controls/examples/workflow-orbit-damping.md

@@ -0,0 +1,15 @@
+# Workflow: OrbitControls with damping
+
+## Steps
+
+1. `const controls = new OrbitControls(camera, renderer.domElement);`
+
+2. `controls.enableDamping = true; controls.dampingFactor = 0.05;`
+
+3. Each frame before render: `controls.update();`
+
+4. Listen to `controls.addEventListener('change', render)` only if using lazy rendering; continuous apps already render in rAF.
+
+5. On destroy: `controls.dispose()`.
+
+API: https://threejs.org/docs/OrbitControls.html

package/skill-packs/threejs/skills/threejs-dev-setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: threejs-dev-setup
+description: "Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders)."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Creating or configuring a new three.js project, Vite/Webpack/Rollup entry, or browser `importmap`
+- Installing the `three` package, aligning version with documentation, or TypeScript setup (`@types/three` where applicable)
+- Import errors for `three/addons/...`, `examples/jsm`, ESM vs CJS interop, or bare specifier resolution
+
+**IMPORTANT: this skill vs runtime topics**
+
+- **threejs-dev-setup** = install paths, bundler, module graph, and where to import addons from.
+- **threejs-renderers** = `WebGLRenderer` / `WebGPURenderer`, canvas, pixel ratio, render loop—after the project loads.
+- **threejs-loaders** = `GLTFLoader`, `DRACOLoader`, progress callbacks—after imports resolve.
+
+**Trigger phrases include:**
+
+- "vite three.js", "webpack three", "import map", "three/addons", "cannot find module", "jsm"
+- "新建项目", "安装 three", "找不到模块", "ESM", "TypeScript three"
+
+## How to use this skill
+
+1. **Confirm delivery model**: SPA bundler (Vite/Webpack), Node tooling, or static HTML with `importmap`—each affects how `three/addons/` resolves.
+2. **Pin `three` version** to a release compatible with the docs the user cites; note that addon paths follow the published package layout.
+3. **Show canonical imports**: core from `three`; controls/loaders/effects from `three/addons/...` (mapped to `examples/jsm` in source tree). See [examples/workflow-scaffold.md](examples/workflow-scaffold.md).
+4. **Minimal loop**: create renderer + scene + camera + one mesh to verify toolchain works.
+5. **TypeScript**: enable `moduleResolution` appropriate for bundler; reference types from `three` package typings; avoid duplicating global script tag patterns unless user targets no-bundler HTML.
+6. **On failure**: distinguish missing dependency vs wrong path vs SSR context (no `window`/`document`).
+7. **Deepening**: link user to [three.js manual](https://threejs.org/manual/) first chapter after scaffold works.
+
+### Example: Vite + three.js minimal verification
+
+```bash
+npm create vite@latest my-3d-app -- --template vanilla && cd my-3d-app
+npm install three
+```
+
+```javascript
+// main.js — canonical imports and minimal render loop
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, innerWidth / innerHeight, 0.1, 100);
+camera.position.z = 3;
+
+const renderer = new THREE.WebGLRenderer();
+renderer.setSize(innerWidth, innerHeight);
+document.body.appendChild(renderer.domElement);
+
+const mesh = new THREE.Mesh(
+  new THREE.BoxGeometry(),
+  new THREE.MeshStandardMaterial({ color: 0x00ff00 })
+);
+scene.add(mesh, new THREE.AmbientLight(0xffffff, 0.5));
+
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
+```
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Manual (getting started) | https://threejs.org/manual/ |
+| Docs index | https://threejs.org/docs/ |
+| Package / install context | https://www.npmjs.com/package/three |
+
+## Scope
+
+- **In scope:** npm/install, bundlers, import maps, TypeScript basics for three, addon import paths, minimal verification snippet.
+- **Out of scope:** WebGL theory, full render target or post stack (threejs-renderers, threejs-postprocessing), physics, deployment beyond "build runs".
+
+## Common pitfalls and best practices
+
+- Mixing multiple `three` copies in one page breaks singletons; dedupe with bundler aliases.
+- Importing addons from deep `node_modules/.../examples/jsm` paths is fragile; prefer package exports `three/addons/...` when available.
+- Always match **r152+** style color management docs when giving snippet defaults (output color space)—point to threejs-renderers/textures for details.
+- SSR frameworks need dynamic import or client-only components for WebGL context.
+
+## Documentation and version
+
+Toolchain and import paths follow the **three** npm package version the user installs. The [Manual](https://threejs.org/manual/) and [docs](https://threejs.org/docs/) are updated with the library; addon paths (`three/addons/...`) must match the package layout for that release—when in doubt, cite the version number and the exact import line from the current docs.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Name the bundler or runtime (Vite, Webpack, bare ESM, `importmap`) and the intended `three` version.
+2. Link https://threejs.org/manual/ and/or https://threejs.org/docs/ for authoritative setup context.
+3. Distinguish **threejs-dev-setup** (resolution) from **threejs-renderers** (runtime API) failures.
+4. Never assume global script tags unless the user explicitly uses CDN/no-bundler HTML.
+5. Recommend deduplicating `three` in `package.json` / lockfile when duplicate singleton issues appear.
+
+## Keywords
+
+**English:** three.js, vite, webpack, rollup, import map, typescript, npm, three/addons, examples jsm, module resolution, scaffold
+
+**中文：** three.js 安装、构建、importmap、模块解析、three/addons、脚手架、Vite、Webpack

package/skill-packs/threejs/skills/threejs-dev-setup/examples/workflow-scaffold.md

@@ -0,0 +1,24 @@
+# Workflow: minimal scaffold (toolchain check)
+
+Use after `three` is installed and the bundler resolves `three` and `three/addons/...`.
+
+## Steps
+
+1. Import core and one addon (e.g. `OrbitControls`) using your bundler’s supported syntax.
+
+```javascript
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+```
+
+2. Create `WebGLRenderer`, append `domElement`, size to canvas container.
+
+3. Create `Scene`, `PerspectiveCamera`, add a `Mesh` with `BoxGeometry` + `MeshStandardMaterial`.
+
+4. Instantiate `OrbitControls(camera, renderer.domElement)` and drive `requestAnimationFrame` calling `controls.update()` then `renderer.render(scene, camera)`.
+
+5. If this runs without module errors, **threejs-dev-setup** is satisfied; tune color space and lighting via **threejs-renderers** and **threejs-lights**.
+
+## Official examples (reference only)
+
+Browse live examples under the three.js repository `examples/`—do not paste entire files; pick patterns matching your bundler.

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

@@ -0,0 +1,108 @@
+---
+name: threejs-geometries
+description: "three.js geometry authoring: BufferGeometry, typed BufferAttribute and interleaved layouts, InstancedBufferGeometry, primitive Geometries (box/sphere/torus/etc.), ExtrudeGeometry and Shape/Path/Curve from Extras, WireframeGeometry, and addon geometries such as TextGeometry, DecalGeometry, RoundedBoxGeometry. Use when building custom buffer geometries, extruding shapes, or using primitive geometry constructors; for animation morph targets see threejs-animation; for merging buffers see BufferGeometryUtils addon."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- Building or modifying `BufferGeometry`, attributes, index buffers, draw ranges
+- Instancing via `InstancedBufferAttribute` / `InstancedMesh` geometry side (**threejs-objects** for mesh wrapper)
+- Extruding `Shape` along paths, `TubeGeometry`, `LatheGeometry`, `ExtrudeGeometry`
+- Text or decal addon geometries
+
+**IMPORTANT: geometries vs math**
+
+- **threejs-geometries** = GPU-ready triangle data.
+- **threejs-math** = `Box3`, `Sphere`, `Ray` tests without mesh topology.
+
+**Trigger phrases include:**
+
+- "BufferGeometry", "BufferAttribute", "ExtrudeGeometry", "Shape", "Curve"
+- "几何体", "缓冲几何", "挤出", "文字几何"
+
+## How to use this skill
+
+1. **Choose geometry type** — prefer built-in primitives (`BoxGeometry`, `SphereGeometry`, etc.) when they fit before custom buffers.
+2. **Custom BufferGeometry** — create geometry, set `position`, `normal`, `uv`, optional `index`; compute bounding volumes for frustum culling.
+3. **Validate normals** — verify normals exist before adding to scene; missing normals break lighting silently.
+4. **Instancing** — align instanced attribute divisor/count with `InstancedMesh` patterns in **threejs-objects**.
+5. **Extrusion** — build `Shape`/`Path`, extrude or lathe per docs; consult Extras **Curve** family for path sampling.
+6. **Addon geometries** — for NURBS, text, decals, follow Addons pages; cite docs instead of copying full APIs.
+7. **Dispose** — call `geometry.dispose()` when replacing meshes to avoid GPU memory leaks.
+
+### Example: Custom BufferGeometry with validation
+
+```javascript
+import * as THREE from 'three';
+
+// Create a simple triangle with custom BufferGeometry
+const geometry = new THREE.BufferGeometry();
+const vertices = new Float32Array([
+  -1, -1, 0,   1, -1, 0,   0, 1, 0
+]);
+geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
+geometry.computeVertexNormals(); // Always compute normals for correct lighting
+
+// Validate: ensure bounding sphere exists for frustum culling
+geometry.computeBoundingSphere();
+if (!geometry.boundingSphere) {
+  console.warn('Bounding sphere computation failed — check vertex data');
+}
+
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const mesh = new THREE.Mesh(geometry, material);
+scene.add(mesh);
+
+// Cleanup when done
+// geometry.dispose(); material.dispose();
+```
+
+See [examples/workflow-extrude-shape.md](examples/workflow-extrude-shape.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Core | https://threejs.org/docs/BufferGeometry.html |
+| Geometries | https://threejs.org/docs/BoxGeometry.html |
+| Extrude | https://threejs.org/docs/ExtrudeGeometry.html |
+| Shape | https://threejs.org/docs/Shape.html |
+
+## Scope
+
+- **In scope:** Core geometries, buffer core, curve/shape/extrusion workflows, selected addon geometries.
+- **Out of scope:** Physics collision mesh baking; full CAD import pipelines.
+
+## Common pitfalls and best practices
+
+- Missing normals break lighting; compute or import consistently.
+- Wrong winding order flips faces—check side/culling.
+- Huge attribute counts need LOD or simplification (modifiers in addons—mention only if user asks).
+
+## Documentation and version
+
+Primitives and `BufferGeometry` live under [Geometries](https://threejs.org/docs/#Geometries) and [BufferGeometry](https://threejs.org/docs/BufferGeometry.html) in [three.js docs](https://threejs.org/docs/). Curve, `Shape`, and extrusion APIs appear under **Extras** and **Geometries**—Addons **Curves** / **Geometries** document NURBS and text meshes; link those instead of copying long signatures.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `BufferGeometry`, a primitive, or `ExtrudeGeometry` / `Shape` as appropriate.
+2. Point **instancing** usage to **threejs-objects** for `InstancedMesh` patterns.
+3. Point morph targets and tracks to **threejs-animation** when deformation is time-driven.
+4. Reference `BufferGeometryUtils` (Addons **Utils**) only by name + docs link when merging/splitting.
+5. Emphasize `dispose()` when replacing large custom buffers.
+
+## References
+
+- https://threejs.org/docs/#Geometries
+- https://threejs.org/docs/BufferGeometry.html
+- https://threejs.org/docs/ExtrudeGeometry.html
+
+## Keywords
+
+**English:** buffergeometry, extrude, shape, path, curve, primitives, instancing, three.js
+
+**中文：** 几何体、BufferGeometry、挤出、Shape、曲线、实例化、three.js

package/skill-packs/threejs/skills/threejs-geometries/examples/workflow-extrude-shape.md

@@ -0,0 +1,13 @@
+# Workflow: extrude a 2D shape
+
+## Steps
+
+1. Create `THREE.Shape()` and draw with `moveTo` / `lineTo` / `quadraticCurveTo` / `bezierCurveTo` or holes via `shape.holes.push(innerShape)`.
+
+2. Build `ExtrudeGeometry(shape, { depth, bevelEnabled, ... })` per [ExtrudeGeometry](https://threejs.org/docs/ExtrudeGeometry.html).
+
+3. Center/pivot by wrapping in `Object3D` or translating geometry once.
+
+4. Assign `MeshStandardMaterial` (**threejs-materials**) and add lights (**threejs-lights**).
+
+For path-based tubes use `TubeGeometry` + `Curve` subclasses instead.

package/skill-packs/threejs/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/skill-packs/threejs/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.