@xonovex/skills 0.1.0

package/skills/threejs-guidelines/reference/performance.md

@@ -0,0 +1,24 @@
+# performance: Performance Optimization
+
+**Guideline:** Minimize draw calls with InstancedMesh; use LOD for distance; dispose unused; reuse geometry/materials; profile before optimizing.
+
+**Rationale:** GPU efficiency depends on draw calls and memory; InstancedMesh renders 1000+ copies in one call vs. 1000 separate meshes.
+
+**Example:**
+```javascript
+const mesh = new THREE.InstancedMesh(geometry, material, 1000);
+for (let i = 0; i < 1000; i++) {
+  dummy.position.set(...);
+  dummy.updateMatrix();
+  mesh.setMatrixAt(i, dummy.matrix);
+}
+mesh.instanceMatrix.needsUpdate = true;
+```
+
+**Techniques:**
+- InstancedMesh: Render thousands of copies in one draw call (vs. 1000 draw calls)
+- LOD (Level of Detail): High detail near (0-50), medium mid-range (50-200), low far (200+)
+- Merge geometries: Combine static meshes with BufferGeometryUtils.mergeGeometries()
+- Memory: Dispose geometry/material/texture; reuse between meshes; unload offscreen
+- Rendering: Shadow map 1024×1024; limit lights to 3-5; prefer alphaTest over transparency
+- Profiling: `renderer.info.render.calls` (target <1000), `renderer.info.memory`

package/skills/threejs-guidelines/reference/physics-vr.md

@@ -0,0 +1,36 @@
+# filename: physics-vr
+
+**Guideline:** Use Rapier (or Cannon-es) for physics; sync physics bodies to meshes each frame; use `renderer.setAnimationLoop()` for WebXR.
+
+**Rationale:** Three.js has no built-in physics; external engines require frame-based sync. WebXR requires specific animation loop API.
+
+**Example:**
+```javascript
+// Physics setup
+const world = new RAPIER.World(new RAPIER.Vector3(0, -9.81, 0));
+const bodyDesc = RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 10, 0);
+const body = world.createRigidBody(bodyDesc);
+const shape = RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5);
+world.createCollider(shape, body);
+
+// Sync loop
+function animate() {
+  world.step();
+  const {x, y, z} = body.translation();
+  const {x: qx, y: qy, z: qz, w: qw} = body.rotation();
+  mesh.position.set(x, y, z);
+  mesh.quaternion.set(qx, qy, qz, qw);
+  renderer.render(scene, camera);
+}
+renderer.setAnimationLoop(animate);
+```
+
+**Techniques:**
+- Physics engines: Rapier (recommended), Cannon-es, Oimo; create world with gravity
+- Bodies: RigidBodyDesc dynamic/static/kinematic; add shapes (colliders)
+- Forces: `.applyForce()`, `.applyImpulse()`, `.setLinvel()`, `.setAngvel()`
+- Raycasting: `world.castRay()` for hit detection with physics bodies
+- WebXR setup: `renderer.xr.enabled = true`; `renderer.setAnimationLoop(animate)` (not requestAnimationFrame)
+- XR input: `renderer.xr.getController(0/1)` for controllers; listen to 'select'/'squeeze' events
+- AR hit testing: `frame.getHitTestResults()` returns positions to place objects
+- VR comfort: Minimize latency, avoid sudden motions; limit physics timestep to ≤16.67ms

package/skills/threejs-guidelines/reference/postprocessing.md

@@ -0,0 +1,26 @@
+# postprocessing: Post-Processing Effects
+
+**Guideline:** Use EffectComposer to chain passes (RenderPass→effects→screen); render to intermediate targets for complex pipelines.
+
+**Rationale:** Post-processing applies cinematic effects (bloom, grain, color grading) after rendering without modifying materials.
+
+**Example:**
+```javascript
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+composer.addPass(new UnrealBloomPass(
+  new THREE.Vector2(w, h),
+  1.5,   // Strength
+  0.4,   // Radius
+  0.85   // Threshold
+));
+function animate() { composer.render(); }
+```
+
+**Techniques:**
+- UnrealBloomPass: Glow on emissive materials; adjust threshold for control
+- FilmPass: Grain/noise effect with intensity and grayscale toggle
+- ShaderPass: Custom fragment shader effects with uniforms for animation
+- WebGLRenderTarget: Intermediate render passes for multi-stage pipelines
+- Color grading: ShaderPass with saturation/brightness uniforms
+- Performance: Bloom expensive; SSAO slow; half-res passes for efficiency; only final pass sets renderToScreen

