PlayCraft Skills 总览

本目录统一管理 PlayCraft 的两类 skill：

| 目录 | 类型 | 说明 | |-----|-----|-----| | skills/ | Atom Skills | Remix 组装单元（代码/资源/配置）。每个 skill 有 manifest.json + SKILL.md + ref/，命名规范 <name>.<bundleType>，如 phaser.aicomponent、win_result_panel.aiimage | | platform-skills/ | Platform Skills | AI Agent 使用 PlayCraft 平台的操作指南（生图、生音频、发布等）。symlink → packages/backend/src/features/agent/skills/，修改统一在 backend 进行 |

图谱关系（节点边、权重、组装引擎）后续在 docs/recommend/ 中单独定义。

命名规范（必须遵守）

Atom Skills — <name>.<bundleType>

特征：

• 目录名格式：<snake_case_name>.<bundleType>（如 grid_board_layout.aicomponent、bg_music.aiaudio）
• 必须有 manifest.json（声明 atomId、category、tags、bindingRoles、scaffold 等）
• 必须有 SKILL.md（使用说明）
• 通常有 ref/ 目录（蒸馏自真实项目的参考代码/资源文件）
• 代表"是什么"：一个可组装进 Remix 的具体素材或代码单元

grid_board_layout.aicomponent/   ← Atom Skill
  ├── manifest.json
  ├── SKILL.md
  └── ref/
      ├── BoardLayout.ts
      └── BoardLayout3D.ts

Platform Tools — playcraft-<name>

特征：

• 目录名格式：playcraft-<kebab-case-name>（如 playcraft-image-generation、playcraft-skill-recommender）
• 只有 SKILL.md，没有 manifest.json（不参与 Atom Graph，不被 recommend API 索引）
• 代表"怎么做"：描述 Agent 如何使用 PlayCraft CLI / API 完成某项操作
• 被 Agent Skills Loader 发现，在 Agent Session 初始化时加载

playcraft-image-generation/      ← Platform Tool
  └── SKILL.md                   ← 仅此一个文件

判断规则

| 问题 | 是 → | 否 → | |------|------|------| | 它是一个可以被 scaffold 进项目的代码/资源单元吗？ | Atom Skill（<name>.<bundleType>） | → 下一条 | | 它描述的是 Agent 如何使用平台工具/CLI 的操作流程吗？ | Platform Tool（playcraft-<name>） | 不属于 skills 目录 |

常见错误：

• ❌ 把平台操作指南做成 manifest.json + SKILL.md（混淆 Atom 和 Platform Tool）
• ❌ 用 <name>.aicomponent 命名平台工具（如 skill_recommender.aicomponent）
• ❌ 给 Platform Tool 创建 manifest.json（会被错误地当作 Atom 索引）

Platform Skills 列表

| Skill | 说明 | |-------|-----| | playcraft-image-generation | AI 生图（Google Gemini / IEGG LiteLLM），直接写入文件 | | playcraft-audio-generation | AI 生音频（BGM + SFX），体积预算管理 | | playcraft-image-processing | 图片后处理（缩放/裁剪/格式转换/合成）| | playcraft-sprite-sheet | 多图合并精灵图，输出 PNG + JSON 帧坐标 | | playcraft-sprite-remix | 精灵图拆解 + 逐帧 AI 重绘 + 重组装 | | sound-effects | 通过 playcraft CLI 生成音效（SFX）| | playcraft-asset-management | 查看/替换项目素材 | | playcraft-code-editor | 读取/修改项目脚本和配置 | | playcraft-remix-workflow | Remix 工程流程（主题/metadata/schema）| | playcraft-create-remix | 创建新 Remix 变体 | | playcraft-build | 在 sandbox 执行 npm run build | | playcraft-save | 将 sandbox 代码 sync → commit → push | | playcraft-deploy | 组合操作：build → save → publish | | playcraft-project-management | 查看变体、浏览推荐 Remix | | playcraft-platform-intro | PlayCraft 平台介绍 | | playcraft-prefab | playcraft prefab CLI 用法 | | playcraft-skill-recommender | 构建项目前的 Skill 推荐与脚手架（playcraft skills match/list/scaffold） |

bundleType 说明

