🎨 Interactive 3D Website Builder

An AI Agent Skill for Building Premium Scroll-Driven 3D Websites

Give your AI agent a .glb model and basic site info → get a production-ready immersive 3D website.

📦 NPM Package: https://www.npmjs.com/package/interactive-3d-website-skill

Works with Claude Code · OpenAI Codex · Google Gemini / Antigravity · Cursor · Any AI Coding Agent

Features · Quick Install · NPM Commands · How It Works · Usage · Templates

✨ Features

• 🤖 AI-Agent Native — Designed as a skill file that AI coding agents read and follow. Not a library — it's instructions that teach your agent how to build 3D websites.
• 📦 One GLB, Full Website — Drop in any .glb 3D model file. The agent auto-centers, auto-scales, and applies premium materials.
• 🎬 Scroll-Driven Animation — GSAP ScrollTrigger maps scroll position to 3D model transforms (position, rotation, scale) at 60fps with zero React re-renders.
• 🧈 Butter-Smooth Scrolling — Lenis smooth scroll provides silky inertia-based scrolling across all devices.
• 🎨 6 Material Presets — Gold Metallic, Chrome, White Marble, Dark Obsidian, Rose Gold, Bronze Antique — or keep original materials.
• 🌗 5 Color Palettes — Luxury Gold, Midnight Silver, Emerald, Cyber Purple, Warm Crimson.
• 📱 Fully Responsive — Desktop + mobile with adaptive model positions and scales.
• ⚡ Production-Ready — SEO metadata, loading screen, Draco compression, adaptive DPR, performance optimized.
• 🧩 10 Copy-Paste Templates — Ready-to-use template files inside reference/.

🎬 Demo

The demo/ directory contains the complete reference implementation — the SaayaLabs website featuring a golden Hermes sculpture that animates as you scroll through the page.

# Clone and run the demo
git clone https://github.com/saayalabs/interactive-3d-website-skill.git
cd interactive-3d-website-skill
npm run dev

🚀 NPM Commands & Installation

Link to Official Package: https://www.npmjs.com/package/interactive-3d-website-skill

⚡ 1. Run Instantly with NPX (No Installation Needed)

# Auto-detects your AI agent and installs the skill
npx interactive-3d-website-skill

Or using the short alias:

npx 3d-website-skill

🤖 2. Install for Specific AI Agents

# Claude Code (installs to ~/.claude/skills/)
npx interactive-3d-website-skill --claude

# Google Gemini / Antigravity (installs to ~/.gemini/config/skills/)
npx interactive-3d-website-skill --gemini

# OpenAI Codex (installs to ~/.codex/skills/)
npx interactive-3d-website-skill --codex

🌐 3. Global Installation

npm install -g interactive-3d-website-skill

Then run anywhere:

interactive-3d-website-skill

📦 4. Add to Local Project

npm install interactive-3d-website-skill

Specific agent:

npx interactive-3d-website-skill --claude   # → ~/.claude/skills/
npx interactive-3d-website-skill --codex    # → ~/.codex/skills/
npx interactive-3d-website-skill --gemini   # → ~/.gemini/config/skills/

Custom directory:

npx interactive-3d-website-skill --target /path/to/your/skills/dir

Option 2: Manual Install

# Clone the repo
git clone https://github.com/saayalabs/interactive-3d-website-skill.git

# Run the installer
cd interactive-3d-website-skill
node install.js

# Or copy manually
cp SKILL.md ~/.claude/skills/interactive_3d_website/
cp -r reference/ ~/.claude/skills/interactive_3d_website/reference/

Option 3: Direct Copy

Just copy two things into your agent's skills directory:

~/.claude/skills/interactive_3d_website/
├── SKILL.md        ← The main skill instructions
└── reference/      ← 10 template files

For Codex: Replace ~/.claude/ with ~/.codex/
For Gemini: Use ~/.gemini/config/skills/
For Cursor: Use .cursor/skills/ in your project root

