@playcraft/cli 0.0.44 → 0.0.46

package/project-template/.claude/skills/playcraft-playable-optimization/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: playcraft-playable-optimization
+description: >-
+  Loop 3 optimization toolkit for PlayCraft playable ads: video validate loop,
+  image validator, headed MP4 recording, FX/animation polish, and L→G focus
+  playground. Use during development ready-state, ui_review/ui_rework, and the
+  optional ring 4 deep optimization after final Ring Gate.
+allowed-tools:
+  - Bash(npm run state:get:*)
+  - Bash(npm run ensure:project:*)
+  - Bash(npm run verify:ui:*)
+  - Bash(npm run record:mp4:*)
+  - Bash(npm run playground:*)
+  - Bash(npm run sweep:L1:*)
+  - Bash(npm run sweep:G1:*)
+  - Bash(npm run repack:frames:*)
+  - Read
+  - Write
+  - Edit
+---
+
+# PlayCraft Playable Optimization Toolkit
+
+Abbreviations used here: UI (User Interface, 用户界面), MP4 (MPEG-4 Part 14, 视频容器格式), FX (Effects, 特效), ASR (Asset State Reference, 资产状态参考).
+
+> **定位**：PlayCraft 三 loop 中 **Loop 3（优化模板）** 的执行引擎。不改 PlayCraft 的 Agent 编排，只提供工具 + 调用协议。
+>
+> **给谁用**：Developer（build 收尾）、Reviewer（ring 4 verify / optional optimization）、Developer / TA / Artist（ui_diff 修复）。
+
+---
+
+## 起手式（每次调用前必做）
+
+```bash
+npm run state:get -- --json
+npm run ensure:project
+```
+
+先读 `state:get`，只运行 `nextCommands` / `currentRingVerifiers` 中已经披露的工具。`ensure:project` 只做目录、脚本和依赖准备，不代表当前 Ring 必须跑 UI / MP4 验证。
+
+`ensure:project` 会：
+
+- 检查/创建 `recordings/`、`validate/`、`focus-lab/`、`playground/`。
+- 若无 `playable.ui.profile.yaml` 则从 template 复制一份。
+- 合并 `package.json` scripts。
+- 自动 `npm install` + `npx playwright install chromium`（首次）。
+
+PlayCraft 是 **Vite** 项目，`ensure-project` 会检测到 `vite.config.ts` + 根目录 `index.html`，不会要求 `game/index.html`。
+
+---
+
+## 与 PlayCraft growth-rings 的接点
+
+| iteration / loop               | 谁调用                  | 调用什么                                   | 产出                           |
+| ------------------------------ | ----------------------- | ------------------------------------------ | ------------------------------ |
+| ring 1 `loop: build`（收尾）   | Developer               | `state:get` 披露的 contract/lifecycle/firstwin | 轻量 HOOK 生命周期 + 首关可胜 |
+| ring 2+ `loop: build`（收尾）  | Developer               | 仅运行 `state:get.nextCommands` 中的 `verify:ui` / `record:mp4` | 当前 Ring 证据 |
+| ring 4 `loop: verify`          | Reviewer                | `verify:ui` → `playwright-cli` 截图        | asset/layout 先行拦截          |
+| ring 4 verify ui_diff fail     | Developer / TA / Artist | 读 `playable-validate` 子 skill 做最小 fix | 修复后重跑 verify + record     |
+| ring 4 optional optimization   | Reviewer / Orchestrator | `playable-validate` loop                   | `validate/PLAYABLE-*.md` + MP4 |
+
+---
+
+## 一句话指令表
+
+| 用户/Agent 意图          | 命令/入口                                                              |
+| ------------------------ | ---------------------------------------------------------------------- |
+| 查看当前可运行命令       | `npm run state:get -- --json`                                          |
+| 整片优化到可交付         | 读 `skills/playable-validate/SKILL.md` § Agent 入口                    |
+| 检查 UI / atlas / layout | 仅当 `state:get.nextCommands` 披露：`npm run verify:ui`                |
+| 录完整局 headed MP4      | 仅当 `state:get.nextCommands` 披露：`npm run record:mp4 -- --headed --fps=60` |
+| 只录某个 focus zone      | `npm run record:focus -- --scope=PHASE --fixture=endcard-win --headed` |
+| 优化 match 碎裂 FX       | 读 `skills/playable-fx-decompose/SKILL.md`                             |
+| 优化帧光效 / burst       | 读 `skills/playable-fx-peak/SKILL.md`                                  |
+| 优化动效手感             | 读 `skills/playable-animate/SKILL.md`                                  |
+| 局部 L→G 穷举            | `npm run sweep:L1` / `npm run sweep:G1`                                |
+
+---
+
+## Vite 项目注意事项
+
+PlayCraft 项目用 Vite，`record:mp4` 默认脚本已经带了 `--use-dev --url=http://localhost:3000/`。只在当前 Ring 已披露 `record:mp4` 时运行：
+
+```bash
+npm run record:mp4 -- --headed --fps=60
+```
+
+这会：
+
+1. 在当前目录启动 `npm run dev`。
+2. 等待 `http://localhost:3000/` 可访问。
+3. 用 Playwright 打开该 URL 并录制。
+
+如果 Vite 端口不是 3000，改 `package.json` 里的 `record:mp4` 脚本，或手动：
+
+```bash
+# 终端 1
+npm run dev
+
+# 终端 2 / Agent
+npm run record:mp4 -- --url=http://localhost:5173/ --headed --fps=60
+```
+
+---
+
+## 录制前提：游戏需暴露 harness 契约
+
+Recorder / `verify:contract` 以 **`window.__playable`** 为 pass 标准（见 `game/contract/` + `publishPlayableRuntime()`）：
+
+```js
+window.__playable.autoPlay(); // 一键推进到 ENDCARD
+window.__playable.getState(); // { currentPhase, isGameOver }
+window.__playable.getCanvas?.(); // 可选，供录屏取 canvas
+window.__playable.hideDebugUi?.(); // 可选，录屏前隐藏 debug UI
+```
+
+`window.__game` 可保留为引擎句柄（如 Phaser.Game），但**不得**在其上挂载 `start` / `autoPlay` 等 harness 方法。
+
+**Legacy 路径（仅 warn，2026-Q3 移除）**：旧项目若仍只暴露 `MainScene._onDebugAutoPlay()` + `sceneManager`，verify 仍可通过但会提示迁移到 `window.__playable`。
+
+---
+
+## 标准工作流（按 gate 披露执行）
+
+```
+npm run state:get -- --json
+npm run ensure:project
+# Run only commands disclosed by state:get.nextCommands.
+# Then review MP4 evidence, make the smallest fix, and rerun disclosed gates.
+```
+
+---
+
+## 输出规范
+
+- MP4 证据：`recordings/playable-YYYYMMDD-HHmmss.mp4`
+- 报告：`validate/PLAYABLE-YYYYMMDD-HHmmss.md`
+- Focus 录屏：`recordings/focus/...`
+- 给用户/ orchestrator：结论 + 证据路径 + 1–3 条 vs 基线
+
+---
+
+## 依赖
+
+- Node.js 18+
+- Python 3 + `pip install pyyaml jsonschema pillow`
+- ffmpeg（`brew install ffmpeg`）
+- Playwright Chromium（由 `ensure-project` 自动安装）
+
+---
+
+## 相关文件
+
+- `skills/playable-validate/SKILL.md` — 整片优化主入口
+- `skills/playable-verify-ui/SKILL.md` — Image Validator
+- `skills/playable-record/SKILL.md` — 录屏
+- `skills/playable-debug/SKILL.md` — 一键通关
+- `skills/playable-fx-peak/SKILL.md` — 帧光效
+- `skills/playable-fx-decompose/SKILL.md` — 碎裂
+- `skills/playable-animate/SKILL.md` — 动效手感
+- `skills/playable-focus/SKILL.md` — L→G playground

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

