@leejungkiin/awkit 1.7.6 → 1.7.7

package/skills/threejs-audio/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: threejs-audio
+description: "three.js audio spatialization: AudioListener attached to camera rig, Audio and PositionalAudio sources, AudioAnalyser for FFT/time-domain data, and integration with Web Audio API contexts; AudioLoader is referenced from threejs-loaders for file decoding. Use when placing 3D sound, configuring panner parameters, or building audio visualization; not a replacement for full game audio middleware."
+---
+
+## When to use this skill
+
+**ALWAYS use this skill when the user mentions:**
+
+- `AudioListener` on `Camera`, `Audio` vs `PositionalAudio`, distance models, refDistance/maxDistance/rolloff
+- `AudioAnalyser` for visualization bars/spectrum
+- Browser autoplay policies blocking audio start
+
+**IMPORTANT: audio vs loaders**
+
+| Step | Skill |
+|------|--------|
+| Decode mp3/ogg buffer | **threejs-loaders** (`AudioLoader`) |
+| Spatial playback API | **threejs-audio** |
+
+**Trigger phrases include:**
+
+- "PositionalAudio", "AudioListener", "AudioAnalyser", "panner"
+- "空间音频", "音量衰减", "频谱"
+
+## How to use this skill
+
+1. **Attach listener** to camera object so head-related audio follows view.
+2. **Validate AudioContext state** — check `listener.context.state` before playback; resume if suspended.
+3. **Create context** compatible with user gesture unlock patterns in browsers.
+4. **PositionalAudio** — set `refDistance`, `maxDistance`, `rolloffFactor`, `distanceModel` per docs.
+5. **Load buffer** via `AudioLoader` (**threejs-loaders**), then `positionalAudio.setBuffer`.
+6. **Analyser** — connect graph `listener.context.createAnalyser()` pathways per examples; watch performance.
+7. **Update** — audio nodes usually need no per-frame update unless following moving sources manually.
+
+### Example: PositionalAudio with context validation
+
+```javascript
+import * as THREE from 'three';
+
+const listener = new THREE.AudioListener();
+camera.add(listener);
+
+// Validate AudioContext state before attempting playback
+function ensureAudioContext() {
+  if (listener.context.state === 'suspended') {
+    listener.context.resume();
+  }
+}
+
+// Resume on user gesture (required by browser autoplay policy)
+document.addEventListener('click', ensureAudioContext, { once: true });
+
+const sound = new THREE.PositionalAudio(listener);
+const loader = new THREE.AudioLoader();
+loader.load('sound.mp3', (buffer) => {
+  sound.setBuffer(buffer);
+  sound.setRefDistance(20);
+  sound.setRolloffFactor(1);
+});
+mesh.add(sound); // Attach to a scene object for spatial positioning
+```
+
+See [examples/workflow-positional-audio.md](examples/workflow-positional-audio.md).
+
+## Doc map (official)
+
+| Docs section | Representative links |
+|--------------|----------------------|
+| Audio | https://threejs.org/docs/AudioListener.html |
+| Audio | https://threejs.org/docs/Audio.html |
+| Audio | https://threejs.org/docs/PositionalAudio.html |
+| Audio | https://threejs.org/docs/AudioAnalyser.html |
+
+Extended list: [references/official-sections.md](references/official-sections.md).
+
+## Scope
+
+- **In scope:** Core Audio classes, spatialization parameters, analyser usage overview.
+- **Out of scope:** FMOD/Wwise-style authoring tools.
+
+## Common pitfalls and best practices
+
+- Autoplay restrictions require user interaction to resume AudioContext.
+- Too many positional sources hurt CPU—pool or LOD audio.
+- Ensure world units match distance model expectations.
+
+## Documentation and version
+
+Audio classes are under [Audio](https://threejs.org/docs/#Audio) in [three.js docs](https://threejs.org/docs/). Decoding buffers uses `AudioLoader`—see **threejs-loaders**. Browser Web Audio policies are external but must be mentioned when `AudioContext` is suspended.
+
+## Agent response checklist
+
+When answering under this skill, prefer responses that:
+
+1. Link `AudioListener`, `PositionalAudio`, or `AudioAnalyser` as relevant.
+2. Delegate file loading of sound buffers to **threejs-loaders** (`AudioLoader`).
+3. Note autoplay / user-gesture requirements for resuming context.
+4. Relate distance attenuation to world units and **threejs-objects** placement.
+5. Avoid promising DAW-level mixing—stay within three.js audio scope.
+
+## References
+
+- https://threejs.org/docs/#Audio
+- https://threejs.org/docs/AudioListener.html
+- https://threejs.org/docs/PositionalAudio.html
+
+## Keywords
+
+**English:** audio, positional audio, listener, analyser, spatial sound, web audio, three.js
+
+**中文：** 音频、空间音频、AudioListener、PositionalAudio、Web Audio、three.js

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