package/skills/threejs-guidelines/reference/scene-fundamentals.md

@@ -0,0 +1,26 @@
+# scene-fundamentals: Scene, Renderer, and Core Concepts
+
+**Guideline:** Configure Scene/Renderer; use Object3D hierarchy with proper dispose patterns; animate with setAnimationLoop and delta time.
+
+**Rationale:** Proper setup ensures memory safety, correct rendering, and frame-rate independence; improper disposal causes memory leaks.
+
+**Example:**
+```javascript
+const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.shadowMap.enabled = true;
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(() => {
+  const delta = clock.getDelta();
+  mesh.rotation.y += delta * 0.5;
+  renderer.render(scene, camera);
+});
+```
+
+**Techniques:**
+- Renderer config: antialias, alpha (transparency), outputColorSpace (sRGB), toneMaps, shadowMap
+- Scene setup: background (color/texture), environment map (PBR), fog, traverse()
+- Object3D: position/rotation/scale, add/remove, visible (hide without disposal), layers, userData
+- Dispose order: geometry → texture → material → renderer (prevents memory leaks)
+- Animation: Use setAnimationLoop() not requestAnimationFrame (WebXR); use delta for frame-rate independence
+- Coordinate system: Right-handed (+X right, +Y up, +Z toward viewer); helpers for debugging

package/skills/threejs-guidelines/reference/shaders.md

@@ -0,0 +1,28 @@
+# filename: shaders
+
+**Guideline:** Use ShaderMaterial with uniforms for parameter control; modify built-in shaders via `onBeforeCompile`; move expensive calculations to vertex shader.
+
+**Rationale:** Custom shaders enable advanced effects; uniform updates avoid recompilation; vertex-side calculations reduce fragment shader load.
+
+**Example:**
+```javascript
+const material = new THREE.ShaderMaterial({
+  uniforms: { time: { value: 0 } },
+  vertexShader: `varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }`,
+  fragmentShader: `varying vec2 vUv;
+    void main() { gl_FragColor = vec4(vUv, 1.0, 1.0); }`
+});
+material.uniforms.time.value = clock.getElapsedTime();
+```
+
+**Techniques:**
+- Uniform types: float, vec2/vec3, Color, sampler2D (texture), Matrix4, arrays
+- Varyings: Pass data vertex→fragment (vUv, vNormal, vWorldPos)
+- Built-in matrices: modelMatrix, modelViewMatrix, projectionMatrix, normalMatrix auto-provided
+- onBeforeCompile: Inject into Three.js shaders using `#include <begin_vertex>` injection points
+- GLSL math: `mix()`, `step()`, `smoothstep()`, `dot()`, `normalize()`, `cross()`
+- Performance: Use `lowp/mediump` precision; minimize branching; move expensive ops to vertex shader

package/skills/threejs-guidelines/reference/textures.md

@@ -0,0 +1,21 @@
+# textures: Texture Loading and Configuration
+
+**Guideline:** Set correct color space per texture type (sRGB for colors, no color space for data), use power-of-2 dimensions, enable mipmaps.
+
+**Rationale:** Color space errors cause washed-out/dark rendering; mipmaps ensure quality at distance; compression saves VRAM.
+
+**Example:**
+```javascript
+const colorTex = loader.load('albedo.jpg');
+colorTex.colorSpace = THREE.SRGBColorSpace;
+const normalTex = loader.load('normal.jpg');
+normalTex.colorSpace = THREE.NoColorSpace; // Data, not color
+```
+
+**Techniques:**
+- Color spaces: sRGB for color/albedo/emissive, NoColorSpace for normal/roughness/metalness/displacement/AO
+- Mipmaps: Auto-generate for most textures; disable for canvas/video (dynamic updates)
+- Wrapping: RepeatWrapping or MirroredRepeatWrapping for tiling; ClampToEdgeWrapping default
+- Filtering: LinearMipmapLinearFilter (smooth, quality), NearestFilter (pixelated retro)
+- Anisotropy: `.anisotropy = renderer.capabilities.getMaxAnisotropy()` for sharp distant angles
+- Compression: KTX2 (best modern), WebP (browser support), Data Textures (procedural)

