opencode-skills-collection 4.0.4 → 4.0.6

package/bundled-skills/docs/users/skills-vs-mcp-tools.md

@@ -1,89 +1,108 @@
-# Skills vs MCP Tools
+# Skills, AAS MCP, and Other MCP Tools
 
-If you are trying to understand the difference between **Antigravity skills** and **MCP tools**, the short version is:
+The short version is:
 
 - **Skills** are reusable `SKILL.md` playbooks that tell an AI assistant how to execute a workflow.
-- **MCP tools** are integrations or callable capabilities that let the assistant interact with external systems.
+- **AAS MCP** is the local, read-only interface through which an agent retrieves the verified AAS catalog without ranking, inspects evidence, and records its exact selected IDs in a proposed stack.
+- **Other MCP tools** connect an assistant to external systems such as APIs, databases, browsers, or hosted services.
+- **The `aas` CLI** validates the durable project profile and agent-selected stack, then previews exact lifecycle operations under human control.
 
-The two are complementary, not competing.
+These surfaces are complementary. AAS Core connects them around the approved `aas-stack.json` manifest.
 
 ## What a skill does
 
 A skill gives the model better instructions for a repeated task such as:
 
-- planning a feature
-- reviewing code
-- running a security audit
-- writing a README
-- debugging a failing test suite
+- planning a feature;
+- reviewing code;
+- running a security audit;
+- writing a README;
+- debugging a failing test suite.
 
-In practice, a skill improves the assistant's decision-making, structure, and process for a task.
+In practice, a skill improves the assistant's decision-making, structure, and process. It remains content, not an executable capability or a grant of authority.
 
-Example:
+Examples:
 
 - `@brainstorming` helps the model clarify requirements before implementation.
-- `@lint-and-validate` helps the model run the right quality checks before claiming success.
+- `@lint-and-validate` helps the model run appropriate quality checks before claiming success.
 
-## What an MCP tool does
+## What AAS MCP does
 
-An MCP tool gives the model a capability it would not otherwise have, such as:
+AAS MCP is part of this repository's product, not an unrelated external integration. Codex or Claude uses it to call the same deterministic AAS Core that powers the CLI projections.
 
-- reading from a database
-- calling GitHub APIs
-- fetching docs from a service
-- creating calendar events
-- querying an external system
+It exposes exactly:
 
-In practice, an MCP tool expands what the assistant can do in the world.
+- `search_skills`;
+- `get_skill`;
+- `compose_stack`;
+- `inspect_stack`;
+- `diff_stack`;
+- the `aas://skills/{id}` resource template.
 
-## The easiest mental model
+The agent inspects the project using its normal local capabilities, searches and reads the complete catalog, and chooses the exact skills. AAS MCP does not scan the repository itself, and Core does not rank or exclude candidates. Catalog metadata is informational only.
+
+AAS MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry. Its tool calls do not install or remove skills, apply a stack, update catalogs, or edit host configuration.
+
+## What other MCP tools do
 
-Use this rule:
+An external MCP tool may give the model a capability it would not otherwise have, such as:
 
-- **Skills tell the assistant how to work.**
-- **MCP tools tell the assistant what systems it can touch.**
+- reading from a database;
+- calling GitHub APIs;
+- fetching documentation from a service;
+- creating calendar events;
+- querying or changing another system.
 
-If you only install tools, the assistant may have access but still behave inconsistently.
+Those tools expand what the assistant can do in the world. Their permissions, network behavior, and write boundaries depend on each server. They are different from the deliberately narrow AAS MCP catalog/composition boundary.
 
-If you only install skills, the assistant may know the workflow but still lack the capability to reach the external system it needs.
+## What the CLI does
 
-Together, they are much stronger.
+The `aas` CLI is the explicit operational interface for:
 
-## Which one should you start with?
+- catalog status and updates;
+- MCP configuration;
+- validation and composition of an agent-selected stack;
+- manifest validation;
+- plan creation and read-only diagnostics.
 