| bundleType | 含义 | category 可选值 | |-----------|-----|--------------| | aicomponent | 通用代码 skill（引擎/布局/场景/UI/状态/构建/工具） | engine / layout / scene / state / component / build / util | | aigameplay | 玩法逻辑（PGS schema + 相关代码模块） | gameplay | | aivalidator | 校验/测试/质量门禁（测试脚本 + 校验报告） | validator | | aiimage | 图片资源 | visual | | aiaudio | 音频资源 | audio | | aiconfig | 配置封包 | config |

Skills 分层清单

1. 引擎层（category: engine）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | phaser.aicomponent | Phaser 3 引擎 + 完整空项目骨架（7 个文件：HTML/CSS/TS 入口/tsconfig/globals/StartGame/GameConfig），安装后即可 pnpm dev 运行 | gameEngine |

2. 构建层（category: build）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | playable_scripts_build.aicomponent | 试玩广告多渠道构建管线（@tencent/playable-scripts） | buildPipeline | | theme_switcher_build.aicomponent | 主题入口 src/theme/index.ts，构建时切换主题 | — |

3. 布局层（category: layout）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | responsive_2d_layout.aicomponent | 框架无关布局规范（uiScale/vScale/不变量）+ 默认 Phaser 参考实现 ref/UiLayout.ts | responsiveLayout | | playable_hud_layout.aicomponent | HUD 屏幕分区（顶/底/棋盘可用高度、z-order 合同），无代码 scaffold | playableHudLayout | | playable_end_screen_layout.aicomponent | 结算全屏布局（遮罩、安全区、CTA 锚点），无代码 scaffold | playableEndScreenLayout | | playable_guidance_layer.aicomponent | 指引层布局（挖洞、手指、与 HUD/结算 depth），无代码 scaffold | playableGuidanceLayout | | grid_board_layout.aicomponent | 可变尺寸格子棋盘布局（格子大小/偏移/缩放边界） | gridBoardLayout |

4. 场景层（category: scene）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | phaser_scene_lifecycle.aicomponent | Phaser 双场景架构骨架（Preloader → Game） | sceneLifecycle | | preloader_scene.aicomponent | 预加载场景（加载资产 + Loading UI + sdk.start） | preloaderScene | | game_scene.aicomponent | 主游戏场景（协调所有子系统） | gameMainScene |

5. 状态层（category: state）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | settings_state.aicomponent | 用户设置（音乐/音效开关/拖拽速度） | userSettings | | theme_state.aicomponent | 主题配置（路径颜色/箭头风格/UI 颜色） | themeManager | | level_state.aicomponent | 关卡进度（当前索引/关卡数据加载） | levelProgress | | run_context_state.aicomponent | 运行上下文（normal/test 模式区分） | runContext |

6. 玩法层（bundleType: aigameplay / category: gameplay + component）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | path_elimination_rules.aigameplay | 路径消除玩法 PGS（核心规则 + testCases）；Remix 的 entry 节点 | gameplayRule | | pick_and_match_rules.aigameplay | 拾取三消玩法 PGS（棋盘拾取→篮子→三同消除）；支持多层堆叠、同类聚合、篮子溢出 | gameplayRule | | arrow_path_data_format.aicomponent | RawLevelJson ↔ ParsedLevel 类型定义和解析器 | levelDataFormat | | path_renderer.aicomponent | 棋盘路径批量渲染器（折线 + 箭头头部） | pathBatchRenderer | | path_animation.aicomponent | 路径动画（消除滑出/阻挡震动/胜利钻石） | pathAnimationDirector | | path_input_handler.aicomponent | 棋盘输入（命中检测/拖拽棋盘/双指缩放） | boardInputHandler | | level_lifecycle.aicomponent | 关卡生命周期（扣命/超时/胜利/进关） | levelLifecycleController |

旧的 arrow_escape_core.aigameplay（描述"放箭头引导角色"玩法）已被 path_elimination_rules.aigameplay（路径消除）替代并删除。