package/skills/threejs-guidelines/reference/webgpu.md

@@ -0,0 +1,34 @@
+# filename: webgpu
+
+**Guideline:** Use WebGPU for compute shaders and modern GPU features; call `await renderer.init()` before rendering; use TSL for cross-renderer materials.
+
+**Rationale:** WebGPU provides lower CPU overhead, compute shaders, native Metal/DirectX support; async init required for GPU device setup.
+
+**Example:**
+```javascript
+import * as THREE from 'three/webgpu';
+
+const renderer = new THREE.WebGPURenderer({antialias: true});
+renderer.setSize(w, h);
+await renderer.init(); // Required async init
+
+const scene = new THREE.Scene();
+const material = new THREE.MeshStandardNodeMaterial({
+  color: vec3(1.0, 0.0, 0.0)
+});
+const mesh = new THREE.Mesh(geometry, material);
+scene.add(mesh);
+renderer.render(scene, camera);
+```
+
+**Techniques:**
+- Setup: `new THREE.WebGPURenderer()` + `await renderer.init()`; async required for device
+- Fallback: Check `navigator.gpu` before creating; fall back to WebGL if unavailable
+- Compute shaders: `Fn([args], returnType)` defines GPU-side computation; `renderer.compute()` executes
+- Storage: `storageTexture()` and `storageBuffer()` for read/write GPU data
+- TSL materials: Work with both WebGL (→GLSL) and WebGPU (→WGSL) automatically
+- Performance: Lower CPU overhead, better batching, native driver support vs WebGL
+- Debugging: `renderer.info`, `renderer.getDevice()` for device limits/features
+- Limitations: Chrome 113+, Firefox Nightly, Safari TP; no polyfill; mobile support limited
+- Migration: Change import from `'three'` to `'three/webgpu'`; add async init; use TSL for shaders
+- Tips: Use compute for physics/particles; minimize CPU↔GPU transfers; batch similar operations

package/skills/typescript-guidelines/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: typescript-guidelines
+description: >-
+  Trigger on `.ts` files with Node.js/ESM patterns. Use when writing TypeScript code for Node.js ESM projects. Apply for async functions, module imports, type safety, linting. Keywords: TypeScript, ESM, strict mode, async/await, Zod, type inference, avoid barrel exports, process.env, template literals, numeric separators.
+---
+
+# TypeScript Coding Guidelines
+
+## Requirements
+
+- Node.js ESM, TypeScript ≥ 5.8, Vitest ≥ 3, Zod ≥ 4.
+
+## Essentials
+
+- **Strict mode** - Enable strict flags, avoid `@ts-ignore` without comment+issue
+- **Type safety** - Explicit public types, `unknown` over `any`, derive from generated types
+- **Imports** - Named ESM imports, `import type` for types, direct from source, see [reference/avoid-barrel-exports.md](reference/avoid-barrel-exports.md), [reference/avoid-reexports.md](reference/avoid-reexports.md)
+- **Async/await** - Handle errors explicitly, only use `async` with `await`, see [reference/async-without-await.md](reference/async-without-await.md), [reference/unnecessary-async-keywords.md](reference/unnecessary-async-keywords.md)
+- **Immutability** - Use `const`/`readonly` where possible
+- **Validation** - Zod for I/O boundaries, infer types from schemas
+- **Linting** - Never suppress with eslint-disable, fix root causes, see [reference/avoid-eslint-disable.md](reference/avoid-eslint-disable.md)
+- **Template literals** - Convert numbers with `String(value)`, see [reference/template-literals-require-string-conversion.md](reference/template-literals-require-string-conversion.md)
+- **Numeric literals** - Use underscores in large numbers (`30_000`), see [reference/numeric-separator-enforcement.md](reference/numeric-separator-enforcement.md)
+- **Method references** - Keep object references to maintain `this` binding, see [reference/unbound-method-references.md](reference/unbound-method-references.md)
+- **Environment** - Use dot notation for `process.env` access, see [reference/env-access-bracket-notation.md](reference/env-access-bracket-notation.md)
+
+## Progressive disclosure
+
+- Read [reference/async-without-await.md](reference/async-without-await.md) - When seeing async functions that don't use await
+- Read [reference/unnecessary-async-keywords.md](reference/unnecessary-async-keywords.md) - When simplifying synchronous controller functions
+- Read [reference/avoid-eslint-disable.md](reference/avoid-eslint-disable.md) - When tempted to suppress linting warnings
+- Read [reference/template-literals-require-string-conversion.md](reference/template-literals-require-string-conversion.md) - When inserting numbers in template literals
+- Read [reference/numeric-separator-enforcement.md](reference/numeric-separator-enforcement.md) - When writing large numeric literals
+- Read [reference/unbound-method-references.md](reference/unbound-method-references.md) - When passing methods as callbacks or references
+- Read [reference/avoid-barrel-exports.md](reference/avoid-barrel-exports.md) - When creating or importing from index.ts files
+- Read [reference/avoid-reexports.md](reference/avoid-reexports.md) - When organizing module exports
+- Read [reference/env-access-bracket-notation.md](reference/env-access-bracket-notation.md) - When accessing process.env variables