🧠 How It Works

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Next.js App (SSR)                       │
│                                                              │
│  layout.tsx ─── Font loading + LenisProvider (smooth scroll) │
│  page.tsx ───── Assembles all sections                       │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐    │
│  │                   HeroSection (400vh)                 │    │
│  │  ┌─────────────┐  ┌────────────────────────────┐     │    │
│  │  │ SceneCanvas  │  │  Content Panels (z-layered) │     │    │
│  │  │ (R3F Canvas) │  │  - Hero text (z-30)         │     │    │
│  │  │  ↕ scroll    │  │  - About card (z-20)        │     │    │
│  │  │  progress    │  │  - Features card (z-20)     │     │    │
│  │  │  ref         │  │                              │     │    │
│  │  │  ┌─────────┐ │  └────────────────────────────┘     │    │
│  │  │  │GLBModel │ │                                      │    │
│  │  │  │(useGLTF)│ │  section height: 400vh               │    │
│  │  │  └─────────┘ │  sticky viewport: 100vh              │    │
│  │  └─────────────┘                                       │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
│  Other Sections ── Domains, Manifesto, Testimonials, etc.    │
└──────────────────────────────────────────────────────────────┘

The 3 Critical Patterns

1. Transparent Canvas Overlay

The WebGL canvas renders with alpha: true (transparent background) and pointerEvents: "none" so it floats over HTML content without blocking scroll or clicks.

2. Zero-Rerender Scroll Tracking

GSAP ScrollTrigger writes to a useRef (not useState), avoiding 60+ re-renders per second. The ref is read inside Three.js's useFrame render loop.

3. Smoothstep Keyframe Interpolation

The 3D model transitions between predefined keyframe states using smoothstep easing (t² × (3 - 2t)) with frame-rate independent damping for buttery-smooth animation on any device.

📖 Usage

What the AI Agent Needs From You

| Input | Example | Required? | |-------|---------|-----------| | GLB model file | product.glb, sculpture.glb | ✅ Yes | | Brand name | "SaayaLabs" | ✅ Yes | | Tagline | "Timeless aesthetic. Unshakable code." | ✅ Yes | | Color palette | Gold, Silver, Emerald, Purple, Crimson | Optional | | Material style | Gold Metallic, Chrome, Marble, etc. | Optional | | Section content | About text, features list, testimonials | Optional |

Example Prompt

Build me a 3D interactive website for my brand "Nova Studios" 
with the tagline "Design Beyond Boundaries". Use the sculpture.glb 
model in my public/assets/ folder. I want a chrome material with 
a midnight blue color palette. Include About, Services, and 
Contact sections.

The agent reads SKILL.md, follows the step-by-step workflow, uses the template files in reference/, and produces a complete Next.js application.

📁 Templates

All templates are in the reference/ directory with ← CUSTOMIZE markers:

| Template | Purpose | |----------|---------| | GLBModel.template.tsx | Load, center, scale, and style any GLB model | | SceneCanvas.template.tsx | R3F Canvas with lighting rig + scroll-driven animation | | HeroSection.template.tsx | 400vh scroll-driven hero with 3 content phases | | ModelLoader.template.tsx | Branded loading screen with progress bar | | LenisProvider.template.tsx | Smooth scroll wrapper | | ScrollReveal.template.tsx | GSAP scroll-triggered content reveals | | globals.template.css | Design system with color tokens + utility classes | | layout.template.tsx | Next.js layout with fonts + SEO metadata | | page.template.tsx | Main page section assembly | | QUICK_REFERENCE.md | Cheatsheet for rapid builds |

🎨 Material Presets

📂 Project Structure

.
├── SKILL.md                    # AI agent skill instructions
├── reference/                  # 10 template files for AI agents
│   ├── QUICK_REFERENCE.md      # Cheatsheet
│   ├── GLBModel.template.tsx
│   ├── SceneCanvas.template.tsx
│   ├── HeroSection.template.tsx
│   ├── ModelLoader.template.tsx
│   ├── LenisProvider.template.tsx
│   ├── ScrollReveal.template.tsx
│   ├── globals.template.css
│   ├── layout.template.tsx
│   └── page.template.tsx
├── demo/                       # Full reference website project
│   ├── src/                    # App, 3D components, sections
│   ├── public/                 # Assets (hermes-draco.glb) & images
│   ├── next.config.ts
│   ├── tsconfig.json
│   └── package.json
├── install.js                  # Skill installer script
├── package.json                # Root skill npm package descriptor
├── LICENSE                     # MIT License
└── README.md

🚢 Publishing to NPM

To publish this skill as an npm package so anyone can run npx interactive-3d-website-skill:

# Login to npm
npm login

# Publish
npm publish --access public

📜 License

MIT License — see LICENSE for details.

Built with 🖤 by SaayaLabs

Timeless aesthetic. Unshakable code.