@playcraft/skills 0.0.2

package/skills/playcraft-prefab/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: playcraft-prefab
+description: playcraft prefab CLI 全量用法（须带 playcraft 前缀）。与 playcraft-remix-workflow 共用同一 CLI；该技能的「CLI 与 Remix 步骤对照表」与本技能 S1–S4 一致。选主题/schema/metadata 见 remix技能。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你在项目根（或 `--project-dir`）执行命令时**必须写全**：**`playcraft prefab …`**（不要省略 `playcraft`）。
+
+  **与 playcraft-remix-workflow**：Remix 流程里「何时跑 CLI」见该技能中的 **CLI 与 Remix 步骤对照表**；**子命令、分页、过滤、JSON 字段** 以本技能为准。对方负责 **index.ts / theme.schema.json5 / theme.metadata.md / 源码**；你负责 **协议已有后的 list/describe/set/switch/…**。
+
+  **修改原则**：**优先 CLI**（校验、路径、`--json` 的 `summary`/`page`/`guide`）；环境不便或批量编辑更合适时，**允许直接编辑** 当前主题的 `theme.data.json5`（须 JSON5 合法且符合 schema）。PlayCanvas 项目同理：优先 CLI，必要时手改 GameConfig。
+
+  **变体一行话**：External 里 variant = 主题目录名，数据在 `src/theme/<id>/theme.data.json5`；PlayCanvas 里 variant = 场景 id，见 `prefab scenes`。存在 `theme.schema.json5` 即按 External 检测；存在 `assets/DefaultGame.json` 即 PlayCanvas。
+
+  ---
+
+  ### S1：首次摸清「能改什么」（控制上下文）
+
+  1. `playcraft prefab variants`（或 `themes` / `scenes`）确认变体。
+  2. `playcraft prefab list --json` → 读 **`summary`**（`total` / `enabled` / `disabled` / `changed`）和 **`page`**；有 **`page.hasMore`** 就继续 `--offset` 翻页，**不要假定一页即全集**。
+  3. 缩小范围：`--match <regex>`（默认忽略大小写；`--match-case` 区分）、`--used-only` / `--unused-only` / `--changed-only`。
+  4. 找字段名或说明：`playcraft prefab search <regex> --json`。
+  5. 看约束与示例：`playcraft prefab describe <key> --json`（含 **`guide`**）；多 key 时用 `describe --all --json --limit N --offset M`（可加 `--match`）。
+
+  ### S2：只改已有字段（数值 / 开关 / dotpath）
+
+  1. `playcraft prefab describe <key> --json` 确认类型与范围。
+  2. 可选：`playcraft prefab diff --json` 看当前与默认值差异。
+  3. 单字段：`playcraft prefab set <key> <field> <value>`；多字段：`set-batch`（`--file` 或 stdin，JSON：`{ "prefabKey": { "field": value } }`）。
+  4. 验证：`get` 或再跑 `diff`。
+
+  ### S3：启用/禁用整块 prefab
+
+  1. `playcraft prefab list --json` 确认 key。
+  2. `playcraft prefab enable <key>` 或 `disable <key>`。
+  3. 再 `describe` / `set` 填子字段（若需要）。
+
+  ### S4：操作非当前活跃主题
+
+  - 要么：`playcraft prefab switch <themeId>`（External 会写 `src/theme/index.ts`）；
+  - 要么：命令统一加 `--variant <themeId>`（或 PlayCanvas 的 scene id）。
+
+  ---
+
+  ### 命令速查（项目根执行）
+
+  ```bash
+  playcraft prefab variants | themes | scenes
+  playcraft prefab list [--json] [--variant <id>] [--limit N] [--offset M] \
+    [--match <regex>] [--match-case] [--used-only] [--unused-only] [--changed-only] [--with-values]
+  playcraft prefab diff [--json] [同上过滤分页]
+  playcraft prefab describe [key] [--all] [--json] [同上]
+  playcraft prefab search <regex> [--json] [--limit N] [--offset M] [--match-case]
+  playcraft prefab get <key> [field] [--variant <id>]
+  playcraft prefab set <key> <field> <value> [--variant <id>]
+  playcraft prefab set-batch [--file path] [--variant <id>]
+  playcraft prefab enable|disable <key> [--variant <id>]
+  playcraft prefab switch <variant>
+  ```
+
+  ```bash
+  playcraft prefab list --json | jq '.summary'
+  ```
+
+  | 常用选项 | 说明 |
+  |----------|------|
+  | `--variant <id>` | 不指定时：External 用 index.ts 活跃主题；PlayCanvas 用默认 GameConfig |
+  | `--project-dir <path>` | 项目根，默认 cwd |
+
+  ### 失败时
+
+  - 无法识别项目类型：确认 cwd 是否为工程根。
+  - key 不存在：`list --json`。
+  - 校验失败：`describe <key> --json`。
+  - 无效正则：检查 pattern。
+  - 变体不存在：`prefab variants`。
+
+## 我做什么
+
+- 用 CLI（优先）读写已有 prefab 配置；必要时允许手改 data 文件（自担 schema 与语法）
+- 分页检索、diff、批量 `set-batch`
+
+## 何时用我
+
+- 「当前主题改了哪些配置项」「把 layout.baseWidth 改成 800」
+- 「有哪些 prefab key」「启用某块玩法」「切到另一个主题做配置」
+- Agent 已处于 **Remix 工程根**且协议已在 schema 中
+
+## 工作流
+
+1. **bash** — 按 **S1→S2/S3/S4** 选用命令序列（尽量带 `--json` 便于解析）
+2. **read** — 仅当 CLI 无法覆盖时读/写 `theme.data.json5`（须符合 playcraft-remix-workflow 目录约定）
+3. **terminate** — `{ summary: "已修改：…" }`