package/skills/typescript-guidelines/reference/async-without-await.md

@@ -0,0 +1,32 @@
+# async-without-await: Only Use Async When Function Contains Await
+
+**Guideline:** Only use `async` when function contains `await` or must return Promise.
+
+**Rationale:** Unnecessary `async` adds overhead and misleads readers about async behavior.
+
+**Example:**
+
+```typescript
+// ❌ Bad: async without await
+const middleware = async (c, next) => {
+  c.set("user", getUser());
+};
+
+// ✅ Good: Remove async
+const middleware = (c, next) => {
+  c.set("user", getUser());
+};
+
+// ✅ Good: Return Promise explicitly if needed
+const middleware = (c, next) => {
+  c.set("user", getUser());
+  return Promise.resolve();
+};
+```
+
+**Techniques:**
+- Review each `async` function for `await` expressions
+- Remove `async` keyword if no `await` found
+- Return `Promise.resolve()` explicitly if signature requires Promise
+- Run ESLint to find @typescript-eslint/require-await violations
+- Verify function behavior unchanged after removal

package/skills/typescript-guidelines/reference/avoid-barrel-exports.md

@@ -0,0 +1,25 @@
+# avoid-barrel-exports: Import Directly from Specific Files
+
+**Guideline:** Avoid `index.ts` barrel exports in subdirectories; import directly from specific files.
+
+**Rationale:** Subdirectory barrels add indirection, obscure source, and cause circular dependency issues.
+
+**Example:**
+
+```typescript
+// ✅ Good: Direct imports, no index.ts
+import {authMiddleware} from "./middlewares/jwt.js";
+import {csrfProtection} from "./middlewares/csrf.js";
+
+// ❌ Bad: Subdirectory barrel exports
+// src/middlewares/index.ts
+export {authMiddleware} from "./jwt.js";
+export {csrfProtection} from "./csrf.js";
+```
+
+**Techniques:**
+- Remove `index.ts` from subdirectories (middlewares, utils, services, controllers)
+- Update imports to specific files directly
+- Use IDE refactoring tools to update all imports automatically
+- Run tests to verify no broken imports
+- Never create new subdirectory barrel exports

package/skills/typescript-guidelines/reference/avoid-eslint-disable.md

@@ -0,0 +1,28 @@
+# avoid-eslint-disable: Never Suppress Warnings - Fix Root Causes
+
+**Guideline:** Never use `eslint-disable`, `@ts-ignore`, or `any` types; fix root causes instead.
+
+**Rationale:** Suppressing warnings hides architectural issues and creates technical debt.
+
+**Example:**
+
+```typescript
+// ❌ WRONG: Suppress error
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+itemsRouter.openapi(listItemsRoute, itemsController.listItems as any);
+
+// ✅ CORRECT: Fix type mismatch
+itemsRouter.openapi(listItemsRoute, (c) => {
+  const {page, limit} = c.req.valid("query");
+  const {items, total} = itemsService.listItems(page, limit);
+  return c.json({items, pagination: {page, limit, total}}, 200);
+});
+```
+
+**Techniques:**
+- Read error message carefully and understand what it indicates
+- Research framework documentation and TypeScript behavior
+- Refactor code to align with type expectations
+- Never use `any`, `@ts-ignore`, or `eslint-disable` comments
+- Verify fix resolves issue completely with type checking
+- Run tests after refactoring to ensure correctness

package/skills/typescript-guidelines/reference/avoid-reexports.md