-Start with **skills** if:
+The durable artifact is `aas-stack.json`, which pins catalog identity, targets, the project profile, and exact skill IDs. The agent proposes it; the user reviews it. It has no Core selection policy. `stack validate` checks it, and `stack plan` creates an immutable preview bound to the observed managed state and exact operations.
+
+`stack apply` and `stack recover` exist only for controlled preview development. They are experimental, disabled by default, and are not supported or certified preview safety claims.
+
+## The easiest mental model
 
-- you want better planning, coding, debugging, testing, or review behavior immediately
-- you are working mostly in local files and terminal flows
-- you want reusable playbooks before adding more integrations
+- **Skills provide the operating guidance.**
+- **AAS MCP gives the agent complete catalog access and records the selection the agent makes.**
+- **`aas-stack.json` records what the user approved.**
+- **The CLI validates and previews the lifecycle.**
+- **Other MCP servers provide access to outside systems.**
 
-Start with **MCP tools** if:
+## Which path should you start with?
 
-- your main blocker is access to external systems
-- you need the model to call APIs, query services, or interact with hosted platforms
-- you already like the model's workflow quality, but need more reach
+Start with **AAS Core** when:
 
-Use **both** when:
+- you use Codex or Claude with local MCP support;
+- you want the agent to compose a small stack from project evidence;
+- you need complete catalog access and a reproducible manifest of the agent's exact selection;
+- you want a reviewable plan before any skill changes.
 
-- you want reliable workflows plus external capabilities
-- you are building agent systems, internal tooling, or multi-step operational flows
+Start with a **direct skill or specialized plugin** when:
 
-## How this repo fits in
+- the host does not yet have a native AAS MCP configuration adapter;
+- you already know the exact skill or fixed domain pack you want;
+- you prefer manual invocation without a managed stack lifecycle.
 
-Agentic Awesome Skills is primarily a **skill library**:
+Add **other MCP tools** when the work needs live access to APIs, services, databases, or hosted platforms. A stack can contain skills that guide those integrations without granting the external permissions itself.
 
-- installable `SKILL.md` playbooks
-- bundles for role-based starting points
-- workflows for ordered execution patterns
-- tool-specific guides for Claude Code, Cursor, Codex CLI, Gemini CLI, and others
+## Preview limits
 
-Many skills in this repo also explain how to work with MCP, APIs, and other integrations, but the repository itself is centered on reusable workflow guidance rather than acting as an MCP server.
+AAS Core helps Codex and Claude search and read the complete local catalog, choose exact skill IDs, and preserve them in a reproducible stack. Metadata may be reported as unknown, but it is informational and never blocks selection or use. Apply and recovery remain experimental.
 
 ## Good next reads
 
+- [AAS Core](aas-core.md)
+- [Getting Started](getting-started.md)
 - [FAQ](faq.md)
 - [Bundles](bundles.md)
 - [Workflows](workflows.md)
-- [AI Agent Skills](ai-agent-skills.md)
-- [Codex CLI Skills](codex-cli-skills.md)
-- [Gemini CLI Skills](gemini-cli-skills.md)
+- [Plugins for Claude Code and Codex](plugins.md)

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

@@ -1,28 +1,53 @@
-# Usage Guide: How to Actually Use These Skills
+# Usage Guide: Compose and Use an AAS Skill Stack
+
+> **Recommended path:** let Codex or Claude inspect the project, search and read the complete AAS catalog, and choose the exact skills. AAS Core records and validates that agent-owned selection.
+
+## Primary workflow: agent-first composition
+
+After configuring the local AAS MCP, ask your agent to inspect the repository and choose a stack for the outcome you want:
+
+```text
+Inspect this repository and enumerate its primary capability areas. For each
+capability, search the complete AAS catalog, paginate or refine the query, and
+compare multiple plausible candidates with get_skill when available. Select at
+least one non-redundant valid skill per capability, explicitly report catalog
+gaps, and evaluate architecture/runtime, languages/frameworks, domain behavior,
+data/storage, integrations, testing/quality, security/privacy, UX/accessibility,
+deployment/operations, and maintenance workflow. Mark dimensions not applicable
+instead of silently omitting them. Do not stop at the first few matches or
+optimize for the smallest stack. Core has no semantic policy favoring a small
+stack; each manifest has a technical maximum of 128 selected skills. Only then
+use compose_stack with a project profile, inspect the schema 2 manifest returned
+in memory, and do not apply it.
+```
 