7. UI 组件层（category: component）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | loading_screen.aicomponent | Loading 页面 UI（logo/标题/星评/进度 dots） | loadingScreen | | top_ui_bar.aicomponent | 顶部 UI 条容器 + GAME_TOP_UI_BAR_HEIGHT 常量 | topUiBar | | bottom_ui_bar.aicomponent | 底部 UI 条占位 + GAME_BOTTOM_UI_BAR_HEIGHT（与 GameConfig 同源） | bottomUiBar | | countdown_timer.aicomponent | 倒计时显示器（七段数码管风格） | countdownTimer | | heart_lives.aicomponent | 心形生命值指示器 | livesIndicator | | combo_display.aicomponent | 连击计数 UI + 倒计时进度环 | comboDisplay | | combo_praise_text.aicomponent | 连击表扬文案弹出动画（GOOD → LEGENDARY） | comboPraiseText | | progress_bar.aicomponent | 关卡进度条（已消除/总路径） | progressBar | | download_button.aicomponent | 下载 CTA 按钮（呼吸动画 + sdk.install） | downloadCta | | game_over_panel.aicomponent | 胜利/失败结果面板（半透明遮罩 + 结果图 + CTA） | gameOverDialog | | tutorial_overlay.aicomponent | 新手引导浮层（前两关步进式操作指导） | tutorialOverlay | | digit_renderer.aicomponent | 七段数码管数字渲染器（基础组件） | digitGlyphRenderer |

8. 工具层（category: util）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | sound_utils.aicomponent | safePlaySound() 音频安全播放工具函数 | audioPlayHelper |

8.5 校验层（bundleType: aivalidator，category: validator）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | gameplay_unit_test.aivalidator | 玩法逻辑单元测试（Vitest） | testFramework | | level_solvability_validator.aivalidator | 关卡可解性验证器 | levelValidator | | level_data_validator.aivalidator | 关卡数据格式校验器 | dataValidator |

aivalidator 与 aicomponent 的区别：aivalidator 的核心目的是检查/验证已有代码或数据的质量，不产出可部署的功能代码。

9. 图片资源层（bundleType: aiimage，category: visual）

| atomId | 对应文件 | bindingRoles | |--------|---------|-------------| | direction_arrow_sprite.aiimage（已有） | arrows.png | directionalIndicator | | playable_app_logo.aiimage | logo.webp | appLogo | | win_result_panel.aiimage | win.webp | successFeedbackPanel | | lose_result_panel.aiimage | lose.webp | failFeedbackPanel | | nomove_hint_overlay.aiimage | nomove_hint.webp | dangerFlashOverlay | | figer_icon.aiimage | figer.webp | tutorialPointer | | time_icon.aiimage | time.webp | clockIcon | | win_dot.aiimage | win_dot.webp | winParticleAsset | | normal_dot.aiimage | normal_dot.webp | normalParticleAsset |

directionalIndicator 同类替代簇：direction_arrow_sprite.aiimage（箭头）可替换为车、手指、赛博风等变体。

10. 音频资源层（bundleType: aiaudio，category: audio）

| atomId | 对应文件 | bindingRoles | |--------|---------|-------------| | cheerful_ukulele.aiaudio（已有） | — | bgMusic | | calm_piano.aiaudio（已有） | — | bgMusic | | energetic_electronic.aiaudio（已有） | — | bgMusic | | bg_music.aiaudio | bg.mp3 | bgMusic | | click_sfx.aiaudio | click.mp3 | sfxClick | | appear_sfx.aiaudio | appear.mp3 | sfxAppear | | success_sfx.aiaudio | success.mp3 | sfxSuccess | | fail_sfx.aiaudio | fail.mp3 | sfxFail | | lose_sfx.aiaudio | lose.mp3 | sfxLose | | mistake_sfx.aiaudio | mistake.mp3 | sfxMistake | | win_anim_sfx.aiaudio | win_anim.mp3 | sfxWinAnim | | arrow_move_error_sfx.aiaudio | arrow_move_error.mp3 | sfxArrowMoveError | | button_click_sfx.aiaudio | button_click.mp3 | sfxButtonClick |

bgMusic 同类替代簇：bg_music / cheerful_ukulele / calm_piano / energetic_electronic

11. 配置层（bundleType: aiconfig，category: config）

| atomId | 描述 | bindingRoles | |--------|-----|-------------| | level_data_pack.aiconfig | RawLevelJson[] 关卡数据集 | levelDataPack | | theme_variant.aiconfig | 主题变体配置（ThemeVariantConfig 实例） | themeVariantConfig | | app_metadata.aiconfig | Loading 页面文案（标题/描述/评分） | appMetadata | | easy_to_hard.aiconfig（已有） | 先易后难难度曲线 | gameConfig | | wave_difficulty.aiconfig（已有） | 波浪难度曲线 | gameConfig | | score_goal.aiconfig（已有） | 分数目标配置 | gameConfig | | time_clear_goal.aiconfig（已有） | 限时通关目标配置 | gameConfig |