@@ -0,0 +1,26 @@
+# avoid-reexports: Import from Source Packages Directly
+
+**Guideline:** Import directly from source packages, don't re-export external utilities through your modules.
+
+**Rationale:** Re-exports obscure code origin and complicate dependency understanding.
+
+**Example:**
+
+```typescript
+// ❌ Bad: Re-export from shared packages
+// src/middlewares/jwt.ts
+export {getUserId, type JwtContext} from "@acme/shared-utils";
+
+// ✅ Good: Import directly from source
+import {getUserId, type JwtContext} from "@acme/shared-utils";
+
+// src/middlewares/jwt.ts - only local exports
+```
+
+**Techniques:**
+- Identify files re-exporting from external/shared packages
+- Remove re-export statements from module exports
+- Update consuming code to import directly from source packages
+- Use IDE find-and-replace for bulk import updates
+- Verify imports resolve correctly with type checking
+- Run tests to ensure behavior unchanged

package/skills/typescript-guidelines/reference/env-access-bracket-notation.md

@@ -0,0 +1,29 @@
+# env-access-bracket-notation: Use Dot Notation for process.env
+
+**Guideline:** Use dot notation for `process.env` (not bracket notation) unless dynamic or special chars.
+
+**Rationale:** Dot notation is more idiomatic and improves readability.
+
+**Example:**
+
+```typescript
+// ❌ Bad: Bracket notation for static
+const secret = process.env["JWT_SECRET"];
+
+// ✅ Good: Dot notation for static
+const secret = process.env.JWT_SECRET;
+
+// OK: Bracket for dynamic keys
+const configKey = "MY_VAR";
+const value = process.env[configKey];
+
+// OK: Bracket for special characters
+const value = process.env["MY-VAR-WITH-DASHES"];
+```
+
+**Techniques:**
+- Replace all `process.env["VAR"]` with `process.env.VAR` for static keys
+- Keep bracket notation only for dynamic keys or special characters
+- Run ESLint to find @typescript-eslint/dot-notation violations
+- Verify runtime behavior unchanged after conversion
+- Update all affected import statements and config files

package/skills/typescript-guidelines/reference/numeric-separator-enforcement.md

@@ -0,0 +1,30 @@
+# numeric-separator-enforcement: Use Underscores in Large Numbers
+
+**Guideline:** Use underscores in large numeric literals (e.g., `30_000`) for improved readability.
+
+**Rationale:** Numeric separators improve readability and prevent misreading similar values.
+
+**Example:**
+
+```typescript
+// ❌ Bad: Hard to read
+const timeout = 30000;
+const secondsPerDay = 86400;
+const maxUsers = 1000000;
+
+// ✅ Good: Clear and readable
+const timeout = 30_000;
+const secondsPerDay = 86_400;
+const maxUsers = 1_000_000;
+
+// OK: Smaller numbers don't need separators
+const smallTimeout = 5000;
+const port = 3000;
+```
+
+**Techniques:**
+- Add underscores for numbers >= 10_000 grouped by thousands
+- Do not add separators for smaller numbers (< 10_000)
+- Run ESLint to find numeric-separators-style violations
+- Use consistent grouping by thousands (e.g., 1_000_000 not 100_0000)
+- Verify numeric values are correct after adding separators

package/skills/typescript-guidelines/reference/template-literals-require-string-conversion.md

@@ -0,0 +1,26 @@
+# template-literals-require-string-conversion: Explicitly Convert Numbers in Template Literals
+
+**Guideline:** Explicitly convert numbers to strings in templates using `String(value)`, not implicit coercion.
+
+**Rationale:** Explicit conversion is clearer and avoids relying on implicit type coercion.
+
+**Example:**
+
+```typescript
+// ❌ Bad: Implicit number coercion
+const port = 3000;
+console.log(`Server running on port: ${port}`);
+
+// ✅ Good: Explicit string conversion
+const port = 3000;
+console.log(`Server running on port: ${String(port)}`);
+
+throw new Error(`Timeout after ${String(5000)}ms`);
+```
+
+**Techniques:**
+- Wrap numeric values in `String()` when using template literals
+- Apply to all primitive types in templates (numbers, booleans)
+- Run ESLint to find @typescript-eslint/restrict-template-expressions violations
+- Replace `` `text: ${value}` `` with `` `text: ${String(value)}` ``
+- Verify tests pass after adding explicit conversions

package/skills/typescript-guidelines/reference/unbound-method-references.md