package/skills/playcraft-project-management/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: playcraft-project-management
+description: PlayCraft 项目管理。查看已有变体、浏览推荐 Remix、从推荐 Remix 创建新变体。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你负责 PlayCraft 项目的查询与创建。
+
+  ## 能力清单
+
+  ### 查询已有变体
+  运行 `playcraft tools list-remixes` 列出用户拥有的变体（Remix）。可加 `--search "<关键词>"` 按名称搜索，支持分页。
+  命令输出摘要到 stdout，详细数据写入文件，用 `read` 工具查看完整结果。
+  返回字段：projectId、branchName、name、templateName、updatedAt、visibility、previewUrl。
+
+  ### 查看推荐 Remix
+  运行 `playcraft tools list-templates` 获取平台推荐 Remix 列表，了解其 ID、名称、类型。
+  命令输出摘要到 stdout，详细数据写入文件，用 `read` 工具查看完整结果。
+
+  ### 创建新变体
+  1. 运行 `playcraft tools list-templates` 获取模板列表
+  2. 根据用户描述选择最匹配的模板
+  3. 运行 `playcraft tools create-remix --project-id <ID> --name "<名称>"` 创建新变体
+  4. 调用 terminate 汇报：项目 ID、名称、模板
+
+  ## 注意事项
+  - Remix（变体）基于推荐 Remix 创建，用户只能创建 Remix
+  - 项目名称应简洁且能反映用户诉求（如"打砖块广告-清明节版"）
+  - 如果用户只是查询项目，直接运行 `playcraft tools list-remixes` 即可，无需创建
+
+## 我做什么
+
+- 查询用户已有的 Remix 变体列表（按名称、日期筛选）
+- 浏览平台推荐 Remix，了解类型和适用场景
+- 根据用户需求选择最合适的 Remix，创建新变体
+
+## 何时用我
+
+- 用户想了解自己有哪些项目时，例如："我的项目有哪些？"、"找一下名字包含'打砖块'的变体"
+- 用户需要创建新项目时，例如："帮我做一个打砖块风格的可玩广告"
+
+## 工作流
+
+### 查询已有变体
+1. **`playcraft tools list-remixes`** — 获取变体列表，可加 `--search` 搜索
+2. **terminate** — 汇报列表结果
+
+### 创建新变体
+1. **`playcraft tools list-templates`** — 获取推荐 Remix 列表
+2. **选择 Remix** — 根据用户描述匹配最合适的
+3. **`playcraft tools create-remix --project-id <ID> --name "<名称>"`** — 用选定 Remix 创建新变体
+4. **terminate** — 汇报 `{ summary: "变体已创建：ID=..., 名称=..., 模板=..." }`

