name: threejs-builder
description: "Three.js app builder: imperative, React Three Fiber, and WebGPU in 4 phases."
agent: typescript-frontend-engineer
user-invocable: false
command: /threejs
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
routing:
  triggers:
    - threejs
    - three.js
    - 3D web
    - 3D scene
    - WebGL
    - WebGPU
    - 3D animation
    - 3D graphics
    - react three fiber
    - r3f
    - drei
    - react-three
    - "@react-three/fiber"
    - postprocessing 3D
    - TSL shader
    - three shading language
    - compute shader three
    - WebGPURenderer
    - node material three
    - game architecture three
    - gltf loading
    - glb model
    - animation state machine three
    - eventbus game
    - game state management three
    - three.js game
  pairs_with:
    - typescript-frontend-engineer
    - react-native-engineer
    - distinctive-frontend-design
  complexity: Medium
  category: frontend

Three.js Builder Skill

Overview

This skill builds complete Three.js web applications using a Phased Construction pattern with four phases: Design, Build, Animate, Polish. It supports three paradigms — imperative Three.js, React Three Fiber (R3F), and WebGPU — detected automatically from project context. Only the relevant paradigm's reference is loaded.

Scope: Use for 3D web apps, interactive scenes, WebGL/WebGPU visualizations, R3F declarative 3D, and product viewers. For game engines, 3D model creation, VR/AR experiences, or CAD workflows, use a more specialized skill.

---

Reference Loading Table

