kiro-kit 0.1.1 → 0.2.0

package/dist/presets/frontend/skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable zip file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a zip file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the zip file (defaults to current directory)
+
+    Returns:
+        Path to the created zip file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    zip_filename = output_path / f"{skill_name}.zip"
+
+    # Create the zip file
+    try:
+        with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {zip_filename}")
+        return zip_filename
+
+    except Exception as e:
+        print(f"❌ Error creating zip file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/presets/frontend/skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+from pathlib import Path
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+    
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+    
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+    
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+    
+    frontmatter = match.group(1)
+    
+    # Check required fields
+    if 'name:' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description:' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+    
+    # Extract name for validation
+    name_match = re.search(r'name:\s*(.+)', frontmatter)
+    if name_match:
+        name = name_match.group(1).strip()
+        # Check naming convention (hyphen-case: lowercase with hyphens)
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+
+    # Extract and validate description
+    desc_match = re.search(r'description:\s*(.+)', frontmatter)
+    if desc_match:
+        description = desc_match.group(1).strip()
+        # Check for angle brackets
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+
+    return True, "Skill is valid!"
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+    
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

package/dist/presets/frontend/skills/threejs/SKILL.md

@@ -1,65 +1,97 @@
----
-name: threejs
-description: Build 3D web experiences with Three.js including scenes, cameras, geometries, materials, lights, animations, and post-processing. Use when creating 3D visualizations or interactive graphics.
----
-
-# Three.js
-
-Activate this skill when building 3D web experiences, visualizations, or interactive graphics.
-
-## When to Use
-
-- Creating 3D scenes and visualizations
-- Building interactive product configurators
-- Implementing animated backgrounds or hero sections
-- Working with WebGL shaders and materials
-- Loading and displaying 3D models (glTF, FBX)
-- Adding post-processing effects
-
-## Core Concepts
-
-- Scene: container for all 3D objects
-- Camera: PerspectiveCamera for most use cases
-- Renderer: WebGLRenderer with proper sizing and pixel ratio
-- Geometry: shape definition (BoxGeometry, SphereGeometry, custom)
-- Material: surface appearance (MeshStandardMaterial for PBR)
-- Light: illumination (AmbientLight + DirectionalLight minimum)
-
-## React Integration (React Three Fiber)
-
-```tsx
-import { Canvas } from '@react-three/fiber';
-import { OrbitControls, Environment } from '@react-three/drei';
-
-function Scene() {
-  return (
-    <Canvas camera={{ position: [0, 0, 5] }}>
-      <ambientLight intensity={0.5} />
-      <directionalLight position={[10, 10, 5]} />
-      <mesh>
-        <boxGeometry args={[1, 1, 1]} />
-        <meshStandardMaterial color="orange" />
-      </mesh>
-      <OrbitControls />
-      <Environment preset="studio" />
-    </Canvas>
-  );
-}
-```
-
-## Performance
-
-- Use instancing for repeated geometries
-- Implement LOD (Level of Detail) for complex scenes
-- Dispose geometries and materials when unmounting
-- Use compressed textures (KTX2, Basis)
-- Limit draw calls and polygon count
-- Use `useFrame` for animations (not setInterval)
-
-## Best Practices
-
-- Always dispose resources on cleanup
-- Use drei helpers for common patterns
-- Implement proper loading states for models
-- Handle WebGL context loss gracefully
-- Test on mobile devices for performance
+---
+name: threejs
+description: >-
+  Build immersive 3D web experiences with Three.js - WebGL/WebGPU library for
+  scenes, cameras, geometries, materials, lights, animations, loaders,
+  post-processing, shaders (including node-based TSL), compute, physics, VR/XR,
+  and advanced rendering. Use when creating 3D visualizations, games,
+  interactive graphics, data viz, product configurators, architectural
+  walkthroughs, or WebGL/WebGPU applications. Covers OrbitControls, GLTF/FBX
+  loading, PBR materials, shadow mapping, post-processing effects (bloom, SSAO,
+  SSR), custom shaders, instancing, LOD, animation systems, and WebXR.
+license: MIT
+version: 1.0.0
+---
+
+# Three.js Development
+
+Build high-performance 3D web applications using Three.js - a cross-browser WebGL/WebGPU library.
+
+## When to Use This Skill
+
+Use when working with:
+- 3D scenes, models, animations, or visualizations
+- WebGL/WebGPU rendering and graphics programming
+- Interactive 3D experiences (games, configurators, data viz)
+- Camera controls, lighting, materials, or shaders
+- Loading 3D assets (GLTF, FBX, OBJ) or textures
+- Post-processing effects (bloom, depth of field, SSAO)
+- Physics simulations, VR/XR experiences, or spatial audio
+- Performance optimization (instancing, LOD, frustum culling)
+
+## Progressive Learning Path
+
+### Level 1: Getting Started
+Load `references/01-getting-started.md` - Scene setup, basic geometries, materials, lights, rendering loop
+
+### Level 2: Common Tasks
+- **Asset Loading**: `references/02-loaders.md` - GLTF, FBX, OBJ, texture loaders
+- **Textures**: `references/03-textures.md` - Types, mapping, wrapping, filtering
+- **Cameras**: `references/04-cameras.md` - Perspective, orthographic, controls
+- **Lights**: `references/05-lights.md` - Types, shadows, helpers
+- **Animations**: `references/06-animations.md` - Clips, mixer, keyframes
+- **Math**: `references/07-math.md` - Vectors, matrices, quaternions, curves
+
+### Level 3: Interactive & Effects
+- **Interaction**: `references/08-interaction.md` - Raycasting, picking, transforms
+- **Post-Processing**: `references/09-postprocessing.md` - Passes, bloom, SSAO, SSR
+- **Controls (Addons)**: `references/10-controls.md` - Orbit, transform, first-person
+
+### Level 4: Advanced Rendering
+- **Materials Advanced**: `references/11-materials-advanced.md` - PBR, custom shaders
+- **Performance**: `references/12-performance.md` - Instancing, LOD, batching, culling
+- **Node Materials (TSL)**: `references/13-node-materials.md` - Shader graphs, compute
+
+### Level 5: Specialized
+- **Physics**: `references/14-physics-vr.md` - Ammo, Rapier, Jolt, VR/XR
+- **Advanced Loaders**: `references/15-specialized-loaders.md` - SVG, VRML, domain-specific
+- **WebGPU**: `references/16-webgpu.md` - Modern backend, compute shaders
+
+## Quick Start Pattern
+
+```javascript
+// 1. Scene, Camera, Renderer
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer();
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+
+// 2. Add Objects
+const geometry = new THREE.BoxGeometry();
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+
+// 3. Add Lights
+const light = new THREE.DirectionalLight(0xffffff, 1);
+light.position.set(5, 5, 5);
+scene.add(light);
+scene.add(new THREE.AmbientLight(0x404040));
+
+// 4. Animation Loop
+function animate() {
+  requestAnimationFrame(animate);
+  cube.rotation.x += 0.01;
+  cube.rotation.y += 0.01;
+  renderer.render(scene, camera);
+}
+animate();
+```
+
+## External Resources
+
+- Official Docs: https://threejs.org/docs/
+- Examples: https://threejs.org/examples/
+- Editor: https://threejs.org/editor/
+- Discord: https://discord.gg/56GBJwAnUS

package/dist/presets/frontend/skills/threejs/references/01-getting-started.md

@@ -0,0 +1,177 @@
+# Getting Started with Three.js
+
+Core concepts for building your first 3D scene.
+
+## Essential Components
+
+Every Three.js app needs 3 core elements:
+
+### 1. Scene
+Container for all 3D objects, lights, cameras.
+
+```javascript
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x000000); // black background
+scene.fog = new THREE.Fog(0xffffff, 1, 5000); // distance fog
+```
+
+### 2. Camera
+Viewpoint into the 3D scene.
+
+**PerspectiveCamera** (realistic, most common):
+```javascript
+const camera = new THREE.PerspectiveCamera(
+  75,  // fov - field of view in degrees
+  window.innerWidth / window.innerHeight,  // aspect ratio
+  0.1,  // near clipping plane
+  1000  // far clipping plane
+);
+camera.position.set(0, 0, 5);
+camera.lookAt(0, 0, 0);
+```
+
+**OrthographicCamera** (no perspective distortion):
+```javascript
+const camera = new THREE.OrthographicCamera(
+  left, right, top, bottom, near, far
+);
+```
+
+### 3. Renderer
+Renders scene using camera perspective.
+
+```javascript
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(window.innerWidth, window.innerHeight);
+renderer.setPixelRatio(window.devicePixelRatio);
+document.body.appendChild(renderer.domElement);
+```
+
+## Basic Geometries
+
+Primitive shapes ready to use:
+
+```javascript
+// Box
+new THREE.BoxGeometry(width, height, depth);
+
+// Sphere
+new THREE.SphereGeometry(radius, widthSegments, heightSegments);
+
+// Plane
+new THREE.PlaneGeometry(width, height);
+
+// Cylinder
+new THREE.CylinderGeometry(radiusTop, radiusBottom, height, radialSegments);
+
+// Cone
+new THREE.ConeGeometry(radius, height, radialSegments);
+
+// Torus
+new THREE.TorusGeometry(radius, tube, radialSegments, tubularSegments);
+```
+
+## Basic Materials
+
+Materials define surface appearance:
+
+**MeshBasicMaterial** - unlit, flat color:
+```javascript
+new THREE.MeshBasicMaterial({ color: 0xff0000 });
+```
+
+**MeshStandardMaterial** - PBR, responds to lights:
+```javascript
+new THREE.MeshStandardMaterial({
+  color: 0x00ff00,
+  metalness: 0.5,
+  roughness: 0.5
+});
+```
+
+**MeshPhongMaterial** - specular highlights:
+```javascript
+new THREE.MeshPhongMaterial({
+  color: 0x0000ff,
+  shininess: 100
+});
+```
+
+## Creating Mesh
+
+Combine geometry + material:
+
+```javascript
+const geometry = new THREE.BoxGeometry(1, 1, 1);
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+```
+
+## Basic Lights
+
+Materials (except Basic) need lights to be visible:
+
+```javascript
+// Ambient - global illumination
+const ambient = new THREE.AmbientLight(0x404040); // soft white
+scene.add(ambient);
+
+// Directional - sun-like, infinite distance
+const directional = new THREE.DirectionalLight(0xffffff, 1);
+directional.position.set(5, 5, 5);
+scene.add(directional);
+
+// Point - lightbulb, radiates in all directions
+const point = new THREE.PointLight(0xff0000, 1, 100);
+point.position.set(0, 10, 0);
+scene.add(point);
+```
+
+## Animation Loop
+
+Continuously render and update scene:
+
+```javascript
+function animate() {
+  requestAnimationFrame(animate);
+
+  // Update objects
+  cube.rotation.x += 0.01;
+  cube.rotation.y += 0.01;
+
+  // Render
+  renderer.render(scene, camera);
+}
+animate();
+```
+
+## Handle Window Resize
+
+Keep aspect ratio correct:
+
+```javascript
+window.addEventListener('resize', () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+## Object3D Hierarchy
+
+Transform and group objects:
+
+```javascript
+const group = new THREE.Group();
+group.add(cube1);
+group.add(cube2);
+scene.add(group);
+
+// Transform
+object.position.set(x, y, z);
+object.rotation.set(x, y, z); // Euler angles
+object.scale.set(x, y, z);
+
+// Hierarchy transforms are relative to parent
+```

package/dist/presets/frontend/skills/threejs/references/02-loaders.md

@@ -0,0 +1,169 @@
+# Asset Loading
+
+Load 3D models, textures, and other assets.
+
+## Loading Manager
+
+Coordinate multiple loads, track progress:
+
+```javascript
+const manager = new THREE.LoadingManager();
+manager.onStart = (url, loaded, total) => console.log('Loading:', url);
+manager.onProgress = (url, loaded, total) => console.log(`${loaded}/${total}`);
+manager.onLoad = () => console.log('Complete');
+manager.onError = (url) => console.error('Error:', url);
+
+const loader = new THREE.TextureLoader(manager);
+```
+
+## GLTF Loader (Recommended Format)
+
+Industry standard, supports PBR materials, animations, bones:
+
+```javascript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+const loader = new GLTFLoader();
+loader.load(
+  'model.gltf',
+  (gltf) => {
+    scene.add(gltf.scene);
+
+    // Access animations
+    const mixer = new THREE.AnimationMixer(gltf.scene);
+    gltf.animations.forEach((clip) => mixer.clipAction(clip).play());
+  },
+  (xhr) => console.log((xhr.loaded / xhr.total * 100) + '% loaded'),
+  (error) => console.error(error)
+);
+```
+
+## FBX Loader
+
+Autodesk format, common in game dev:
+
+```javascript
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+
+const loader = new FBXLoader();
+loader.load('model.fbx', (object) => {
+  scene.add(object);
+});
+```
+
+## OBJ Loader
+
+Simple geometry format:
+
+```javascript
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+
+const loader = new OBJLoader();
+loader.load('model.obj', (object) => {
+  scene.add(object);
+});
+
+// With MTL (material library)
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+
+const mtlLoader = new MTLLoader();
+mtlLoader.load('model.mtl', (materials) => {
+  materials.preload();
+  const objLoader = new OBJLoader();
+  objLoader.setMaterials(materials);
+  objLoader.load('model.obj', (object) => scene.add(object));
+});
+```
+
+## Texture Loader
+
+Load images as textures:
+
+```javascript
+const textureLoader = new THREE.TextureLoader();
+const texture = textureLoader.load('texture.jpg');
+
+// Use in material
+const material = new THREE.MeshStandardMaterial({ map: texture });
+
+// Load with callback
+textureLoader.load(
+  'texture.jpg',
+  (texture) => {
+    material.map = texture;
+    material.needsUpdate = true;
+  },
+  (xhr) => console.log((xhr.loaded / xhr.total * 100) + '% loaded'),
+  (error) => console.error(error)
+);
+```
+
+## Cube Texture Loader
+
+Load environment maps (skybox):
+
+```javascript
+const cubeLoader = new THREE.CubeTextureLoader();
+const envMap = cubeLoader.load([
+  'px.jpg', 'nx.jpg',  // positive x, negative x
+  'py.jpg', 'ny.jpg',  // positive y, negative y
+  'pz.jpg', 'nz.jpg'   // positive z, negative z
+]);
+
+scene.background = envMap;
+material.envMap = envMap;
+```
+
+## DRACO Compressed Models
+
+Smaller file sizes for GLTF:
+
+```javascript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+
+const dracoLoader = new DRACOLoader();
+dracoLoader.setDecoderPath('path/to/draco/');
+
+const loader = new GLTFLoader();
+loader.setDRACOLoader(dracoLoader);
+loader.load('compressed.gltf', (gltf) => scene.add(gltf.scene));
+```
+
+## KTX2 Compressed Textures
+
+GPU-optimized texture compression:
+
+```javascript
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+const ktx2Loader = new KTX2Loader();
+ktx2Loader.setTranscoderPath('path/to/basis/');
+ktx2Loader.detectSupport(renderer);
+ktx2Loader.load('texture.ktx2', (texture) => {
+  material.map = texture;
+  material.needsUpdate = true;
+});
+```
+
+## Common Other Loaders
+
+```javascript
+// STL (3D printing)
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+
+// Collada (.dae)
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+
+// 3DS Max
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+```
+
+## Best Practices
+
+- Use GLTF/GLB for web (best compression, features)
+- Compress with DRACO for large models
+- Use KTX2 for textures (GPU-friendly)
+- Enable caching: `THREE.Cache.enabled = true;`
+- Show loading progress to users
+- Handle errors gracefully