package/skills/playcraft-remix-workflow/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: playcraft-remix-workflow
+description: Remix 工程流程（主题/metadata/schema/新功能）。配置读写须落实在可执行命令：在项目根运行 playcraft prefab（list/describe/set/switch/…）；详见文内「CLI 对照表」。可手改 theme.data.json5 作备选。与 playcraft-prefab 同一套 CLI。
+disable: false
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你指导在 **Remix 工程**里做玩法变体：主题与协议在仓库中的位置、如何向用户提问、何时扩展 schema、何时改源码。
+
+  **与 playcraft-prefab**：二者共用同一套 **`playcraft prefab` CLI**（命令清单以 **playcraft-prefab** 技能为准）。本技能补充 **何时、为何** 在 Remix 里执行这些命令；**不要**只写「用 list」而不写 **`playcraft prefab list`**。
+
+  - **本技能负责**：选/复制主题、改 `src/theme/index.ts`、读/写 `theme.metadata.md`、**编辑 `theme.schema.json5`**、新功能设计协议、改游戏源码。
+  - **配置值读写（已有协议）**：在项目根执行 **`playcraft prefab …`**（优先）；CLI 不便时可手改 `src/theme/<主题>/theme.data.json5`（须符合 schema）。PlayCanvas 工程用 `playcraft prefab scenes` 与 `--variant <sceneId>`。
+
+  ### CLI 与 Remix 步骤对照（均在仓库根目录执行）
+
+  | Remix 步骤 | 建议命令（External 主题工程） |
+  |------------|-------------------------------|
+  | 确认有哪些主题 / 当前活跃 | `playcraft prefab themes --json` |
+  | 用户选定主题后对齐 CLI 上下文 | `playcraft prefab switch <themeId>` **或** 所有后续命令加 `--variant <themeId>` |
+  | 全局摸清 prefab 与启用情况 | `playcraft prefab list --json`（读 `.summary`、`.page`，注意 `.page.hasMore`） |
+  | 按关键词找字段 | `playcraft prefab search '<regex>' --json` |
+  | 看某 key 约束与 `guide` | `playcraft prefab describe <key> --json` |
+  | 看相对默认值改动了什么 | `playcraft prefab diff --json` |
+  | 改一个字段 | `playcraft prefab set <key> <field> <value>` |
+  | 一次改多字段 | `playcraft prefab set-batch --file batch.json`（或 stdin） |
+  | 整块启用/关闭 | `playcraft prefab enable <key>` / `disable <key>` |
+  | PlayCanvas：有哪些场景 | `playcraft prefab scenes --json` |
+
+  `theme.data.json5` 即 CLI 对当前主题写入的配置落盘文件；手改该文件与 CLI 写入应二选一或谨慎合并，避免冲突。
+
+  ## 介绍
+
+  指导修改当前可玩广告工程；产物是基于某一 **theme** 配置呈现的游戏。
+
+  ## 变体原则
+
+  玩法由配置项组合而成，尽量配置化以实现复用与组装。目录见下；**所有 prefab 子命令的完整列表、分页与过滤选项以 playcraft-prefab 技能为准**，本处只固定 **Remix 与 CLI 的衔接**。
+
+  ## 目录结构
+
+  ```
+  ├── assets ← 公共资源
+  ├── SKILL
+  │   ├── SKILL.md                    ← 若存在则读取，了解当前游戏专用技能
+  ├── src
+  │   ├── theme
+  │   │   ├── theme.schema.json5      ← 全局唯一协议：所有 prefab 键与字段定义
+  │   │   ├── theme.metadata.md       ← 各主题玩法摘要（# 主题名 / 玩法要点）
+  │   │   ├── index.ts                ← 仅引用一个主题目录，如 export { default } from "./draft"
+  │   │   ├── draft/
+  │   │   │   ├── theme.data.json5    ← 当前主题最终配置（CLI 优先写入；亦可手改）
+  │   │   │   ├── assets/
+  │   │   └── <其他主题目录>/
+  │   │       └── theme.data.json5
+  ...
+  ```
+
+  ## 初始化流程
+
+  ### 问题 1：选择主题
+
+  - 读取 `src/theme/theme.metadata.md`，向用户展示可选主题与玩法描述。
+  - 选项：① 使用 draft；② 切换到已有主题名；③ 复制某主题为新目录并命名。
+  - 用户确认后：修改 `src/theme/index.ts` 指向选定主题。
+  - **之后改配置值（必绑 CLI）**：先执行 `playcraft prefab switch <themeId>`（会改 `index.ts` 与 CLI 默认主题一致），**或** 不改 index、仅对每条命令加 `--variant <themeId>`。再跑 `playcraft prefab list --json` 确认上下文。
+
+  ### 问题 2：修改需求
+
+  - **摸清能力（先 CLI）**：`playcraft prefab list --json` → `jq '.summary'`；按需 `playcraft prefab search '<关键词>' --json`、`playcraft prefab describe <key> --json`。仍可读 `theme.schema.json5` 补细节，但**不要**只靠通读大文件代替上述命令。
+  - 询问用户今日目标：已有协议内变体 → **场景 1**；新协议 → **场景 2**。
+
+  ## 变体流程（用户提出具体需求后）
+
+  下文以 `src/theme/draft` 为例说明路径；其他主题将 `draft` 换成对应目录名，或对每条命令使用 `playcraft prefab … --variant <themeId>`。
+
+  ### 已有配置项：优先 CLI，可选手改
+
+  - **首选**：上表所列 **`playcraft prefab …`** 全名；机器解析时**加 `--json`**。
+  - **亦可**：直接编辑 `theme.data.json5`（须符合 `theme.schema.json5`、JSON5 合法）。
+  - 协议要求其他工具/技能（生图、路径资源等）时，按协议执行。
+
+  ### 场景 1：需求落在已有协议内
+
+  **默认命令序列**：`playcraft prefab describe <key> --json` → `playcraft prefab set <key> <field> <value>`（或多字段 `set-batch`）→ `playcraft prefab get <key> --json` 或 `diff --json` 复核。CLI 不便时再手改 `theme.data.json5`。
+
+  ### 场景 2：新增功能（协议中尚不存在）
+
+  先结合源码与 schema 注释判断是否允许实现（部分能力可能以库形式封闭并在 schema 中注明）。
+
+  若可实现，以配置优先，典型步骤：
+
+  1. **设计协议项**：与用户澄清细节；将新块写入 **唯一** 的 `src/theme/theme.schema.json5`（JSON Schema + 必要时 `xplatform`，参考 `references/xplatform.schema.json5`）。新 object 建议含 **`enable`，且默认 `false`**，避免旧主题被默认打开。
+  2. **写入配置值**：协议落地后执行 **`playcraft prefab enable <key>`**，再 **`playcraft prefab describe <key> --json`**，然后 **`playcraft prefab set …`** / **`playcraft prefab set-batch …`** 填默认值；亦可手改 `theme.data.json5`。更新 `theme.metadata.md`，未实现前可标【实现中】。
+  3. **实现源码**：按新协议接入游戏逻辑；验收通过后更新 `theme.metadata.md`，去掉【实现中】。
+
+## 我做什么
+
+- Remix 流程：主题选择、metadata、目录与 schema 扩展、新功能实现节奏
+- 在流程中嵌入 **完整 `playcraft prefab …` 命令**；细节与选项见 **playcraft-prefab** 技能
+
+## 何时用我
+
+- 用户要「换主题 / 复制主题 / 理解这个游戏能改什么」
+- 需要改 **theme.schema.json5** 或更新 **theme.metadata.md**
+- 新玩法从零设计协议并实现代码
+
+## 工作流
+
+1. **read** — `theme.metadata.md`；必要时 `theme.schema.json5`
+2. **bash / 用户** — 确认主题；**bash** — `playcraft prefab switch …` 或统一 `--variant`
+3. **bash** — `playcraft prefab list|search|describe|set|…`（完整命令见上表与 playcraft-prefab）
+4. **read / bash** — 场景 2：改 `theme.schema.json5`、`theme.metadata.md`、源码
+5. **terminate** — 简要汇报变更与待验收点