@@ -0,0 +1,32 @@
+# unbound-method-references: Keep Object References for Method Calls
+
+**Guideline:** Keep object reference when calling methods, don't destructure them.
+
+**Rationale:** Destructuring methods breaks `this` binding and causes runtime errors.
+
+**Example:**
+
+```typescript
+// ❌ Bad: Destructuring breaks this
+const {injectWebSocket} = createNodeWebSocket({app});
+injectWebSocket(server); // May fail
+
+// ✅ Good: Keep object reference
+const wsHelpers = createNodeWebSocket({app});
+wsHelpers.injectWebSocket(server); // Maintains this binding
+
+// ❌ Bad: DOM API destructuring
+const {addEventListener} = document;
+addEventListener("click", handler); // Fails
+
+// ✅ Good: Use object reference
+document.addEventListener("click", handler);
+```
+
+**Techniques:**
+- Never destructure methods: avoid `const {method} = object`
+- Keep object reference: `const helpers = object`
+- Call methods on object: `helpers.method()`
+- Use object reference for DOM API calls
+- Run ESLint to find @typescript-eslint/unbound-method violations
+- Refactor destructured methods to keep object references

package/skills/typescript-guidelines/reference/unnecessary-async-keywords.md

@@ -0,0 +1,37 @@
+# unnecessary-async-keywords: Remove Async Keyword Without Await Usage
+
+**Guideline:** Remove `async` from functions that don't use `await`; frameworks allow returning Promises directly.
+
+**Rationale:** Unnecessary `async` adds overhead and creates false async expectations.
+
+**Example:**
+
+```typescript
+// ❌ Bad: async without await
+async function getUser(id: string) {
+  return database.users.find(id);
+}
+
+// ✅ Good: Remove async, return Promise directly
+function getUser(id: string) {
+  return database.users.find(id);
+}
+
+// ❌ Bad: Hono handler with async, no await
+app.get("/users", async (c) => {
+  return c.json(getUsers());
+});
+
+// ✅ Good: Remove async
+app.get("/users", (c) => {
+  return c.json(getUsers());
+});
+```
+
+**Techniques:**
+- Run ESLint to find @typescript-eslint/require-await violations
+- Remove `async` keyword for each flagged function
+- Verify return types still match (Promises ok without `async`)
+- Return Promise directly without `async` wrapper
+- Run tests to ensure behavior unchanged
+- Commit with clear explanation of changes

package/skills/typescript-to-lua-guidelines/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: typescript-to-lua-guidelines
+description: >-
+  Trigger on `.ts` files in game/scripting dirs with TSTL config. Use when transpiling TypeScript to Lua with TSTL 1.24+. Apply for game scripting, clean Lua output, multi-return functions. Keywords: TSTL, TypeScript-to-Lua, namespaces, LuaMultiReturn, decorators, stable tables, coroutines, Lua interop.
+---
+
+# TypeScript-to-Lua Coding Guidelines
+
+## Requirements
+
+- TSTL ≥ 1.24; TS strict mode; Lua ≥ 5.3 / LuaJIT 2.1.
+
+## Essentials
+
+- **Code organization** - Favor namespaces/functions over classes for clean Lua output, see [reference/namespaces-vs-classes.md](reference/namespaces-vs-classes.md), [reference/function-patterns.md](reference/function-patterns.md)
+- **Performance** - Keep tables stable, design for Lua GC and coroutines, see [reference/stable-tables.md](reference/stable-tables.md), [reference/coroutine-patterns.md](reference/coroutine-patterns.md)
+- **TSTL features** - Use LuaMultiReturn, decorators when beneficial, see [reference/multi-return-functions.md](reference/multi-return-functions.md), [reference/tstl-decorators.md](reference/tstl-decorators.md)
+- **Optimization** - Avoid heavy TypeScript features, see [reference/avoiding-heavy-features.md](reference/avoiding-heavy-features.md), [reference/performance-tips.md](reference/performance-tips.md)
+
+## Progressive disclosure
+
+- Read [reference/namespaces-vs-classes.md](reference/namespaces-vs-classes.md) - When choosing code organization for clean Lua output
+- Read [reference/multi-return-functions.md](reference/multi-return-functions.md) - When implementing Lua-style multiple return values
+- Read [reference/function-patterns.md](reference/function-patterns.md) - When defining functions that transpile cleanly
+- Read [reference/module-organization.md](reference/module-organization.md) - When structuring TSTL projects or exports
+- Read [reference/stable-tables.md](reference/stable-tables.md) - When optimizing for Lua GC or JIT performance
+- Read [reference/coroutine-patterns.md](reference/coroutine-patterns.md) - When implementing cooperative multitasking
+- Read [reference/lua-interop.md](reference/lua-interop.md) - When calling Lua code from TypeScript
+- Read [reference/tstl-decorators.md](reference/tstl-decorators.md) - When using TSTL-specific decorators
+- Read [reference/performance-tips.md](reference/performance-tips.md) - When generated Lua code is slow or bloated
+- Read [reference/type-safety.md](reference/type-safety.md) - When maintaining types across TS/Lua boundary
+- Read [reference/avoiding-heavy-features.md](reference/avoiding-heavy-features.md) - When transpiled output is unexpectedly large
+- Read [reference/tsconfig.md](reference/tsconfig.md) - When configuring TSTL compiler options

