@leejungkiin/awkit 1.7.6 → 1.7.8

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.

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.