Threejs Builder

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

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:

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