继承自 match3 的通用素材

| atomId | 说明 | |--------|-----| | match3_core.aigameplay | match3 玩法规则，暂未改动 | | forest/ocean/castle/desert.aiimage | 背景图，可作 boardBackgroundTexture 候选 | | fruit_tile/jewel_tile/candy_tile.aiimage | match3 / pick_and_match 可用的瓦片贴图集 |

bindingRoles 语义标签完整列表

语义标签用于：

1. 声明该 skill 的类别（写在 bindingRoles 字段）
2. 软槽位候选召回（其他 skill 的 imports[].matchBindingRoles 引用）

完整枚举见 packages/common/src/recommend/atom-graph/types.ts 中的 AtomBindingRole 类型。

文件结构

packages/skills/
├── skills/
│   ├── phaser.aicomponent/
│   │   ├── manifest.json     # 类型、标签、bindingRoles、scaffold、imports、exports
│   │   ├── SKILL.md          # 使用说明、Scaffold/Imports/Skill Definition
│   │   └── ref/              # 蒸馏自真实 remix 的源文件
│   ├── path_elimination_rules.aigameplay/
│   │   ├── manifest.json
│   │   ├── SKILL.md
│   │   └── ref/
│   │       └── pgs-schema.json   # 完整 PGS 规则描述
│   └── ...（共 ~68 个 skill）
└── test/
    └── atom-skills.test.ts   # 完整性校验

双 Skill 系统共存设计

PlayCraft 同时支持两套互补的 Skill 系统，两者职责不同、互不干扰。

.claude/skills/                        ← Claude Code 原生发现路径
  ├── playcraft-workflow/               ← 静态桥接 skill（随项目模板分发）
  │   └── SKILL.md                      工作流入口，引导 agent 使用 playcraft skills match
  ├── playcraft-skill-recommender → …   ← 软连接（playcraft create 自动创建）
  ├── playcraft-image-generation  → …   ← 软连接（指向 node_modules/@playcraft/skills）
  ├── playcraft-audio-generation  → …
  └── …（其余 Platform Tool 软连接）

node_modules/@playcraft/skills/skills/ ← DAG 推荐引擎的 Atom 索引源
  ├── phaser.aicomponent/
  ├── match3_core.aigameplay/
  ├── gameplay_balance_check.aivalidator/
  └── …（134+ Atom Skills）

分层策略

| 层 | 内容 | 发现方式 | 职责 | |---|---|---|---| | Claude Code Skills | 静态桥接 skill + Platform Tool 软连接 | IDE 自动扫描 .claude/skills/ | HOW：平台工具用法 | | DAG Atom Skills | 134+ .aiimage/.aiaudio/.aicomponent/.aigameplay/.aiconfig/.aivalidator | playcraft skills match CLI 推荐 | WHAT：游戏积木 |

为什么不把 Atom Skills 放进 .claude/skills/

1. 数量问题：134+ Atom Skills 会淹没 Claude Code 的 description 匹配机制
2. 格式差异：Atom Skills 的 SKILL.md 包含 DAG 元数据（triggers、prompt_extension、tools），Claude Code 不解析这些字段
3. 职责分离：Atom Skills 通过 playcraft skills match 按引擎+意图精准推荐，比 IDE 文本匹配更准确
4. 发现机制：DAG 推荐系统可做依赖图遍历、打分排序，远优于 IDE 的关键词匹配

桥接 skill（playcraft-workflow）的作用

packages/cli/project-template/.claude/skills/playcraft-workflow/SKILL.md 是静态提交到模板的唯一 Atom 入口：

• Claude Code 自动注入（description 含构建相关关键词）
• 告知 agent "开始任何游戏项目前先运行 playcraft skills match"
• 解释如何阅读 Atom Skill 的 SKILL.md（prompt_extension / tools 字段）

软连接生命周期

playcraft create my-game
  → 复制 project-template（含静态 playcraft-workflow）
  → 在 .claude/skills/ 创建 playcraft-* 软连接
    ├── 若 monorepo dev 路径可解析 → 绝对路径软连接（当下即用）
    └── 否则 → 相对路径软连接（指向 node_modules，npm install 后激活）

npm install
  → @playcraft/skills 安装到 node_modules
  → 相对路径软连接自动解析生效

软连接由 playcraft create 生成，在 .gitignore 中排除，不提交到项目 Git 仓库。