package/skills/typescript-to-lua-guidelines/reference/avoiding-heavy-features.md

@@ -0,0 +1,41 @@
+# avoiding-heavy-features: Avoiding Heavy TypeScript Features
+
+**Guideline:** Avoid complex inheritance, async/await, and heavy OOP patterns that bloat Lua output.
+
+**Rationale:** Complex features require substantial runtime support and generate verbose Lua. Simpler patterns align with Lua's lightweight nature.
+
+**Example:**
+```typescript
+// AVOID: Heavy inheritance
+class Entity { move() {} }
+class GameObject extends Entity { render() {} }
+class Enemy extends GameObject { attack() {} }
+
+// PREFER: Composition with namespaces
+namespace Physics {
+  export interface Body { x: number; y: number }
+  export function move(b: Body, dx: number) { b.x += dx }
+}
+
+namespace Rendering {
+  export function render(b: Body) { /* draw */ }
+}
+
+// AVOID: async/await
+async function loadData() { return await fetch() }
+
+// PREFER: Generators (become coroutines in Lua)
+function* loadData() {
+  const data = yield fetchAsync()
+  return data
+}
+```
+
+**Techniques:**
+- Use composition patterns instead of inheritance to keep Lua output lightweight
+- Replace async/await with callback functions or coroutines (not supported in Lua)
+- Prefer interfaces and namespaces for code organization over class-based designs
+- Design data structures as plain objects without methods or properties
+- Use function* generators for cooperative multitasking instead of async APIs
+- Keep class hierarchies shallow, prefer interfaces for type contracts
+- Avoid decorators and complex OOP patterns that require runtime support

package/skills/typescript-to-lua-guidelines/reference/coroutine-patterns.md

@@ -0,0 +1,49 @@
+# coroutine-patterns: Coroutine-Friendly Patterns
+
+**Guideline:** Design generators for seamless Lua coroutine integration without runtime overhead.
+
+**Rationale:** Lua coroutines provide cooperative multitasking naturally. TypeScript generators compile to coroutines, enabling timers, sequences, and state machines.
+
+**Example:**
+```typescript
+// Timer using generator/coroutine
+function* timer(seconds: number): Generator<void, void> {
+  let elapsed = 0
+  while (elapsed < seconds) {
+    const delta = yield  // Receives delta-time from Lua
+    elapsed += delta
+  }
+}
+
+// Animation sequence
+function* animatePosition(
+  target: { x: number },
+  endX: number,
+  duration: number
+): Generator<void, boolean> {
+  let elapsed = 0
+  const startX = target.x
+  while (elapsed < duration) {
+    const delta = yield
+    elapsed += delta
+    const progress = elapsed / duration
+    target.x = startX + (endX - startX) * progress
+  }
+  return true
+}
+
+// Chaining coroutines
+function* sequence(): Generator<void, void> {
+  yield* timer(2)           // Wait 2 seconds
+  yield* animatePosition(obj, 100, 1)  // Animate 1 second
+}
+```
+
+**Techniques:**
+- Use `function*` syntax to define generators that compile to Lua coroutines
+- Yield control points with `yield` to pause execution and allow other tasks
+- Accept delta-time as yield result to measure elapsed time accurately
+- Return final values after completion to signal coroutine success or results
+- Chain generators with `yield*` to compose coroutines without overhead
+- Type generators as `Generator<YieldType, ReturnType>`
+- Use for implementing timers, animations, state machines, and task sequences