three-agent-skills 1.0.0

package/AGENTS.md

@@ -0,0 +1,225 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.
+
+## Repository Overview
+
+A collection of agent skills for Three.js development. Skills are packaged instructions and scripts that extend AI agent capabilities for 3D web development, shader programming, and WebGL optimization.
+
+## Creating a New Skill
+
+### Directory Structure
+
+```
+skills/
+  {skill-name}/           # kebab-case directory name
+    SKILL.md              # Required: skill definition
+    scripts/              # Optional: executable scripts
+      {script-name}.sh    # Bash scripts (preferred)
+    references/           # Optional: supporting documentation
+      *.md                # Additional reference files
+  {skill-name}.zip        # Required for distribution: packaged skill
+```
+
+### Naming Conventions
+
+- **Skill directory**: `kebab-case` (e.g., `shader-optimization`, `scene-setup`)
+- **SKILL.md**: Always uppercase, always this exact filename
+- **Scripts**: `kebab-case.sh` (e.g., `analyze.sh`, `generate-boilerplate.sh`)
+- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
+
+### SKILL.md Format
+
+Every skill must have a `SKILL.md` file with this structure:
+
+```markdown
+---
+name: {skill-name}
+description: {One sentence describing when to use this skill. Include trigger phrases.}
+argument-hint: <optional-args>  # Optional: hint for arguments
+license: MIT
+metadata:
+  author: {author-name}
+  version: "{semver}"
+---
+
+# {Skill Title}
+
+{Brief description of what the skill does.}
+
+## When to Apply
+
+Reference these guidelines when:
+- {Scenario 1}
+- {Scenario 2}
+- {Scenario 3}
+
+## How It Works
+
+{Numbered list explaining the skill's workflow}
+
+1. Step one
+2. Step two
+3. Step three
+
+## Usage
+
+```bash
+bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
+```
+
+**Arguments:**
+- `arg1` - Description (defaults to X)
+
+**Examples:**
+{Show 2-3 common usage patterns}
+
+## Quick Reference
+
+{Concise summary of rules/patterns organized by category}
+
+## Output
+
+{Show example output users will see}
+
+## Present Results to User
+
+{Template for how the agent should format results when presenting to users}
+
+## Troubleshooting
+
+{Common issues and solutions}
+```
+
+### Best Practices for Context Efficiency
+
+Skills are loaded on-demand. Only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant.
+
+To minimize context usage:
+
+- **Keep SKILL.md under 500 lines** - put detailed reference material in separate files
+- **Write specific descriptions** - helps the agent know exactly when to activate the skill
+- **Use progressive disclosure** - reference supporting files that get read only when needed
+- **Prefer scripts over inline code** - script execution doesn't consume context (only output does)
+- **File references work one level deep** - link directly from SKILL.md to supporting files
+
+### Script Requirements
+
+If your skill includes scripts:
+
+```bash
+#!/bin/bash
+set -e  # Fail-fast behavior
+
+# Write status messages to stderr
+echo "Processing..." >&2
+
+# Write machine-readable output (JSON) to stdout
+echo '{"result": "success"}'
+
+# Include cleanup trap for temp files
+cleanup() {
+    rm -rf "$TEMP_DIR"
+}
+trap cleanup EXIT
+```
+
+Key requirements:
+- Use `#!/bin/bash` shebang
+- Use `set -e` for fail-fast behavior
+- Write status messages to stderr: `echo "Message" >&2`
+- Write machine-readable output (JSON) to stdout
+- Include a cleanup trap for temp files
+- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
+
+### Creating the Zip Package
+
+After creating or updating a skill:
+
+```bash
+cd skills
+zip -r {skill-name}.zip {skill-name}/
+```
+
+### End-User Installation
+
+**Claude Code:**
+```bash
+cp -r skills/{skill-name} ~/.claude/skills/
+```
+
+**claude.ai:**
+Add the skill to project knowledge or paste SKILL.md contents into the conversation.
+
+If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
+
+## Skill Types
+
+### 1. Guidelines Skills (No Scripts)
+
+Pure documentation skills that provide rules and best practices. Example: `react-best-practices`.
+
+Structure:
+```
+skill-name/
+  SKILL.md          # Rules and guidelines
+  rules/            # Optional: individual rule files
+    rule-1.md
+    rule-2.md
+```
+
+### 2. Tool Skills (With Scripts)
+
+Skills that execute actions via bash scripts. Example: `vercel-deploy`.
+
+Structure:
+```
+skill-name/
+  SKILL.md          # Usage instructions
+  scripts/
+    main-action.sh  # Primary script
+    helper.sh       # Supporting scripts
+```
+
+### 3. Hybrid Skills
+
+Combine guidelines with automation tools.
+
+Structure:
+```
+skill-name/
+  SKILL.md          # Instructions + quick reference
+  AGENTS.md         # Full compiled guidelines
+  scripts/
+    analyze.sh      # Automation scripts
+  rules/
+    detailed-rules/
+```
+
+## Frontmatter Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (kebab-case) |
+| `description` | Yes | One sentence with trigger phrases |
+| `argument-hint` | No | Hint for arguments (e.g., `<file-or-pattern>`) |
+| `license` | No | License type (default: MIT) |
+| `metadata.author` | No | Author name |
+| `metadata.version` | No | Semantic version |
+
+## Testing Your Skill
+
+1. **Local Testing**: Copy to `~/.claude/skills/` and test with Claude Code
+2. **Description Testing**: Verify the agent activates on expected trigger phrases
+3. **Script Testing**: Run scripts manually to verify behavior
+4. **Context Testing**: Ensure SKILL.md stays under 500 lines
+
+## Example Skills for Three.js
+
+Future skills in this repository:
+
+- `three-scene-setup` - Best practices for Three.js scene initialization
+- `shader-optimization` - GLSL shader performance patterns
+- `three-performance` - Rendering optimization guidelines
+- `three-postprocessing` - Post-processing effects setup
+- `three-physics` - Physics engine integration patterns

