---
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
```