opencode-skills-collection 4.0.3 → 4.0.5

package/bundled-skills/docs/users/usage.md

@@ -1,28 +1,41 @@
-# Usage Guide: How to Actually Use These Skills
+# Usage Guide: Compose and Use an AAS Skill Stack
 
-> **Confused after installation?** This guide walks you through exactly what to do next, step by step.
+> **Recommended path:** let Codex or Claude use AAS Core to compose a small, policy-controlled stack. Direct installs and manual skill invocation remain supported alternatives.
 
----
+## Primary workflow: agent-first composition
+
+After configuring the local AAS MCP, ask your agent to inspect the repository and recommend a stack for the outcome you want:
+
+```text
+Inspect this repository and use the AAS MCP tools to recommend a small skill stack.
+Explain evidence, exclusions, and unknowns; propose an aas-stack.json; do not apply it.
+```
+
+The agent should use `search_skills`, `get_skill`, and `recommend_stack`, then check the complete proposal with `inspect_stack` and correct every reported issue before presenting it. Review the resulting `aas-stack.json`, validate it with `aas stack validate`, and use `aas stack plan` to preview the exact operations without materializing skills or managed state in the target.
+
+The recommendation is deterministic and local. AAS MCP does not inspect the repository itself, install skills, update catalogs, or change configuration. See [AAS Core](aas-core.md) for setup, the exact tool boundary, CLI commands, and preview limitations.
 
-## "I just installed the repository. Now what?"
+`stack apply` and `stack recover` are experimental, disabled by default, and are not supported or certified preview safety claims.
 
-Great question! Here's what just happened and what to do next:
+---
+
+## Alternative workflow: direct skill installation
 
-If you came in through a **Claude Code** or **Codex** plugin instead of a full library install, the mental model is the same: you still invoke individual skills in prompts. The main difference is that plugins ship the plugin-safe subset. See [plugins.md](plugins.md) for the install model.
+If you came in through a **Claude Code** or **Codex** plugin instead of AAS Core or a full library install, invoke individual skills in prompts. Plugins ship a fixed plugin-safe subset; AAS Core instead composes a project stack from the verified catalog and records it in `aas-stack.json`. See [plugins.md](plugins.md) for the distribution model.
 
-### What You Just Did
+### What direct distribution provides
 
 When you ran `npx agentic-awesome-skills` or cloned the repository, you:
 