package/README.md

@@ -0,0 +1,129 @@
+# Three Agent Skills
+
+AI coding agent skills for Three.js and React Three Fiber development.
+
+Skills follow the [Agent Skills](https://agentskills.io/) specification.
+
+## Installation
+
+```bash
+npx add-skill three-agent-skills
+```
+
+Or from GitHub directly:
+
+```bash
+npx add-skill emalorenzo/three-agent-skills
+```
+
+### List available skills
+
+```bash
+npx add-skill three-agent-skills --list
+```
+
+### Install specific skill
+
+```bash
+npx add-skill three-agent-skills --skill three-best-practices
+npx add-skill three-agent-skills --skill r3f-best-practices
+```
+
+## Available Skills
+
+### three-best-practices
+
+Pure Three.js optimization guidelines. 70+ rules across 12 categories.
+
+**Use when:**
+- Writing Three.js code
+- Optimizing WebGL performance
+- Managing memory and disposal
+- Writing shaders (GLSL or TSL)
+
+**Categories:**
+- Modern Setup & Imports (Import Maps, renderers)
+- Memory Management & Dispose (CRITICAL)
+- Render Loop Optimization (CRITICAL)
+- Geometry & Buffer Management
+- Material & Texture Optimization
+- Lighting & Shadows
+- Scene Graph Organization
+- Shader Best Practices (GLSL)
+- TSL - Three.js Shading Language
+- Loading & Assets
+- Camera & Controls
+- Debug & DevTools
+
+### r3f-best-practices
+
+React Three Fiber and Poimandres ecosystem best practices. 60+ rules across 11 categories.
+
+**Use when:**
+- Writing R3F components
+- Optimizing R3F performance (re-renders)
+- Using Drei helpers
+- Managing state with Zustand
+- Implementing physics or post-processing
+
+**Ecosystem coverage:**
+- @react-three/fiber
+- @react-three/drei
+- @react-three/postprocessing
+- @react-three/rapier
+- zustand
+- leva
+
+**Categories:**
+- Performance & Re-renders (CRITICAL)
+- useFrame & Animation (CRITICAL)
+- Component Patterns
+- Canvas & Setup
+- Drei Helpers
+- Loading & Suspense
+- State Management
+- Events & Interaction
+- Post-processing
+- Physics (Rapier)
+- Leva (Debug GUI)
+
+## Usage Examples
+
+Once installed, the agent uses skills automatically based on context:
+
+```
+Help me set up a Three.js scene with proper memory management
+```
+
+```
+Review my R3F component for performance issues
+```
+
+```
+How do I load GLTF models with Drei?
+```
+
+```
+Optimize my shader for mobile devices
+```
+
+## Supported Agents
+
+Works with any agent that supports the [Agent Skills](https://agentskills.io/) spec:
+
+- Claude Code
+- Cursor
+- Codex
+- OpenCode
+- VS Code Copilot
+- And more...
+
+## Documentation
+
+- Full Three.js guide: [THREE_BEST_PRACTICES.md](./THREE_BEST_PRACTICES.md)
+- Full R3F guide: [R3F_BEST_PRACTICES.md](./R3F_BEST_PRACTICES.md)
+- Creating skills: [AGENTS.md](./AGENTS.md)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "three-agent-skills",
+  "version": "1.0.0",
+  "description": "AI coding agent skills for Three.js and React Three Fiber best practices",
+  "keywords": [
+    "threejs",
+    "three.js",
+    "react-three-fiber",
+    "r3f",
+    "webgl",
+    "3d",
+    "agent-skills",
+    "ai",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "author": "emalorenzo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emalorenzo/three-agent-skills.git"
+  },
+  "homepage": "https://github.com/emalorenzo/three-agent-skills#readme",
+  "bugs": {
+    "url": "https://github.com/emalorenzo/three-agent-skills/issues"
+  },
+  "files": [
+    "skills",
+    "AGENTS.md",
+    "README.md"
+  ]
+}

package/skills/r3f-best-practices/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: r3f-best-practices
+description: React Three Fiber (R3F) and Poimandres ecosystem best practices. Use when writing, reviewing, or optimizing R3F code. Triggers on tasks involving @react-three/fiber, @react-three/drei, zustand, @react-three/postprocessing, @react-three/rapier, or leva.
+license: MIT
+metadata:
+  author: three-agent-skills
+  version: "1.0.0"
+---
+
+# React Three Fiber Best Practices
+
+Comprehensive guide for React Three Fiber and the Poimandres ecosystem. Contains 60+ rules across 11 categories, prioritized by impact.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new R3F components
+- Optimizing R3F performance (re-renders are the #1 issue)
+- Using Drei helpers correctly
+- Managing state with Zustand
+- Implementing post-processing or physics
+
+## Ecosystem Coverage
+
+- **@react-three/fiber** - React renderer for Three.js
+- **@react-three/drei** - Useful helpers and abstractions
+- **@react-three/postprocessing** - Post-processing effects
+- **@react-three/rapier** - Physics engine
+- **zustand** - State management
+- **leva** - Debug GUI
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Performance & Re-renders | CRITICAL | `perf-` |
+| 2 | useFrame & Animation | CRITICAL | `frame-` |
+| 3 | Component Patterns | HIGH | `component-` |
+| 4 | Canvas & Setup | HIGH | `canvas-` |
+| 5 | Drei Helpers | MEDIUM-HIGH | `drei-` |
+| 6 | Loading & Suspense | MEDIUM-HIGH | `loading-` |
+| 7 | State Management | MEDIUM | `state-` |
+| 8 | Events & Interaction | MEDIUM | `events-` |
+| 9 | Post-processing | MEDIUM | `postpro-` |
+| 10 | Physics (Rapier) | LOW-MEDIUM | `physics-` |
+| 11 | Leva (Debug GUI) | LOW | `leva-` |
+
+## Quick Reference
+
+### 1. Performance & Re-renders (CRITICAL)
+
+- `perf-never-set-state-in-useframe` - NEVER call setState in useFrame
+- `perf-isolate-state` - Isolate components that need React state
+- `perf-zustand-selectors` - Use Zustand selectors, not entire store
+- `perf-transient-subscriptions` - Use transient subscriptions for continuous values
+- `perf-memo-components` - Memoize expensive components
+- `perf-keys-for-lists` - Use stable keys for dynamic lists
+- `perf-avoid-inline-objects` - Avoid creating objects/arrays in JSX
+- `perf-dispose-auto` - Understand R3F auto-dispose behavior
+
+### 2. useFrame & Animation (CRITICAL)
+
+- `frame-priority` - Use priority for execution order
+- `frame-delta-time` - Always use delta for animations
+- `frame-conditional-subscription` - Disable useFrame when not needed
+- `frame-destructure-state` - Destructure only what you need
+- `frame-render-on-demand` - Use invalidate() for on-demand rendering
+- `frame-avoid-heavy-computation` - Move heavy work outside useFrame
+
+### 3. Component Patterns (HIGH)
+
+- `component-jsx-elements` - Use JSX for Three.js objects
+- `component-attach-prop` - Use attach for non-standard properties
+- `component-primitive` - Use primitive for existing objects
+- `component-extend` - Use extend() for custom classes
+- `component-forwardref` - Use forwardRef for reusable components
+- `component-dispose-null` - Set dispose={null} on shared resources
+
+### 4. Canvas & Setup (HIGH)
+
+- `canvas-size-container` - Canvas fills parent container
+- `canvas-camera-default` - Configure camera via prop
+- `canvas-gl-config` - Configure WebGL context
+- `canvas-shadows` - Enable shadows at Canvas level
+- `canvas-frameloop` - Choose appropriate frameloop mode
+- `canvas-events` - Configure event handling
+- `canvas-linear-flat` - Use linear/flat for correct colors
+
+### 5. Drei Helpers (MEDIUM-HIGH)
+
+- `drei-use-gltf` - useGLTF with preloading
+- `drei-use-texture` - useTexture for texture loading
+- `drei-environment` - Environment for realistic lighting
+- `drei-orbit-controls` - OrbitControls from Drei
+- `drei-html` - Html for DOM overlays
+- `drei-text` - Text for 3D text
+- `drei-instances` - Instances for optimized instancing
+- `drei-use-helper` - useHelper for debug visualization
+- `drei-bounds` - Bounds to fit camera
+- `drei-center` - Center to center objects
+- `drei-float` - Float for floating animation
+
+### 6. Loading & Suspense (MEDIUM-HIGH)
+
+- `loading-suspense` - Wrap async components in Suspense
+- `loading-preload` - Preload assets with useGLTF.preload
+- `loading-use-progress` - useProgress for loading UI
+- `loading-lazy-components` - Lazy load heavy components
+- `loading-error-boundary` - Handle loading errors
+
+### 7. State Management (MEDIUM)
+
+- `state-zustand-store` - Create focused Zustand stores
+- `state-avoid-objects-in-store` - Be careful with Three.js objects
+- `state-subscribeWithSelector` - Fine-grained subscriptions
+- `state-persist` - Persist state when needed
+- `state-separate-concerns` - Separate stores by concern
+
+### 8. Events & Interaction (MEDIUM)
+
+- `events-pointer-events` - Use pointer events on meshes
+- `events-stop-propagation` - Prevent event bubbling
+- `events-cursor-pointer` - Change cursor on hover
+- `events-raycast-filter` - Filter raycasting
+- `events-event-data` - Understand event data structure
+
+### 9. Post-processing (MEDIUM)
+
+- `postpro-effect-composer` - Use EffectComposer
+- `postpro-common-effects` - Common effects reference
+- `postpro-selective-bloom` - SelectiveBloom for optimized glow
+- `postpro-custom-shader` - Create custom effects
+- `postpro-performance` - Optimize post-processing
+
+### 10. Physics Rapier (LOW-MEDIUM)
+
+- `physics-setup` - Basic Rapier setup
+- `physics-body-types` - dynamic, fixed, kinematic
+- `physics-colliders` - Choose appropriate colliders
+- `physics-events` - Handle collision events
+- `physics-api-ref` - Use ref for physics API
+- `physics-performance` - Optimize physics
+
+### 11. Leva (LOW)
+
+- `leva-basic` - Basic Leva usage
+- `leva-folders` - Organize with folders
+- `leva-conditional` - Hide in production
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/perf-never-set-state-in-useframe.md
+rules/drei-use-gltf.md
+rules/state-zustand-selectors.md
+```
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `../R3F_BEST_PRACTICES.md`
+
+## Critical Patterns
+
+### NEVER setState in useFrame
+
+```jsx
+// BAD - 60 re-renders per second!
+function BadComponent() {
+  const [position, setPosition] = useState(0);
+  useFrame(() => {
+    setPosition(p => p + 0.01); // NEVER DO THIS
+  });
+  return <mesh position-x={position} />;
+}
+
+// GOOD - Mutate refs directly
+function GoodComponent() {
+  const meshRef = useRef();
+  useFrame(() => {
+    meshRef.current.position.x += 0.01;
+  });
+  return <mesh ref={meshRef} />;
+}
+```
+
+### Zustand Selectors
+
+```jsx
+// BAD - Re-renders on ANY store change
+const store = useGameStore();
+
+// GOOD - Only re-renders when playerX changes
+const playerX = useGameStore(state => state.playerX);
+
+// BETTER - No re-renders, direct mutation
+useFrame(() => {
+  const { value } = useStore.getState();
+  ref.current.position.x = value;
+});
+```
+
+### Drei useGLTF
+
+```jsx
+import { useGLTF } from '@react-three/drei';
+
+function Model() {
+  const { scene } = useGLTF('/model.glb');
+  return <primitive object={scene} />;
+}
+
+// Preload for instant loading
+useGLTF.preload('/model.glb');
+```
+
+### Suspense Loading
+
+```jsx
+function App() {
+  return (
+    <Canvas>
+      <Suspense fallback={<Loader />}>
+        <Model />
+      </Suspense>
+    </Canvas>
+  );
+}
+```

package/skills/r3f-best-practices/rules/_sections.md

@@ -0,0 +1,90 @@
+# Rule Sections
+
+## Priority 1: Performance & Re-renders (CRITICAL)
+- perf-never-set-state-in-useframe
+- perf-isolate-state
+- perf-zustand-selectors
+- perf-transient-subscriptions
+- perf-memo-components
+- perf-keys-for-lists
+- perf-avoid-inline-objects
+- perf-dispose-auto
+
+## Priority 2: useFrame & Animation (CRITICAL)
+- frame-priority
+- frame-delta-time
+- frame-conditional-subscription
+- frame-destructure-state
+- frame-render-on-demand
+- frame-avoid-heavy-computation
+
+## Priority 3: Component Patterns (HIGH)
+- component-jsx-elements
+- component-attach-prop
+- component-primitive
+- component-extend
+- component-forwardref
+- component-dispose-null
+
+## Priority 4: Canvas & Setup (HIGH)
+- canvas-size-container
+- canvas-camera-default
+- canvas-gl-config
+- canvas-shadows
+- canvas-frameloop
+- canvas-events
+- canvas-linear-flat
+
+## Priority 5: Drei Helpers (MEDIUM-HIGH)
+- drei-use-gltf
+- drei-use-texture
+- drei-environment
+- drei-orbit-controls
+- drei-html
+- drei-text
+- drei-instances
+- drei-use-helper
+- drei-bounds
+- drei-center
+- drei-float
+
+## Priority 6: Loading & Suspense (MEDIUM-HIGH)
+- loading-suspense
+- loading-preload
+- loading-use-progress
+- loading-lazy-components
+- loading-error-boundary
+
+## Priority 7: State Management (MEDIUM)
+- state-zustand-store
+- state-avoid-objects-in-store
+- state-subscribeWithSelector
+- state-persist
+- state-separate-concerns
+
+## Priority 8: Events & Interaction (MEDIUM)
+- events-pointer-events
+- events-stop-propagation
+- events-cursor-pointer
+- events-raycast-filter
+- events-event-data
+
+## Priority 9: Post-processing (MEDIUM)
+- postpro-effect-composer
+- postpro-common-effects
+- postpro-selective-bloom
+- postpro-custom-shader
+- postpro-performance
+
+## Priority 10: Physics Rapier (LOW-MEDIUM)
+- physics-setup
+- physics-body-types
+- physics-colliders
+- physics-events
+- physics-api-ref
+- physics-performance
+
+## Priority 11: Leva Debug GUI (LOW)
+- leva-basic
+- leva-folders
+- leva-conditional