-> **Confused after installation?** This guide walks you through exactly what to do next, step by step.
+The agent must use `search_skills` and `get_skill` across the complete catalog, build a capability-to-skill coverage map, continue searching while a primary capability remains uncovered, choose the exact IDs itself, call `compose_stack`, then check the in-memory proposal with `inspect_stack` before presenting it. All 1,968 current catalog skills remain individually searchable, readable, and selectable. A client or the CLI can persist the reviewed `aas-stack.json`; an audit-enabled flow can then call `export_selection_evidence`, validate it with `inspect_selection_evidence`, and atomically publish the manifest and separate `aas-selection-evidence.json` sidecar in an `artifact-dir`. Use `aas stack plan` to preview the exact operations without materializing skills or managed state in the target.
 
----
+Selection evidence contains the raw `search_skills` queries observed during the MCP session. Do not place secrets, credentials, private source text, or personal data in catalog queries.
+
+Selection belongs to the coding agent. AAS MCP does not inspect the repository itself, rank or exclude skills, 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 validates and records the exact stack the agent selected from the verified catalog 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,969+ 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 +57,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 +94,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 +145,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 +201,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 +229,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,969+ skills at once. Here's a sensible approach:
 
 If you want a tool-specific starting point before choosing skills, use:
 
@@ -327,7 +346,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 +362,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,969+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
 
 The intended pattern is:
 
@@ -394,7 +413,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 search the complete catalog, choose exact IDs, and explain its selection.
+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
+   ▼
+AGENT SEARCHES + READS COMPLETE LOCAL CATALOG
+   │
+   ▼
+CODEX OR CLAUDE CHOOSES EXACT SKILL IDS
+   │
+   ▼
+compose_stack ── validates · pins · never recommends
+   │
+   ▼
+AGENT PROPOSES aas-stack.json (no selection policy)
+   │
+   ├────────► WORKBENCH (optional browser-local review)
+   ▼
+CLI VALIDATE ──► CLI PLAN ──► HUMAN REVIEW
+
+Supported 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,969+ 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,969+ 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,969+ 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,969+ 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à đọc catalog cục bộ đã xác minh, tự chọn chính xác các ID skill, rồi lưu lựa chọn đó trong `aas-stack.json` để người dùng xem trước trước khi có bất kỳ thay đổi nào. Core không xếp hạng hay đề xuất skill.
+
+> **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` và `get_skill`, tự đánh giá kết quả theo ngữ nghĩa, rồi gọi `compose_stack` với `profile` và các ID đã chọn; dùng `inspect_stack` để xác minh và `diff_stack` khi cần so sánh.
+3. Xem lại tệp `aas-stack.json` schema 2 chứa `profile` và đúng thứ tự ID do agent chọn.
+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.
+- Kết quả tìm kiếm đầy đủ, phân trang và có thứ tự catalog ổn định; chúng không chứa điểm số hay thứ hạng. Codex hoặc Claude Code tự đánh giá và chọn skill.
+- `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 truy cập catalog, ghi nhận lựa chọn và xác thực; Codex hoặc Claude Code ra quyết định ngữ nghĩa. 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 để lưu stack do agent chọn 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 tìm kiếm catalog cục bộ đầy đủ theo thứ tự ổn định, tự đánh giá kết quả không có điểm số hay xếp hạng, rồi gửi `profile` cùng chính xác các ID đã chọn tới `compose_stack`. AAS Core ghi nhận lựa chọn trong `aas-stack.json` schema 2; 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,968+ 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.