@@ -29,21 +29,21 @@ playcraft tools search-image --query "<关键词（建议英文）>" [--source u
 
 **先本地，再网络**。网络研究是本地 Skill 发现的补充，不是替代。
 
-| 场景 | 应做什么 |
-|---|---|
-| `playcraft skills match` 完整匹配 | 直接用，无需研究 |
-| 部分匹配，缺少细节 | 用本地 Skill，补充网络研究缺失部分 |
-| 完全无匹配 | **触发 `research` 文本研究** |
-| 遇到陌生专业名词 | **触发 `research` 文本研究** |
-| 需要最新数据（2024+ 最佳实践） | **触发 `research` 文本研究** |
-| 需要视觉参考图（Phase 1 概念图 / 风格探索） | **触发 `search-image` 图片搜索** |
-| 生成后不满意，想用参考图引导风格 | **触发 `search-image` → 结果 URL 直接传 `--reference-image`** |
+| 场景                                        | 应做什么                                                      |
+| ------------------------------------------- | ------------------------------------------------------------- |
+| `playcraft skills match` 完整匹配           | 直接用，无需研究                                              |
+| 部分匹配，缺少细节                          | 用本地 Skill，补充网络研究缺失部分                            |
+| 完全无匹配                                  | **触发 `research` 文本研究**                                  |
+| 遇到陌生专业名词                            | **触发 `research` 文本研究**                                  |
+| 需要最新数据（2024+ 最佳实践）              | **触发 `research` 文本研究**                                  |
+| 需要视觉参考图（Phase 1 概念图 / 风格探索） | **触发 `search-image` 图片搜索**                              |
+| 生成后不满意，想用参考图引导风格            | **触发 `search-image` → 结果 URL 直接传 `--reference-image`** |
 
 ---
 
 ## 各角色研究标准流程
 
-### PM — 玩法机制调研
+### Game Designer — 玩法机制调研
 
 ```bash
 # 理解陌生的玩法类型
@@ -62,7 +62,7 @@ playcraft tools fetch-url \
   --query "what are the key level design parameters"
 ```
 
-### Designer — 视觉/音频风格调研
+### Artist — 视觉/音频风格调研
 
 ```bash
 # 搜索艺术风格生成参数
@@ -144,14 +144,15 @@ playcraft tools research \
 
 ## 研究结果融入活 DAG
 
-研究结果**必须写入 `atom-plan.md`**，否则其他 Agent 无法从中受益。
+研究结果**必须写入 `atom-tree.md`**，否则其他 Agent 无法从中受益。
 
 ### 写入格式
 
 ```markdown
-<!-- 在对应 atom 的 Asset/Impl Skill Context 下 -->
+<!-- 写入 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`
@@ -166,10 +167,11 @@ playcraft tools research \
 - **候选新 Skill**：`{{建议名称}}.{{bundleType}}` — {{为什么值得沉淀}}
 ```
 
-### 示例：Designer 研究波普艺术 + 搜图参考
+### 示例：Artist 研究波普艺术 + 搜图参考
 
 ```markdown
 ### bg_atom — 背景图层
+
 - 本地 Skill：无匹配
 - 文本研究结论：
   - 命令：`playcraft tools research --query "pop art game sprite color palette" --focus visual --json`
@@ -191,10 +193,11 @@ playcraft tools research \
 
 ## "候选新 Skill" 贡献循环
 
-每次网络研究形成可复用方案，在 `atom-plan.md` 的 **DAG Revisions** 标注：
+每次网络研究形成可复用方案，在 `atom-tree.md` 的 **Revision Notes** 标注：
 
 ```markdown
 ### Revision N — {{Agent}} (propose-skill)
+
 - **atomId**: {{atom_id}}
 - **reason**: 本地无 Skill，通过网络研究形成可复用方案
 - **change**: 建议创建：`{{skill_name}}.{{bundleType}}` — {{描述}}，来源：{{URL}}
@@ -204,9 +207,9 @@ playcraft tools research \
 
 ## 研究质量检查
 
-| 检查项 | 要求 |
-|---|---|
-| **来源可信度** | 优先官方文档、行业权威；引用来源来自 `--json` 输出的 `citations` 字段 |
-| **信息时效** | 优先 2024-2026 年内容（在 query 中加年份可提高准确性） |
-| **可操作性** | 结论必须直接用于生成参数或代码，不能泛泛而谈 |
-| **与 StyleDirection 一致** | 视觉研究须与 design-brief 的 StyleDirection 对齐 |
+| 检查项                     | 要求                                                                  |
+| -------------------------- | --------------------------------------------------------------------- |
+| **来源可信度**             | 优先官方文档、行业权威；引用来源来自 `--json` 输出的 `citations` 字段 |
+| **信息时效**               | 优先 2024-2026 年内容（在 query 中加年份可提高准确性）                |
+| **可操作性**               | 结论必须直接用于生成参数或代码，不能泛泛而谈                          |
+| **与 StyleDirection 一致** | 视觉研究须与 design-brief 的 StyleDirection 对齐                      |

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

@@ -0,0 +1,331 @@
+---
+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`            | 文件清单 + 用途描述（含图集格式）  |
+| 将 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> → 确认适合
+④ 将选中的 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]
+```
+
+---
+
+### 7. `link` — 创建符号链接（IDE 感知）
+
+```bash
+playcraft skills link --atoms <atomId1,atomId2,...> [--prune]
+playcraft skills link --from-atom-tree --prune
+```
+
+---
+
+## 推荐算法说明
+
+### 代码 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） → ④ scaffold → ⑤ 编码
+```
+
+### 流程 B：启发探索（不确定做什么）
+
+```
+① gettags --category gameplay → 了解有哪些玩法类型
+② filter --category gameplay --tags <感兴趣的> --json → 看相关 skill 列表
+③ read <某个 aigameplay skill> → 深入了解规则和变体
+④ 决定方向后 → match --intent <确定的关键词> → 获取完整推荐
+```
+
+### 流程 C：中途查找（开发中需要某个能力）
+
+```
+① filter --tags <能力关键词> --json → 找到候选
+② inspect <atomId> → 快速确认文件资产
+③ read <atomId> → 确认 API 和用法
+④ scaffold/link → 落地
+```
+
+---
+
+## 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`（会误解图集格式和裁切方式）