package/skills/playcraft-remix-workflow/references/xplatform.schema.json5

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "平台私有metadata字段协议",
+  "description": "描述PlayCraft平台渲染各字段表单时的辅助数据结构",
+  "required": [
+  ],
+  "properties": {
+    "value_type": {
+      "type": "string",
+      "const": "path",
+      "description": "可选字段，值类型标识。例如 所描述的目标字段若表示文件路径，例如 value: ./assets/xxx.png，则可以添加 value_type: path 用于平台识别后使用文件解析器处理该目标字段",
+      "examples": [
+        "path"
+      ]
+    },
+    "mime_type": {
+      "type": "string",
+      "description": "可选字段，所描述的目标字段若表示文件/文件路径时可以使用。用于指定文件格式，遵循 MIME 规范",
+      "examples": [
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/webp",
+        "audio/mpeg",
+        "application/json"
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/skills/playcraft-save/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: playcraft-save
+description: 原子操作：将 sandbox 中的当前代码（含 dist/ 如已构建）sync 到本地 repo，commit 并 push 到 Git。不触发构建，不上传 COS。
+compatibility: agent
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你负责将项目 sandbox 中的当前状态保存到 Git（sync → commit → push）。
+
+  ## 职责边界
+  - **只负责 Git 保存**，不执行构建，不上传 COS
+  - 若 sandbox 内已有 dist/（之前执行过 build），dist/ 也会随源码一起提交
+  - 保存成功 → terminate 汇报 commitHash
+
+  ## CLI 命令说明
+  - **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**：sync sandbox → commit → push，返回 success + commitHash
+  - **`playcraft tools list-remixes`**：当 projectId 未知时，先查询获取；结果写入文件，stdout 打印摘要，用 `read` 工具查看详细数据
+  - **read**：读取 context.md 获取项目信息和 commit 信息建议
+
+  ## 工作流
+  1. 从 context.md 或 `playcraft tools list-remixes` 获取 projectId 和 branch
+  2. 确定 commitMessage（简洁描述本次变更）
+  3. 运行 **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**
+  4. 成功 → terminate `{ summary: "已保存，commit: <hash>" }`
+  5. 冲突/失败 → terminate `{ summary: "保存失败：<原因>" }`
+
+  ## commitMessage 规范
+  - 简洁描述本次改动，如 "feat: 替换背景图为节日版"、"fix: 修复碰撞检测逻辑"
+  - 若 Manager 在 context.md 中指定了 commitMessage 则直接使用
+
+## 我做什么
+- 将 sandbox 中的最新代码 sync 到本地 repo
+- 创建 Git commit 并推送到远端
+
+## 何时用我
+- 代码修改完成后，只想保存代码（不需要构建或发布预览）
+- 作为 deploy 流程中的中间步骤（build → **save** → publish）
+
+## 工作流
+1. **`playcraft tools save-to-git --project-id <ID> --message "<提交信息>"`**
+2. 成功 → **terminate** `{ summary: "保存成功，commit: <commitHash>" }`
+3. 失败 → **terminate** `{ summary: "保存失败：<error>" }`

package/skills/playcraft-skill-recommender/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: playcraft-skill-recommender
+description: 构建项目前的 Skill 推荐与脚手架工具。在开始任何新游戏项目前必须先调用，根据引擎（threejs/phaser）和意图关键词，自动推荐完整的代码 skill 集合（含引擎层/布局层/输入层/渲染层/动画层/玩法层）和媒体资产（背景图/BGM/SFX/UI 面板），并生成可直接执行的 scaffold 命令。
+triggers: 构建新游戏项目, 选择 skill, 查找可用组件, 3D项目搭建, Three.js项目, Phaser项目
+compatibility: agent,opencode
+---
+
+# playcraft-skill-recommender
+
+## 作用
+
+解决 Agent 遗漏已有 skill 的根本问题：**在构建任何项目之前，先运行此命令，获取完整推荐清单，再动手写代码。**
+
+## Skill Definition
+
+tools:
+
+- bash
+
+prompt_extension: |
+在开始任何新游戏项目之前，你必须先运行 playcraft skills match 获取完整推荐清单。
+在推荐列表中找到对应 skill 后，先读取其 SKILL.md 了解用法，再用 scaffold 命令将 ref 文件复制到项目。
+禁止在未查看推荐列表的情况下手写引擎/布局/输入/渲染/动画代码。
+
+## 三条命令
+
+### 1. `match` — 推荐完整 skill 集合（最常用）
+
+```bash
+playcraft skills match --intent "<关键词,逗号分隔>" [--json]
+# 省略 --engine 时会自动推断引擎（JSON 字段 engineSource=inferred）并输出依赖图 + scaffold
+
+playcraft skills match --engine <threejs|phaser> --intent "<关键词>" [--json]
+# 引擎已定，用 --engine 覆盖自动推断
+```
+
+**示例：**
+
+```bash
+# 三消（自动选定 phaser，一轮即可粘贴到 atom-plan）
+playcraft skills match --intent "match3,grid,tile" --json
+
+# Three.js 3D 棋盘
+playcraft skills match --intent "board,3d,path,animation" --json
+# 或显式：playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+```
+
+**输出结构：**
+
+```
+10 个代码 skill（按层排序）
+  引擎层 → 布局层 → 场景层 → 输入层 → 渲染层 → 动画层 → 玩法层 → 实体层 → UI层
+
+N 类媒体资产（M 个候选）
+  背景图层：多个背景任选其一
+  音频层：多个 BGM + 各类 SFX
+  视觉资产层：结果面板、粒子、Logo、图标…
+
+💡 代码 Scaffold 快捷命令（可直接复制执行）
+🎨 媒体生成提示（参数见各 skill 目录下 manifest.json 的 generation）
+    - 图片：playcraft tools generate-image（--prompt / --aspect-ratio / --image-model / --reference-image 等）
+    - 音效：playcraft tools generate-sfx；BGM：playcraft tools generate-bgm
+    - 本地后处理：playcraft image <子命令>（如 remove-background、convert），见 playcraft-image-processing
+```
+
+### 2. `list` — 列出可用 skill（快速浏览）
+
+```bash
+playcraft skills list [--engine threejs] [--category layout] [--tag 3d] [--json]
+```
+
+### 3. `scaffold` — 将 ref 文件复制到项目（执行脚手架）
+
+```bash
+playcraft skills scaffold \
+  --engine threejs \
+  --atoms grid_board_layout.aicomponent,path_input_handler.aicomponent \
+  --out ./src \
+  [--dry-run] \
+  [--force]
+```
+
+## 推荐算法说明
+
+### 代码 skill 匹配（第一遍）
+
+打分规则（满足任意条件累加，阈值 ≥ 8 进入推荐）：
+
+| 信号                          | 分值  | 说明                   |
+| ----------------------------- | ----- | ---------------------- |
+| `engineVariants[engine]` 存在 | +15   | 有该引擎的专属变体文件 |
+| `renderBackend` 包含该引擎    | +15   | 声明支持该引擎         |
+| `tags` 包含引擎名             | +8    | 标签匹配               |
+| 每个 intent 标签命中 `tags`   | +3/个 | 意图相关               |
+| `imports` 中依赖该引擎 skill  | +5    | 直接依赖链             |
+
+依赖图遍历时，优先使用 `engineVariants[engine].imports`（引擎-aware），避免把其他引擎的依赖拉进来。
+
+### 媒体资产匹配（第二遍，引擎无关）
+
+媒体 skill（`.aiimage` / `.aiaudio` / `.aiconfig`）通过 `bindingRoles` 分组：
+
+- 有 `bindingRoles` 的 skill → 按 role 分组，同 role 多个 = 候选项（任选其一）
+- 无 `bindingRoles` 但有 `background` tag → 归入"背景图"候选组
+- 无 `bindingRoles` 但有 `bgm` tag → 归入"背景音乐"备选
+
+## Skill 目录发现优先级
+
+1. `--skills-dir <path>` 参数
+2. `AGENT_SKILLS_PATHS` 环境变量（逗号分隔）
+3. `<cwd>/node_modules/@playcraft/skills/skills`（项目安装的 skills 包）
+4. `<CLI包>/../../../skills/skills`（monorepo 开发时自动发现）
+
+## Agent 工作流（必须遵守）
+
+```
+开始构建新项目
+  ↓
+① 运行 playcraft skills match --engine <引擎> --intent "<意图关键词>"
+  ↓
+② 阅读推荐清单，确认代码 skill 层级和媒体资产列表
+  ↓
+③ 对每个推荐的代码 skill，读取其 SKILL.md 了解用法
+  ↓
+④ 执行 scaffold 快捷命令，将 ref 文件复制到项目
+  ↓
+⑤ 按各媒体 skill 的 manifest.json（generation）调用 playcraft tools generate-image / generate-sfx / generate-bgm，必要时再跑 playcraft image 后处理
+  ↓
+⑥ 在已有 ref 文件基础上编写项目代码（不要重复造轮子）
+```
+
+**禁止事项：**
+
+- ❌ 未运行 `skills match` 就开始写引擎/布局/输入/渲染代码
+- ❌ 手动猜测 skill 名称（如只搜到 `threejs.aicomponent` 就开始，忽略 `grid_board_layout`）
+- ❌ 对已有 ref 文件重新实现相同功能（如自行写 `BoardLayout3D.ts`）
+
+## 典型案例
+
+**问题**：构建 Three.js 3D 棋盘消除游戏时，未发现 `grid_board_layout.aicomponent`（含现成 `BoardLayout3D.ts`），导致自行实现了一遍棋盘布局逻辑。
+
+**正确做法**：
+
+```bash
+playcraft skills match --engine threejs --intent "board,3d,path,animation"
+# 输出中会明确显示：
+# ── 布局层 ──────────────────────
+# • grid_board_layout.aicomponent [threejs 变体]
+#   Scaffold 文件：
+#     ref/BoardLayout3D.ts → src/game/utils/BoardLayout3D.ts
+#     ref/BoardRenderer3D.ts → src/game/rendering/BoardRenderer3D.ts
+```