@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/.claude/skills/playcraft-research/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: playcraft-research
+description: PlayCraft 网络研究协议。当本地 Skill 库不足以覆盖需求时触发——包括遇到陌生玩法机制、不熟悉的美术风格、特定音频类型、算法实现参考、需要图片参考等场景。使用 playcraft tools research / fetch-url / search-image 命令（统一鉴权，无需配置额外 key）直接搜索网络，将研究成果融入活 DAG。
+triggers: 本地skill不够,没有现成skill,找不到参考,不了解这个风格,不熟悉这个玩法,陌生机制,需要调研,搜索参考,互联网搜索,研究,需要图片参考,找参考图,视觉参考
+---
+
+# PlayCraft 网络研究协议
+
+## 可用工具（统一鉴权，无需额外配置）
+
+使用 PlayCraft CLI 提供的三个搜索工具：
+
+```bash
+# 文本研究 — Gemini + Google Search grounding，返回综合答案 + 引用来源
+playcraft tools research --query "<问题>" [--focus <领域>] [--json]
+
+# 读取 URL — Gemini 理解指定页面内容，返回结构化摘要
+playcraft tools fetch-url --url "<URL>" [--query "<具体问题>"] [--json]
+
+# 图片搜索 — Unsplash / Pexels 高质量图库，返回可直接用于 --reference-image 的 URL
+playcraft tools search-image --query "<关键词（建议英文）>" [--source unsplash|pexels|auto] [--count 6] [--orientation landscape|portrait|square] [--json]
+```
+
+`--focus` 参数（research 命令）：`gameplay` | `visual` | `audio` | `code` | `compliance`
+
+---
+
+## 何时使用网络研究
+
+**先本地，再网络**。网络研究是本地 Skill 发现的补充，不是替代。
+
+| 场景                                        | 应做什么                                                      |
+| ------------------------------------------- | ------------------------------------------------------------- |
+| `playcraft skills match` 完整匹配           | 直接用，无需研究                                              |
+| 部分匹配，缺少细节                          | 用本地 Skill，补充网络研究缺失部分                            |
+| 完全无匹配                                  | **触发 `research` 文本研究**                                  |
+| 遇到陌生专业名词                            | **触发 `research` 文本研究**                                  |
+| 需要最新数据（2024+ 最佳实践）              | **触发 `research` 文本研究**                                  |
+| 需要视觉参考图（Phase 1 概念图 / 风格探索） | **触发 `search-image` 图片搜索**                              |
+| 生成后不满意，想用参考图引导风格            | **触发 `search-image` → 结果 URL 直接传 `--reference-image`** |
+
+---
+
+## 各角色研究标准流程
+
+### Game Designer — 玩法机制调研
+
+```bash
+# 理解陌生的玩法类型
+playcraft tools research \
+  --query "match-3 mobile game level design best practices difficulty curve" \
+  --focus gameplay --json
+
+# 了解可玩广告设计原则
+playcraft tools research \
+  --query "playable ad game mechanics player retention 15 seconds hook" \
+  --focus gameplay --json
+
+# 读取具体设计文章
+playcraft tools fetch-url \
+  --url "https://www.gamedeveloper.com/design/..." \
+  --query "what are the key level design parameters"
+```
+
+### Artist — 视觉/音频风格调研
+
+```bash
+# 搜索艺术风格生成参数
+playcraft tools research \
+  --query "pixel art 8-bit game sprite limited color palette generation prompt keywords" \
+  --focus visual --json
+
+# 读取调色板数据库
+playcraft tools fetch-url \
+  --url "https://lospec.com/palette-list/..." \
+  --query "what are the exact hex colors and style characteristics"
+
+# 搜索音频风格
+playcraft tools research \
+  --query "chiptune BGM game music BPM range instruments characteristics" \
+  --focus audio --json
+
+# ── 图片搜索（新增）─────────────────────────────────────────────────────────
+
+# 搜索视觉参考图（用于 Phase 1 风格探索）
+playcraft tools search-image \
+  --query "pixel art 8-bit forest game background" \
+  --source pexels --orientation portrait --json
+
+# 搜索元素参考图（用于指导具体 asset 生成）
+playcraft tools search-image \
+  --query "cute cartoon fruit character icon game UI" \
+  --count 4 --json
+
+# 将搜索结果 URL 直接用作参考图（无需先下载）
+playcraft tools generate-image \
+  --prompt "pixel art forest background, 8-bit style, limited color palette" \
+  --reference-image "https://images.unsplash.com/photo-xxxxx" \
+  --output assets/images/bg/background.png \
+  --aspect-ratio 9:16
+```
+
+> **关键提示**：`search-image` 返回的 `downloadUrl` 字段可直接传给 `--reference-image`，CLI 会自动下载，无需手动保存。`--json` 模式返回结构化列表，方便批量选用。
+
+### Developer — 算法/技术实现调研
+
+```bash
+# 搜索具体实现
+playcraft tools research \
+  --query "A* pathfinding javascript tile map Phaser 3 implementation performance" \
+  --focus code --json
+
+# 读取官方文档
+playcraft tools fetch-url \
+  --url "https://phaser.io/docs/3.60.0/Phaser.Physics.html" \
+  --query "how does StaticGroup work with tilemap collision"
+
+# 搜索性能优化
+playcraft tools research \
+  --query "Phaser 3 60fps mobile performance sprite batch rendering optimization" \
+  --focus code --json
+```
+
+### Reviewer — 质量标准调研
+
+```bash
+# 平台合规要求
+playcraft tools research \
+  --query "Google Ads playable ad HTML5 policy requirements file size 2026" \
+  --focus compliance --json
+
+# 读取最新政策文档
+playcraft tools fetch-url \
+  --url "https://support.google.com/google-ads/answer/..." \
+  --query "what are the technical requirements for playable ads"
+
+# 性能基准
+playcraft tools research \
+  --query "web game 60fps performance budget mobile device HTML5 2025" \
+  --focus compliance --json
+```
+
+---
+
+## 研究结果融入活 DAG
+
+研究结果**必须写入 `atom-tree.md`**，否则其他 Agent 无法从中受益。
+
+### 写入格式
+
+```markdown
+<!-- 写入 atom-tree.md 的 `Execution Context` 或 `Revision Notes` -->
+
+### {{atom_id}} — {{slot_name}}
+
+- **本地 Skill**：无匹配（playcraft skills match 返回 0 结果）
+- **文本研究结论**（若执行了 research / fetch-url）：
+  - 命令：`playcraft tools research --query "..." --focus visual --json`
+  - 核心发现：{{1-3 句话，具体且可操作}}
+  - 关键参数：{{数值、关键词、具体配置}}
+  - 引用来源：{{URL}}
+- **图片参考**（若执行了 search-image）：
+  - 命令：`playcraft tools search-image --query "..." --json`
+  - 选用图片：{{description}} — {{downloadUrl}}
+  - 使用方式：作为 `--reference-image` 传入生成命令
+- **实现/生成决策**：{{基于研究的具体方案}}
+- **候选新 Skill**：`{{建议名称}}.{{bundleType}}` — {{为什么值得沉淀}}
+```
+
+### 示例：Artist 研究波普艺术 + 搜图参考
+
+```markdown
+### bg_atom — 背景图层
+
+- 本地 Skill：无匹配
+- 文本研究结论：
+  - 命令：`playcraft tools research --query "pop art game sprite color palette" --focus visual --json`
+  - 核心发现：波普艺术使用 4-6 色高饱和调色板，粗黑轮廓线，网点图案填充
+  - 关键参数：饱和度 >80%，互补色对比，轮廓线 3-5px
+  - 引用来源：lospec.com/palette-list/pop-art
+- 图片参考：
+  - 命令：`playcraft tools search-image --query "pop art colorful bold graphic background" --source unsplash --json`
+  - 选用图片：Bold geometric pop art composition — https://images.unsplash.com/photo-xxxxx
+  - 使用方式：`--reference-image "https://images.unsplash.com/photo-xxxxx"`
+- 生成决策：
+  - prompt: "pop art style, bold black outlines, halftone dots, vivid colors, {{element}}"
+  - style: "vibrant, graphic, flat colors, 1960s comic style"
+  - reference: 上方 Unsplash URL（CLI 自动下载）
+- 候选新 Skill：`pop_art_sprite.aiimage`
+```
+
+---
+
+## "候选新 Skill" 贡献循环
+
+每次网络研究形成可复用方案，在 `atom-tree.md` 的 **Revision Notes** 标注：
+
+```markdown
+### Revision N — {{Agent}} (propose-skill)
+
+- **atomId**: {{atom_id}}
+- **reason**: 本地无 Skill，通过网络研究形成可复用方案
+- **change**: 建议创建：`{{skill_name}}.{{bundleType}}` — {{描述}}，来源：{{URL}}
+```
+
+---
+
+## 研究质量检查
+
+| 检查项                     | 要求                                                                  |
+| -------------------------- | --------------------------------------------------------------------- |
+| **来源可信度**             | 优先官方文档、行业权威；引用来源来自 `--json` 输出的 `citations` 字段 |
+| **信息时效**               | 优先 2024-2026 年内容（在 query 中加年份可提高准确性）                |
+| **可操作性**               | 结论必须直接用于生成参数或代码，不能泛泛而谈                          |
+| **与 StyleDirection 一致** | 视觉研究须与 design-brief 的 StyleDirection 对齐                      |