-✅ **Downloaded 1,965+ skill files** to your computer (default: `~/.agents/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)
+✅ **Downloaded 1,968+ skill files** to your computer (default: `~/.agents/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)
 ✅ **Made them available** to your AI assistant
 ❌ **Did NOT enable them all automatically** (they're just sitting there, waiting)
 
-Think of it like installing a toolbox. You have all the tools now, but you need to **pick which ones to use** for each job.
+Direct distribution makes skill files available to the host. It does not select a project-specific stack, record desired state, or produce a preview plan; those are AAS Core responsibilities.
 
 ---
 
-## Step 1: Understanding "Bundles" (Recommendations or Focused Installs)
+## Direct-install Step 1: Understanding Bundles
 
 **Common confusion:** "Do I need to download each skill separately?"
 
@@ -32,11 +45,7 @@ Think of it like installing a toolbox. You have all the tools now, but you need
 
 Bundles are **curated groups** of skills organized by role. They help you decide which skills to start using, and they can also be exposed as focused marketplace plugins for Claude Code and Codex.
 
-**Analogy:**
-
-- You installed a toolbox with 1,965+ tools (✅ done)
-- Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools"
-- You can either **pick skills from the tray** or install that tray as a focused marketplace bundle plugin
+Bundles provide editorial shortlists. You can either select individual skills from a bundle or install its focused marketplace plugin where supported.
 
 ### What Bundles Are NOT
 
@@ -73,9 +82,7 @@ If you want only one bundle active at a time in Antigravity, use the activation
 
 ---
 
-## Step 2: How to Actually Execute/Use a Skill
-
-This is the part that should have been explained better! Here's how to use skills:
+## Direct-install Step 2: Invoke a Skill
 
 ### The Simple Answer
 
@@ -126,7 +133,7 @@ Use @brainstorming to plan this feature
 
 ---
 
-## Step 3: What Should My Prompts Look Like?
+## Direct-install Step 3: Write a Focused Prompt
 
 Here are **real-world examples** of good prompts:
 
@@ -182,7 +189,7 @@ Here are **real-world examples** of good prompts:
 
 ---
 
-## Step 4: Your First Skill (Hands-On Tutorial)
+## Direct-install Step 4: Your First Skill
 
 Let's actually use a skill right now. Follow these steps:
 
@@ -210,9 +217,9 @@ Let's actually use a skill right now. Follow these steps:
 
 ---
 
-## Step 5: Picking Your First Skills (Practical Advice)
+## Direct-install Step 5: Pick Skills Manually
 
-Don't try to use all 1,965+ skills at once. Here's a sensible approach:
+Don't try to use all 1,968+ skills at once. Here's a sensible approach:
 
 If you want a tool-specific starting point before choosing skills, use:
 
@@ -327,7 +334,7 @@ AI: [Creates tests, sets up CI/CD, deploys to Vercel]
 
 ### "Can I see all available skills?"
 
-Yes! Three ways:
+Yes. With AAS Core, ask the agent to call `search_skills` and inspect candidates with `get_skill`. On a direct install, you can also:
 
 1. Browse [CATALOG.md](../../CATALOG.md) (searchable list)
 2. Run `ls ~/.agents/skills/` (or your actual install path)
@@ -343,7 +350,7 @@ Usually no, but if your AI doesn't recognize a skill:
 
 ### "Can I load all skills into the model at once?"
 
-No. Even though you have 1,965+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
+No. Even though you have 1,968+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
 
 The intended pattern is:
 
@@ -394,7 +401,13 @@ Use @skill-creator to help me build a custom skill for [your task]
 
 ## Next Steps
 
-Now that you understand how to use skills:
+For the Core-first path:
+
+1. Configure the local MCP with the [AAS Core guide](aas-core.md).
+2. Ask the agent to recommend and explain a small stack.
+3. Review `aas-stack.json`, validate it, and preview the plan.
+
+For direct/manual use:
 
 1. ✅ **Try one skill right now** - Start with `@brainstorming` on any idea you have
 2. 📚 **Pick 3-5 skills** from your role's bundle in [bundles.md](bundles.md)

package/bundled-skills/docs/users/visual-guide.md

@@ -1,26 +1,32 @@
-# Visual Quick Start Guide
+# Visual Guide: AAS Core and Skill Distribution
 
-**Learn by seeing!** This guide uses diagrams and visual examples to help you understand skills.
+This guide shows the primary AAS Core workflow and the supporting catalog and distribution surfaces.
 
 ---
 
 ## The Big Picture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    YOU (Developer)                          │
-│                          ↓                                  │
-│              "Help me build a payment system"               │
-│                          ↓                                  │
-├─────────────────────────────────────────────────────────────┤
-│                  AI ASSISTANT                               │
-│                          ↓                                  │
-│              Loads @stripe-integration skill                │
-│                          ↓                                  │
-│         Becomes an expert in Stripe payments                │
-│                          ↓                                  │
-│    Provides specialized help with code examples             │
-└─────────────────────────────────────────────────────────────┘
+PROJECT
+   │ inspected by Codex or Claude, not by AAS
+   ▼
+EXPLICIT PROJECT PROFILE
+   │
+   ▼
+AAS MCP ── search · inspect · recommend
+   │
+   ▼
+AAS CORE + LOCAL VERIFIED CATALOG
+   │ evidence · exclusions · coverage · unknowns
+   ▼
+AGENT PROPOSES aas-stack.json
+   │
+   ├────────► WORKBENCH (optional browser-local review)
+   ▼
+CLI VALIDATE ──► CLI PLAN ──► HUMAN REVIEW
+
+Supported preview path: stop after plan review.
+Apply and recovery remain experimental.
 ```
 
 ---
@@ -34,7 +40,7 @@ agentic-awesome-skills/
 ├── 📄 CONTRIBUTING.md                  ← Contributor workflow
 ├── 📄 CATALOG.md                       ← Full generated catalog
 │
-├── 📁 skills/                          ← 1,965+ skills live here
+├── 📁 skills/                          ← 1,968+ skills live here
 │   │
 │   ├── 📁 brainstorming/
 │   │   └── 📄 SKILL.md                 ← Skill definition
@@ -47,7 +53,7 @@ agentic-awesome-skills/
 │   │   └── 📁 2d-games/
 │   │       └── 📄 SKILL.md             ← Nested skills also supported
 │   │
-│   └── ... (1,965+ total)
+│   └── ... (1,968+ total)
 │
 ├── 📁 apps/
 │   └── 📁 web-app/                     ← Interactive browser
@@ -66,7 +72,7 @@ agentic-awesome-skills/
 
 ---
 
-## How Skills Work (Flow Diagram)
+## Alternative: Direct Skill Distribution
 
 ```
 ┌──────────────┐
@@ -90,7 +96,7 @@ agentic-awesome-skills/
        │
        ↓
 ┌──────────────┐
-│ 5. RESULT    │  You get specialized help!
+│ 5. RESULT    │  The agent follows the selected instructions
 └──────────────┘
 ```
 
@@ -100,7 +106,7 @@ agentic-awesome-skills/
 
 ```
                     ┌─────────────────────────┐
-                    │  1,965+ SKILLS          │
+                    │  1,968+ SKILLS          │
                     └────────────┬────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
@@ -201,7 +207,7 @@ If you want a workspace-style manual install instead, cloning into `.agent/skill
 │   ├── 📁 brainstorming/                 │
 │   ├── 📁 stripe-integration/            │
 │   ├── 📁 react-best-practices/          │
-│   └── ... (1,965+ total)                │
+│   └── ... (1,968+ total)                │
 └─────────────────────────────────────────┘
 ```
 

package/bundled-skills/docs/vietnamese/AAS_CORE.vi.md

@@ -0,0 +1,28 @@
+# AAS Core
+
+**AAS Core** là lớp điều khiển cục bộ, ưu tiên agent được khuyến nghị cho Agentic Awesome Skills. Core cho phép Codex hoặc Claude Code tìm kiếm và kiểm tra catalog cục bộ đã xác minh, tạo đề xuất stack tối thiểu theo quy tắc xác định, rồi trình bày `aas-stack.json` và kế hoạch CLI để người dùng xem trước khi có bất kỳ thay đổi nào.
+
+> **Ranh giới phát hành:** Gói npm 14.6.0 đã phát hành trước AAS Core và không thể dùng để bootstrap Core. Các gói hỗ trợ Core bắt đầu từ dòng 15.x; chỉ dùng một phiên bản chính xác có release notes tuyên bố rõ rằng nó bao gồm AAS Core.
+
+## Luồng sử dụng
+
+1. Dùng AAS CLI chính thức để cấu hình MCP stdio cục bộ cho Codex hoặc Claude Code.
+2. Cho phép agent gọi `search_skills`, `get_skill` và `recommend_stack`; chỉ dùng `inspect_stack` hoặc `diff_stack` khi cần.
+3. Xem lại tệp `aas-stack.json` do agent đề xuất.
+4. Dùng AAS CLI để xác thực manifest và xem trước kế hoạch chính xác.
+5. Dừng lại sau khi xem kế hoạch; chỉ nghiên cứu các giai đoạn sau nếu bạn chủ động tham gia phát triển preview có kiểm soát.
+
+## Ranh giới tin cậy
+
+- AAS MCP chạy cục bộ và chỉ đọc; MCP không cài đặt, xóa, áp dụng hay cập nhật nội dung.
+- Đề xuất dựa trên quy tắc xác định và bằng chứng trong catalog, không dựa trên một lệnh gọi mô hình ẩn khác.
+- `validate` và `plan` là luồng preview hiện được ghi nhận. `apply` và `recover` bị tắt theo mặc định và chưa phải là cam kết an toàn đã được chứng nhận.
+- Danh tính catalog và runtime được xác minh cục bộ. Theo mặc định, dữ liệu dự án không được gửi tới dịch vụ AAS.
+
+## Quan hệ với plugin và cài đặt trực tiếp
+
+AAS Core là lớp điều phối và ra quyết định. Plugin, plugin chuyên biệt và bản cài đặt thư viện đầy đủ vẫn là các cách phân phối nội dung skill. Với Codex và Claude Code, nên dùng Core để xác định stack tối thiểu trước, rồi mới chọn cách phân phối phù hợp.
+
+Các công cụ chưa có adapter AAS Core vẫn có thể dùng cách cài đặt trực tiếp, plugin hoặc tích hợp manifest tùy chỉnh.
+
+Xem [`docs/users/aas-core.md`](../users/aas-core.md) để biết các lệnh tiếng Anh và yêu cầu cấu hình hiện tại.

package/bundled-skills/docs/vietnamese/README.vi.md

@@ -1,6 +1,10 @@
-# 🌌 Agentic Awesome Skills: 1,936+ Kỹ năng (Skills) cho Claude Code, Gemini CLI, Cursor, Copilot và nhiều hơn nữa
+# AAS Core — Agentic Awesome Skills
 
-> **Thư viện GitHub có thể cài đặt gồm hơn 1,936 kỹ năng agentic cho Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity và các trợ lý lập trình AI khác.**
+> **Ghép stack kỹ năng cục bộ, xác định cho coding agent: từ hồ sơ dự án tường minh đến kế hoạch có thể xem lại trước mọi thay đổi trên target.**
+
+Codex hoặc Claude tự kiểm tra dự án; AAS không quét repository. Agent gửi một hồ sơ tường minh tới AAS MCP cục bộ, chỉ đọc. AAS Core đánh giá hồ sơ và policy dựa trên catalog cục bộ đã xác minh, rồi agent đề xuất `aas-stack.json`; CLI xác thực manifest và tạo kế hoạch preview bất biến trước khi thay đổi kỹ năng.
+
+> **Ranh giới phát hành:** Gói npm 14.6.0 đã phát hành trước AAS Core và không thể dùng để bootstrap Core. Các gói hỗ trợ Core bắt đầu từ dòng 15.x; chỉ dùng một phiên bản chính xác có release notes tuyên bố rõ rằng nó bao gồm Core. Luồng preview được hỗ trợ dừng sau khi xem kế hoạch; `apply` và `recover` vẫn mang tính thử nghiệm. [Tìm hiểu AAS Core](AAS_CORE.vi.md).
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai)
@@ -11,7 +15,7 @@
 [![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode)
 [![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/agentic-awesome-skills)
 
-**Agentic Awesome Skills** là một thư viện kỹ năng có thể cài đặt với **1,936+ kỹ năng `SKILL.md`** được thiết kế để hoạt động mượt mà trên các trợ lý lập trình AI lớn:
+Catalog gồm **1,967+ kỹ năng `SKILL.md`**, plugin chuyên biệt, bundle, workflow và installer trực tiếp vẫn rất quan trọng. Chúng là lớp nội dung, tuyển chọn, phân phối và tương thích xung quanh AAS Core, không phải sản phẩm chính cạnh tranh với Core:
 
 - 🟣 **Claude Code** (Anthropic CLI)
 - 🔵 **Gemini CLI** (Google DeepMind)
@@ -22,11 +26,11 @@
 - ⚪ **OpenCode** (Mã nguồn mở CLI)
 - 🟡 **Kiro CLI / IDE** và **AdaL CLI**
 
-**Phiên bản hiện tại: V14.0.0.** Đây không chỉ là một danh sách prompt; repository này cung cấp kỹ năng, bundles, workflows, catalog sinh tự động và installer CLI để dùng lại các playbook đã được kiểm chứng.
+**Ranh giới phiên bản:** Dòng 14.x là baseline phân phối kỹ năng trực tiếp và không chứa AAS Core; các gói hỗ trợ Core bắt đầu từ dòng 15.x. GitHub là nguồn chuẩn cho Core, catalog, plugin và tài liệu; website được host chỉ là bề mặt duyệt catalog và review trong trình duyệt, không phải control plane được host.
 
 ### 1. 🐣 Bối cảnh: Đây là gì?
 
-**Agentic Awesome Skills** (Phiên bản 14.0.0) là một thư viện kỹ năng lớn cho AI coding assistants.
+**Agentic Awesome Skills** là repository chuẩn của AAS Core. Core là lớp sản phẩm cục bộ và xác định; catalog, bundle, workflow, plugin và installer CLI cung cấp bằng chứng, tuyển chọn, phân phối và khả năng tương thích xung quanh Core.
 
 Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ chuyên biệt**. Chúng không biết "Quy trình Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation".  
 **Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách chính xác trong mọi lần thực thi.
@@ -55,7 +59,7 @@ Repository được tổ chức thành các lĩnh vực chuyên biệt để bi
 
 [Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](BUNDLES.vi.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn.
 
-## Duyệt hơn 1,936 Kỹ năng
+## Duyệt hơn 1,967 Kỹ năng
 
 Chúng tôi đã chuyển danh sách đầy đủ các kỹ năng sang một danh mục riêng biệt để giữ cho file README này gọn gàng.
 

package/bundled-skills/game-development/2d-games/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: 2d-games
-description: "2D game development principles. Sprites, tilemaps, physics, camera."
+description: >-
+  2D game development principles. Sprites, atlases, tilemaps, physics, cameras,
+  and genre patterns (platformer, top-down). Use for canvas/Phaser/Kaplay/Pixi
+  2D games or guest viewports inside hybrid web apps.
 risk: none
 source: community
 date_added: "2026-02-27"
@@ -8,24 +11,30 @@ date_added: "2026-02-27"
 
 # 2D Game Development
 
-> Principles for 2D game systems.
+> Principles for 2D game systems. Pair with `game-development/web-games` / `game-development/engine-selection` for framework choice.
 
 ---
 
-## 1. Sprite Systems
+## Shell vs guest (web)
+
+| Setup | 2D systems live… |
+|-------|------------------|
+| Full-screen 2D game | Entire app (Phaser/Kaplay/Pixi/Canvas) |
+| Hybrid DOM + challenges | Only inside guest viewports; tear down when done |
+
+---
 
-### Sprite Organization
+## 1. Sprite Systems
 
 | Component | Purpose |
 |-----------|---------|
 | **Atlas** | Combine textures, reduce draw calls |
-| **Animation** | Frame sequences |
+| **Animation** | Frame sequences (often 8-24 FPS) |
 | **Pivot** | Rotation/scale origin |
 | **Layering** | Z-order control |
 
 ### Animation Principles
 
-- Frame rate: 8-24 FPS typical
 - Squash and stretch for impact
 - Anticipation before action
 - Follow-through after action
@@ -34,16 +43,12 @@ date_added: "2026-02-27"
 
 ## 2. Tilemap Design
 
-### Tile Considerations
-
 | Factor | Recommendation |
 |--------|----------------|
 | **Size** | 16x16, 32x32, 64x64 |
 | **Auto-tiling** | Use for terrain |
 | **Collision** | Simplified shapes |
 
-### Layers
-
 | Layer | Content |
 |-------|---------|
 | Background | Non-interactive scenery |
@@ -55,8 +60,6 @@ date_added: "2026-02-27"
 
 ## 3. 2D Physics
 
-### Collision Shapes
-
 | Shape | Use Case |
 |-------|----------|
 | Box | Rectangular objects |
@@ -64,9 +67,7 @@ date_added: "2026-02-27"
 | Capsule | Characters |
 | Polygon | Complex shapes |
 
-### Physics Considerations
-
-- Pixel-perfect vs physics-based
+- Pixel-perfect vs physics-based: pick one approach per game
 - Fixed timestep for consistency
 - Layers for filtering
 
@@ -74,14 +75,13 @@ date_added: "2026-02-27"
 
 ## 4. Camera Systems
 
-### Camera Types
-
 | Type | Use |
 |------|-----|
 | **Follow** | Track player |
 | **Look-ahead** | Anticipate movement |
 | **Multi-target** | Two-player |
 | **Room-based** | Metroidvania |
+| **Static** | Board games, modal skill-checks |
 
 ### Screen Shake
 
@@ -103,7 +103,7 @@ date_added: "2026-02-27"
 
 - 8-directional or free movement
 - Aim-based or auto-aim
-- Consider rotation or not
+- Decide whether rotation matters
 
 ---
 
@@ -115,15 +115,18 @@ date_added: "2026-02-27"
 | Complex collision shapes | Simplified collision |
 | Jittery camera | Smooth following |
 | Pixel-perfect on physics | Choose one approach |
+| Orphaned RAF/listeners after a guest closes | Full teardown |
 
 ---
 
 > **Remember:** 2D is about clarity. Every pixel should communicate.
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+
+Use for canvas/Phaser/Kaplay/Pixi 2D systems, or guest viewports inside hybrid web apps.
 
 ## Limitations
+
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/game-development/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: game-development
-description: "Game development orchestrator. Routes to platform-specific skills based on project needs."
+description: >-
+  Game development orchestrator. Routes by platform, dimension, and engine fit
+  (web 2D/3D, hybrid DOM+canvas, narrative tools). Use when starting or
+  structuring a game project, choosing frameworks, or picking among Phaser,
+  PixiJS, Kaplay, Canvas/WebGL, Three.js, Babylon.js, Godot, Unity, or Ink/Twine.
 risk: unknown
 source: community
 date_added: "2026-02-27"
@@ -8,13 +12,13 @@ date_added: "2026-02-27"
 
 # Game Development
 
-> **Orchestrator skill** that provides core principles and routes to specialized sub-skills.
+> **Orchestrator skill** — principles plus routing to specialized sub-skills.
 
 ---
 
 ## When to Use This Skill
 
-You are working on a game development project. This skill teaches the PRINCIPLES of game development and directs you to the right sub-skill based on context.
+You are working on a game development project. This skill teaches PRINCIPLES and directs you to the right sub-skill based on context.
 
 ---
 
@@ -24,7 +28,7 @@ You are working on a game development project. This skill teaches the PRINCIPLES
 
 | If the game targets... | Use Sub-Skill |
 |------------------------|---------------|
-| Web browsers (HTML5, WebGL) | `game-development/web-games` |
+| Web browsers (HTML5, WebGL, WebGPU) | `game-development/web-games` |
 | Mobile (iOS, Android) | `game-development/mobile-games` |
 | PC (Steam, Desktop) | `game-development/pc-games` |
 | VR/AR headsets | `game-development/vr-ar` |
@@ -36,10 +40,11 @@ You are working on a game development project. This skill teaches the PRINCIPLES
 | 2D (sprites, tilemaps) | `game-development/2d-games` |
 | 3D (meshes, shaders) | `game-development/3d-games` |
 
-### Specialty Areas
+### Architecture / tooling
 
 | If you need... | Use Sub-Skill |
 |----------------|---------------|
+| Engine / framework choice, shell vs guest, fit tiers | `game-development/engine-selection` |
 | GDD, balancing, player psychology | `game-development/game-design` |
 | Multiplayer, networking | `game-development/multiplayer` |
 | Visual style, asset pipeline, animation | `game-development/game-art` |
@@ -51,8 +56,6 @@ You are working on a game development project. This skill teaches the PRINCIPLES
 
 ### 1. The Game Loop
 
-Every game, regardless of platform, follows this pattern:
-
 ```
 INPUT  → Read player actions
 UPDATE → Process game logic (fixed timestep)
@@ -64,7 +67,7 @@ RENDER → Draw the frame (interpolated)
 - Rendering: As fast as possible
 - Interpolate between states for smooth visuals
 
----
+**Hybrid / UI-heavy games:** the outer app may be DOM/event-driven; use a classic game loop only in canvas/WebGL viewports (or wherever simulation ticks).
 
 ### 2. Pattern Selection Matrix
 
@@ -76,11 +79,10 @@ RENDER → Draw the frame (interpolated)
 | **ECS** | Thousands of similar entities | RTS units, particles |
 | **Command** | Undo, replay, networking | Input recording |
 | **Behavior Tree** | Complex AI decisions | Enemy AI |
+| **Content-as-data** | Designers ship levels/events without code | JSON/YAML packs |
 
 **Decision Rule:** Start with State Machine. Add ECS only when performance demands.
 
----
-
 ### 3. Input Abstraction
 
 Abstract input into ACTIONS, not raw keys:
@@ -90,10 +92,6 @@ Abstract input into ACTIONS, not raw keys:
 "move"  → WASD, Left stick, Virtual joystick
 ```
 
-**Why:** Enables multi-platform, rebindable controls.
-
----
-
 ### 4. Performance Budget (60 FPS = 16.67ms)
 
 | System | Budget |
@@ -105,14 +103,7 @@ Abstract input into ACTIONS, not raw keys:
 | Rendering | 5ms |
 | Buffer | 1.67ms |
 
-**Optimization Priority:**
-1. Algorithm (O(n²) → O(n log n))
-2. Batching (reduce draw calls)
-3. Pooling (avoid GC spikes)
-4. LOD (detail by distance)
-5. Culling (skip invisible)
-
----
+**Optimization Priority:** Algorithm → Batching → Pooling → LOD → Culling.
 
 ### 5. AI Selection by Complexity
 
@@ -123,8 +114,6 @@ Abstract input into ACTIONS, not raw keys:
 | **GOAP** | High | Emergent, planning-based |
 | **Utility AI** | High | Scoring-based decisions |
 
----
-
 ### 6. Collision Strategy
 
 | Type | Best For |
@@ -145,30 +134,33 @@ Abstract input into ACTIONS, not raw keys:
 | Cache nothing | Cache references |
 | Optimize without profiling | Profile first |
 | Mix input with logic | Abstract input layer |
+| Pick an engine by hype | Match engine to genre + team + delivery target |
 
 ---
 
 ## Routing Examples
 
-### Example 1: "I want to make a browser-based 2D platformer"
-→ Start with `game-development/web-games` for framework selection
-→ Then `game-development/2d-games` for sprite/tilemap patterns
-→ Reference `game-development/game-design` for level design
+### “Browser 2D platformer”
+→ `game-development/engine-selection` → `game-development/web-games` → `game-development/2d-games` → `game-development/game-design`
 
-### Example 2: "Mobile puzzle game for iOS and Android"
-→ Start with `game-development/mobile-games` for touch input and stores
-→ Use `game-development/game-design` for puzzle balancing
+### “UI-heavy web game with small arcade challenges”
+→ `game-development/engine-selection` (shell vs guest) → `game-development/web-games` → `game-development/2d-games` for guests only
 
-### Example 3: "Multiplayer VR shooter"
-→ `game-development/vr-ar` for comfort and immersion
-→ `game-development/3d-games` for rendering
-→ `game-development/multiplayer` for networking
+### “Mobile puzzle”
+→ `game-development/mobile-games` → `game-development/game-design`
+
+### “Multiplayer VR shooter”
+→ `game-development/vr-ar` → `game-development/3d-games` → `game-development/multiplayer`
+
+### “Branching narrative with light stats”
+→ `game-development/engine-selection` (Ink/Twine) → host UI of your choice
 
 ---
 
 > **Remember:** Great games come from iteration, not perfection. Prototype fast, then polish.
 
 ## Limitations
+
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.