Signal	Load These Files	Why
@react-three/fiber, r3f, drei, useFrame, <Canvas>, <mesh>, React project with 3D	react-three-fiber.md	React Three Fiber
WebGPURenderer, TSL, tsl, compute shader, wgsl, node material, WebGPU mentioned	webgpu.md	WebGPU
Standalone HTML, CDN imports, new THREE.Scene(), no React, vanilla JS/TS	advanced-topics.md (load as needed)`	Imperative
Game project: EventBus, GameState, player controller, enemies, scoring, multiple game systems	game-patterns.md (alongside paradigm reference)`	Game architecture
GLTF/GLB model loading, .glb files, animated characters, skeletal rigs, model import	gltf-loading.md (alongside paradigm reference)`	GLTF loading
references/build-recipes.md	build-recipes.md	Phase 2/3 build, error diagnosis
references/advanced-topics.md	advanced-topics.md	Imperative paradigm
references/react-three-fiber.md	react-three-fiber.md	R3F paradigm
references/webgpu.md	webgpu.md	WebGPU paradigm
references/visual-polish.md	visual-polish.md	Visual quality signal
references/gltf-loading.md	gltf-loading.md	GLTF/GLB model loading signal
references/game-patterns.md	game-patterns.md	Game project signal
references/game-architecture.md	game-architecture.md	Game project signal
references/shader-patterns.md	shader-patterns.md	Custom GLSL / visual effects
references/performance-patterns.md	performance-patterns.md	Performance / many objects
references/advanced-animation.md	advanced-animation.md	Animation systems / skeletal rigs

Instructions

Phase 1: DESIGN

Goal: Detect the paradigm, understand what the user wants, and select appropriate components.

Core Constraints:

• Build only what the user asked for — no speculative features or "while I'm here" additions
• Detect the paradigm before selecting components — imperative, R3F, and WebGPU have fundamentally different patterns; using the wrong one is the #1 source of bugs
• Structure through the scene graph — use Group for logical groupings and maintain proper hierarchy
• Vary style by context — portfolio/showcase use elegant muted palettes; games use bright colors; data viz uses clean lines; backgrounds use subtle slow movement; product viewers use realistic PBR lighting
• Read repository CLAUDE.md before building — ensure compliance with local development standards

Step 0: Detect paradigm

Scan the user's request, existing project files (package.json, imports), and stated requirements to identify which paradigm applies:

Signal	Paradigm / Context	Reference to Load
@react-three/fiber, r3f, drei, useFrame, <Canvas>, <mesh>, React project with 3D	React Three Fiber	references/react-three-fiber.md
WebGPURenderer, TSL, tsl, compute shader, wgsl, node material, WebGPU mentioned	WebGPU	references/webgpu.md
Standalone HTML, CDN imports, new THREE.Scene(), no React, vanilla JS/TS	Imperative	references/advanced-topics.md (load as needed)
Game project: EventBus, GameState, player controller, enemies, scoring, multiple game systems	Game architecture	references/game-architecture.md + references/game-patterns.md (alongside paradigm reference)
GLTF/GLB model loading, .glb files, animated characters, skeletal rigs, model import	GLTF loading	references/gltf-loading.md (alongside paradigm reference)

If ambiguous (e.g., user says "3D scene" with no project context), ask which paradigm — don't guess, because imperative Three.js patterns actively conflict with R3F patterns (OrbitControls setup, animation loops, component lifecycle).

Game and GLTF references load alongside the paradigm reference — they are complementary, not alternative. A game project using R3F loads both react-three-fiber.md and the relevant game references.

After detecting paradigm: Read the corresponding reference file. The reference contains paradigm-specific patterns, failure modes, and component selection guidance that override the generic steps below.

Additional reference loading signals (visual-polish, shader-patterns, performance-patterns, advanced-animation) are listed in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 1: Additional Reference Loading Signals).

Step 1: Identify the core visual element

Determine from the user request:

• What is the primary 3D content? (geometric shapes, loaded model, particles, terrain)
• What interaction is needed? (none, orbit, click, mouse tracking)
• What animation brings it to life? (rotation, oscillation, morphing, physics)
• What is the context? (portfolio, game, data viz, background, product viewer)

Step 2: Select components

See the Scene Plan template in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 1: Scene Plan Template).

Step 3: Document visual style

Record the visual direction for this scene (e.g., "elegant minimal portfolio style", "vibrant interactive game", "clean data visualization"). Use this to guide material colors, lighting warmth, and animation pacing.

Gate: Scene plan documented with geometry, material, lighting, animation, and controls selected. Proceed only when gate passes.

Phase 2: BUILD

Goal: Construct the scene with proper structure and modern patterns.

Paradigm-specific build instructions: If you loaded a paradigm reference in Step 0, follow its build patterns instead of the imperative defaults. R3F uses JSX components and <Canvas>, not manual renderer setup. WebGPU uses WebGPURenderer with different initialization. The reference file is authoritative for its paradigm.

Core constraints for the imperative paradigm (single HTML, resize handling, CONFIG object, modular setup functions, three-point lighting, renderer.setAnimationLoop()) are in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 2: Core Constraints).

Step 1: Create HTML boilerplate

See the HTML boilerplate in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 2: HTML Boilerplate).

Step 2: Build scene infrastructure

See the scene infrastructure code (CONFIG object, scene/camera/renderer setup, resize handler) in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 2: Scene Infrastructure).

Step 3: Add lighting, geometry, and materials per scene plan

Build each component from the Phase 1 plan. Create geometry once and reuse where possible (avoid allocating new geometries in animation loops). Use Group for hierarchical transforms and logical scene organization.

Gate: Scene renders without errors. All planned geometry, materials, and lights are present. Proceed only when gate passes.

Phase 3: ANIMATE

Goal: Add motion, interaction, and life to the scene.

Paradigm-specific animation: R3F uses useFrame hooks (never requestAnimationFrame or setAnimationLoop). WebGPU may use compute shaders for GPU-driven animation. See the loaded paradigm reference for patterns.

Core constraints for the imperative paradigm (no geometry/material allocation in the loop, time parameter usage, OrbitControls default, transform-only-per-frame) are in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 3: Core Constraints).

Step 1: Set up animation loop

See the animation loop pattern in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 3: Animation Loop).

Step 2: Implement planned animations

Apply transforms per frame. Time-based animation follows the pattern shown in references/build-recipes.md.

Step 3: Add interaction handlers

Wire up mouse/touch events, orbit controls, or raycasting per the scene plan.

Gate: Animations run smoothly. Interactions respond correctly. No console errors. Proceed only when gate passes.

Phase 4: POLISH

Goal: Ensure quality, performance, and completeness.

Core constraints (remove debug helpers / commented code, handle window resize, ensure visible lighting, match visual style) and the four verification steps (responsive behavior, visual quality, output testing, cleanup) are in ${CLAUDE_SKILL_DIR}/references/build-recipes.md (Phase 4: Core Constraints + Polish Verification Steps).

Gate: All verification steps pass. Output is complete and ready to deliver.

---

Error Handling

See ${CLAUDE_SKILL_DIR}/references/build-recipes.md for error cases: black screen / nothing renders, OrbitControls not defined, model loads but is invisible or tiny.

---

References

Reference	When to Load	Content
references/build-recipes.md	Phase 2/3 build, error diagnosis	HTML boilerplate, CONFIG + scene/camera/renderer setup, animation loop, error handling (black screen, OrbitControls, model scale)
references/advanced-topics.md	Imperative paradigm	GLTF loading, post-processing, shaders, raycasting, physics, InstancedMesh, TypeScript
references/react-three-fiber.md	R3F paradigm	Declarative patterns, Drei helpers, camera pitfalls, post-processing, Zustand, performance
references/webgpu.md	WebGPU paradigm	WebGPURenderer, TSL shaders, compute shaders, version-specific changes, device loss
references/visual-polish.md	Visual quality signal	Material recipes, dramatic lighting, post-processing stacking, HDR environments, shadow quality
references/gltf-loading.md	GLTF/GLB model loading signal	Coordinate system contract, SkeletonUtils.clone, model caching, auto-centering, bone hierarchy, asset manifest
references/game-patterns.md	Game project signal	Animation state machine, camera-relative movement, delta capping, mobile input, player controller
references/game-architecture.md	Game project signal	EventBus, GameState singleton, Constants module, restart-safety, pre-ship checklist
references/shader-patterns.md	Custom GLSL / visual effects	ShaderMaterial vs RawShaderMaterial, vertex displacement, fragment effects (holographic, dissolve, chromatic aberration), EffectComposer postprocessing pipeline
references/performance-patterns.md	Performance / many objects	InstancedMesh, BufferGeometry typed arrays, draw call batching, LOD, KTX2 textures, dispose patterns
references/advanced-animation.md	Animation systems / skeletal rigs	AnimationMixer morph targets, bone manipulation, procedural IK, spring physics, GSAP integration, particle animation