package/project-template-v2/.claude/skills/playcraft-skill-recommender/SKILL.md

@@ -0,0 +1,382 @@
+---
+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 的根本问题：**在构建任何项目之前，先运行此命令，获取完整推荐清单，再动手写代码。**
+
+---
+
+## 按场景选择命令
+
+| 你的场景                    | 推荐命令             | 说明                                    |
+| --------------------------- | -------------------- | --------------------------------------- |
+| 开始新项目，需要完整推荐    | `match`              | 按引擎+意图输出依赖树+媒体候选          |
+| 探索库里有什么玩法/能力     | `gettags` → `filter` | 先看有哪些 tag，再按 tag 筛选           |
+| 知道需要什么类型的组件      | `filter`             | 按 tags/keywords/category 精确查找      |
+| 想深入了解某个 skill        | `read`               | 输出完整 SKILL.md                       |
+| 了解 skill 包含哪些文件资产 | `inspect`            | 文件清单 + 用途描述（含图集格式）       |
+| 生成 Atom 引入中间文件      | `init-atom-tree`     | 运行 match 并写入 `docs/atom-tree.json` |
+| 选择 atom                   | `select-atom`        | 追加 `meta.selectedAtoms` 并补齐硬依赖  |
+| 将 skill 文件落地到项目     | `scaffold`           | 复制 ref/ 文件到项目目录                |
+| 让 Agent/IDE 持续感知 skill | `link`               | 在 .claude/skills/ 创建符号链接         |
+
+---
+
+## 命令详解
+
+### 1. `match` — 推荐完整 skill 集合（新项目首选）
+
+```bash
+# 自动推断引擎
+playcraft skills match --intent "<关键词,逗号分隔>" --json
+
+# 指定引擎
+playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
+```
+
+**适用时机**：你已经知道要做什么类型的游戏，需要一次性获取完整的技术栈推荐。
+
+**输出结构**：
+
+- 代码 skill（按层排序：引擎层 → 布局层 → 场景层 → 输入层 → 渲染层 → 动画层 → 玩法层 → UI层）
+- 媒体资产候选（按 bindingRole 分组：背景图、BGM、SFX、面板等，每组多个候选任选其一）
+- Scaffold 快捷命令（可直接复制执行）
+
+**示例**：
+
+```bash
+# 三消游戏
+playcraft skills match --intent "match3,grid,tile,eliminate" --json
+
+# 麻将收集消除
+playcraft skills match --intent "mahjong,tile,match,stacking,puzzle" --json
+
+# Three.js 3D 棋盘
+playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+```
+
+---
+
+### 2. `gettags` — 发现库里有哪些标签
+
+```bash
+# 看 gameplay 类 skill 有哪些 tag
+playcraft skills gettags --category gameplay --json
+
+# 看所有 tag
+playcraft skills gettags --json
+```
+
+**适用时机**：你不确定库里有什么，想先了解标签空间，再决定怎么筛选。
+
+**输出**：去重排序的 tag 列表。
+
+**典型用法**（启发阶段）：
+
+```bash
+# Step 1: 看 gameplay 下有什么玩法标签
+playcraft skills gettags --category gameplay --json
+# → ["billiards","casual","core","eliminate","grid","match3","physics","puzzle","stacking",...]
+
+# Step 2: 发现 "billiards" 标签，筛选相关 skill
+playcraft skills filter --category gameplay --tags billiards --json
+```
+
+---
+
+### 3. `getkeywords` — 发现库里有哪些关键词
+
+```bash
+playcraft skills getkeywords --category gameplay --json
+playcraft skills getkeywords --json
+```
+
+**适用时机**：当 tag 维度找不到想要的内容时，keywords 覆盖同义词、中文词、行为动词等补充检索维度。
+
+---
+
+### 4. `filter` — 多维度精确筛选
+
+```bash
+playcraft skills filter --tags "<tag1,tag2>" [--keywords "<kw1,kw2>"] [--category "<cat>"] [--role "<role>"] [--and] [--json]
+```
+
+**参数说明**：
+
+| 参数         | 作用                                                        | 默认行为           |
+| ------------ | ----------------------------------------------------------- | ------------------ |
+| `--tags`     | 按 manifest.tags 匹配                                       | OR（命中任一即可） |
+| `--keywords` | 按 manifest.keywords 匹配                                   | OR                 |
+| `--category` | 按 manifest.category 过滤（逗号分隔多选）                   | OR                 |
+| `--role`     | 按 manifest.bindingRoles 匹配（逗号分隔）                   | OR                 |
+| `--and`      | 维度内改为 AND（必须同时命中所有）                          | 不加则 OR          |
+| `--json`     | 输出详细 JSON（含 label, tags, bindingRoles, gameplayType） | 无则文本格式       |
+
+**维度间关系**：跨维度始终是 AND — 即 `--tags match3 --category gameplay` 要求同时满足 tag 含 match3 且 category 是 gameplay。
+
+**`--json` 输出格式**：
+
+```json
+[
+  {
+    "atomId": "match3_core.aigameplay",
+    "category": "gameplay",
+    "bundleType": "aigameplay",
+    "mode": "fixed",
+    "label": { "zh": "三消核心玩法", "en": "Match-3 core gameplay" },
+    "tags": ["gameplay", "match3", "casual", "grid", "eliminate", "core"],
+    "bindingRoles": ["gameplayRule"],
+    "gameplayType": "match3"
+  }
+]
+```
+
+**示例**：
+
+```bash
+# 找所有 gameplay 类的 puzzle 相关 skill
+playcraft skills filter --category gameplay --tags puzzle --json
+
+# 找同时有 phaser 和 animation 标签的 skill
+playcraft skills filter --tags "phaser,animation" --and --json
+
+# 找 match3 相关的所有东西（跨 category）
+playcraft skills filter --tags match3 --json
+
+# 找含 "台球" 关键词的 skill（中文搜索）
+playcraft skills filter --keywords "台球" --json
+
+# 找所有 UI 组件
+playcraft skills filter --category ui --json
+
+# 按 role 查找：谁能扮演 "背景音乐" 角色
+playcraft skills filter --role bgMusic --json
+
+# 按 role 查找：谁能扮演 "贴图集" 角色
+playcraft skills filter --role tileTextureSet --json
+
+# 组合：找 gameplay 中声明了 gameplayRule 角色的 skill
+playcraft skills filter --category gameplay --role gameplayRule --json
+```
+
+---
+
+### 4.1 理解 Role（bindingRole）
+
+**Role 是什么**：每个 skill 可以声明它能扮演的"语义角色"（`manifest.bindingRoles`）。Role 回答的是"这个 skill 在依赖图中能填什么槽位"。
+
+**典型场景**：`match` 推荐结果中的 `mediaGroups` 按 role 分组展示候选。当你想替换某个候选或查看同 role 下还有哪些选择时，用 `filter --role` 查询。
+
+**常见 role 举例**：
+
+| role                   | 含义            | 典型 provider                                    |
+| ---------------------- | --------------- | ------------------------------------------------ |
+| `bgMusic`              | 背景音乐        | `calm_piano`, `cheerful_ukulele`, `bg_music`     |
+| `tileTextureSet`       | 牌面/瓦片贴图集 | `candy_tile`, `fruit_tile`, `tile-sheets-normal` |
+| `backgroundTexture`    | 场景背景图      | `forest`, `castle`, `game-backgrounds`           |
+| `gameplayRule`         | 玩法规则实现    | `match3_core`, `car_parking`, `eight_ball_pool`  |
+| `successFeedbackPanel` | 胜利面板        | `win_result_panel`                               |
+| `failFeedbackPanel`    | 失败面板        | `lose_result_panel`                              |
+
+**操作流程（role 替换）**：
+
+```
+① match --json → 看到 mediaGroups 中某个 role 的候选
+② 对候选不满意 → filter --role <role> --json → 查看该 role 的所有 provider
+③ read <想用的 atomId> → 确认适合
+④ 通过 `select-atom` 将选中的 atomId 写入 atom-tree.json 的 `meta.selectedAtoms` shortlist
+```
+
+---
+
+### 5. `read` — 深读某个 skill 的完整文档
+
+```bash
+playcraft skills read "<atomId>"
+```
+
+**适用时机**：已经确定要用某个 skill，需要了解其 API、配置项、集成方式。
+
+**示例**：
+
+```bash
+playcraft skills read "match3_core.aigameplay"
+playcraft skills read "tile-slot-storage-phaser"
+playcraft skills read "countdown-ui-phaser"
+```
+
+---
+
+### 5.1 `inspect` — 查看 skill 的文件资产清单
+
+```bash
+playcraft skills inspect "<atomId>"          # 人读格式
+playcraft skills inspect "<atomId>" --json   # JSON 格式
+```
+
+**适用时机**：`read` 之前想先快速确认这个 skill 包了什么文件、图片资产的格式和使用方式，而不必读完整个 SKILL.md。尤其对包含图集、spritesheet、多文件资产的 skill 有用。
+
+**输出两个区块**：
+
+- **Scaffold 文件**：`scaffold` 命令会复制的路径列表（dest → source → mode）
+- **Files 列表**：skill 内所有登记文件的路径 + 用途说明（含图集裁切方式、运行时使用注意等）
+
+**示例**：
+
+```bash
+# 了解台球场景 skill 包含哪些图集和资产
+playcraft skills inspect billiards-shot-scene-phaser
+
+# 了解 Phaser 引擎骨架包含哪些文件
+playcraft skills inspect phaser.aicomponent --json
+```
+
+---
+
+### 6. `scaffold` — 将 ref 文件复制到项目
+
+```bash
+playcraft skills scaffold \
+  --engine <threejs|phaser> \
+  --atoms <atomId1,atomId2,...> \
+  --out ./src \
+  [--dry-run] [--force]
+```
+
+**scaffold 语义**：scaffold 不是临时代码草稿。文件一旦落地,就成为当前项目 runtime 的实现基座。后续 developer 应优先 `adopt-scaffold` / `configure-scaffold` / `extend-scaffold`,只有在任务卡的 `scaffoldValue` 与实际代码不匹配时才 `use-as-reference` 或 `reject-for-slice`,并在 handoff 记录原因。不要一边保留 scaffold 文件,一边静默重写同一能力。
+
+**命令输出**：
+
+- `--dry-run` 与实际执行都会打印每个文件的 `source → dest`,例如 `ref/BoardLayout.ts → game/scenes/GameUI/BoardLayout.ts`。
+- 如果 atom 有硬依赖,会打印 `[import-link] [当前 atom] 依赖 atom -> skill 目录`,用于提醒后续还要读依赖 skill。
+- 实际执行会生成或更新 `docs/scaffold-manifest.md`,记录本次 scaffold 的 atom 与落地文件。
+
+**developer 摄入规则**：
+
+- 开始实现时,如果 `docs/scaffold-manifest.md` 存在或在 dispatch `requiredContext` 中,先读它,再读对应 `.claude/skills/<atomId>/SKILL.md`、关键 `ref/` 源码和已落地文件。
+- `docs/scaffold-manifest.md` 当前主要记录 atom 和目标文件;若需要确认来源文件、mode 或依赖,使用 context 阶段留下的任务卡 `sourceOfTruth`,或回看 `playcraft skills inspect <atomId>` / scaffold 输出。
+- scaffold 后继续编码前,必须重新读取落地文件。落地文件是当前项目现实,`ref/` 是来源真相,二者都不能被未读重写。
+
+---
+
+### 7. `init-atom-tree` / `select-atom` — 维护 Atom 引入中间文件
+
+```bash
+# 先由推荐器运行 match,生成 docs/atom-tree.json 的 meta.skillsMatch 快照
+playcraft skills init-atom-tree --intent "<genre,core-action,feedback>" --engine <phaser|threejs>
+
+# 从 meta.skillsMatch.items 里选择要进入本项目的 atom,逗号分隔可批量
+playcraft skills select-atom --id "<atomId1,atomId2>"
+
+# 校验选择集合,然后把 selectedAtoms link 到 .claude/skills/
+playcraft skills validate-atom-tree-selection
+playcraft skills link --from-atom-tree --prune
+
+# 可选:生成人读指南 docs/atom-tree.md
+playcraft skills gen-atom-tree-md
+```
+
+**适用时机**：context 阶段需要把 design 结果和 Skill 推荐固化成 Atom 引入链路时。atom-tree 是中间产物,用于完成 atom 的选择、link、模板初始化和 scaffold,不承载任务计划、执行日志或 handoff 状态。
+
+**输出结构**：
+
+- `docs/atom-tree.json`：Atom 引入中间文件，包含 `meta.engineDecision`、`meta.skillsMatch`、`meta.selectedAtoms`；应由本命令族维护，避免手写完整 JSON (JavaScript Object Notation, JavaScript 对象表示法)。
+- `docs/atom-tree.md`：可选人读 companion，由 `gen-atom-tree-md` 生成，只用于辅助阅读，不作为第二份真源。
+
+`meta.skillsMatch` 由 `init-atom-tree` 写入；`meta.selectedAtoms` 由 `select-atom` 写入，是 `link --from-atom-tree` 和 `remix init-template --from-atom-tree` 的输入。
+
+---
+
+### 8. `link` — 创建符号链接（IDE 感知）
+
+```bash
+playcraft skills link --atoms <atomId1,atomId2,...> [--prune]
+playcraft skills link --from-atom-tree --prune
+```
+
+**输出位置**：
+
+- 每个 selected atom 会链接到项目内 `.claude/skills/<atomId>/`。
+- 链接清单写入 `.claude/skills/.playcraft-dag-links.json`。
+- 下游 developer 应优先读取项目内 `.claude/skills/<atomId>/SKILL.md` 与 `.claude/skills/<atomId>/ref/...`;`playcraft skills read/inspect` 只作为链接缺失时的兜底。
+
+---
+
+## 推荐算法说明
+
+### 代码 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 → 归入"背景音乐"备选
+
+---
+
+## 工作流指南
+
+### 流程 A：新项目（从零开始）
+
+```
+① match → ② inspect 各个 skill（了解包含哪些文件） → ③ read 各个 skill（深读 API） → ④ 在 todo 写 scaffoldValue / sourceOfTruth → ⑤ scaffold → ⑥ developer 读 scaffold-manifest 和落地文件后编码
+```
+
+### 流程 B：启发探索（不确定做什么）
+
+```
+① gettags --category gameplay → 了解有哪些玩法类型
+② filter --category gameplay --tags <感兴趣的> --json → 看相关 skill 列表
+③ read <某个 aigameplay skill> → 深入了解规则和变体
+④ 决定方向后 → match --intent <确定的关键词> → 获取完整推荐
+```
+
+### 流程 C：中途查找（开发中需要某个能力）
+
+```
+① filter --tags <能力关键词> --json → 找到候选
+② inspect <atomId> → 快速确认文件资产
+③ read <atomId> → 确认 API 和用法
+④ 判断 scaffoldValue 是否服务当前 slice → ⑤ scaffold/link → 落地 → ⑥ 读 scaffold-manifest 和落地文件后集成
+```
+
+---
+
+## Skill 目录发现优先级
+
+1. `--skills-dir <path>` 参数
+2. `AGENT_SKILLS_PATHS` 环境变量（逗号分隔）
+3. `<cwd>/node_modules/@playcraft/skills/playcraft-skills`（项目安装的 skills 包）
+4. `<CLI包>/../../../skills/playcraft-skills`（monorepo 开发时自动发现）
+
+---
+
+## Agent 禁止事项
+
+- ❌ 未运行 `skills match` 就开始写引擎/布局/输入/渲染代码
+- ❌ 手动猜测 skill 名称（如只搜到 `phaser.aicomponent` 就开始，忽略 `grid_board_layout`）
+- ❌ 对已有 ref 文件重新实现相同功能
+- ❌ 使用 `filter` 找到 skill 后不 `read` 就直接引用（先了解 API 再使用）
+- ❌ scaffold 含图集/多帧资产的 skill 前不 `inspect`（会误解图集格式和裁切方式）
+- ❌ scaffold 后不读 `docs/scaffold-manifest.md` 和落地文件,直接另写一套同能力实现