paean-ai/8x-skills

8x Skills

用于在 Paean Apps Square（.clide.app / 8x.gg）上构建、发布和混搭游戏的可移植智能体技能——可从 Zero CLI、Claude Code 和 Codex（或任何能读取 SKILL.md 并运行 Node 脚本的智能体）使用。

| 技能 | 功能 |
|-------|--------------|
| paean-skills-update | 拉取或同步此 8x-skills 仓库，并为 Zero CLI、Claude Code 或 Codex 项目重新安装/刷新 Paean 技能文件。 |
| paean-zero-setup | 安装 Zero CLI 并登录 Paean，以便发布/混搭脚本可以从 Zero 或 Paean 令牌文件读取本地凭据。 |
| paean-game-create | 创建或大幅升级一款具有商业品质、移动优先的 Paean 网页游戏。定义美术、玩法、吸引模式预览、响应式 UI、纯 JS 架构、紧凑资源和 Playwright 发布验证的制作标准。 |
| paean-sdk | 设计并集成云存档、排行榜、付费访问/IAP、激励广告/IAA、多人房间、AI、共享数据和分享。一个入口可路由到聚焦的能力设计指南；包含集成模块和离线模拟主机。 |
| paean-publish | 将静态前端（顶层 index.html）部署到 .clide.app，可作为仅托管（--hosting-only，无 Apps Square 条目）或作为公开 Square 上架项。支持自定义句柄、扫描机密信息，并阻止对检测到的 Worker/D1/R2 项目进行意外的纯静态上传。 |
| paean-remix | 将一款或多款已发布游戏混搭成新游戏。将主要来源（完整资源）克隆到用户工作区，通过 8x.gg MCP 服务器读取次要来源，并搭建一个具有多父级混搭图谱的项目（例如 h1 玩法 + h2 美术 + h3 主题），以便每个上游创作者都恰好被致谢一次。 |

对于能力设计，请说 paean iap、paean iaa、paean net、paean rank 或 paean ai，
或将它们组合起来（例如，“use paean rank with an optional paean iaa revive”）。这些是由
paean-sdk 路由的自然语言意图，而不是 CLI 命令
或单独安装的技能。Create 和 Remix 会在其制作简报期间选择相同的指南。共享 SDK 契约保留在一处；
详细设计和验收位于 paean-sdk/reference/design-.md，并且仅在相关时加载。

发布/混搭技能以自包含 Node 脚本形式提供——无需 npm install，除 Node 运行时和系统
zip/unzip 外没有外部依赖。paean-game-create 技能提供游戏制作标准以及静态/Playwright 验证器。
paean-sdk 技能提供浏览器参考文件（无服务器、无构建），你可以将其复制到你的应用中。

每件原创作品和混搭作品都应同时适配竖屏和横屏，而不是要求玩家旋转设备。针对可用屏幕重新组合
游戏区域和 UI，在方向变化时保留状态，并在发布前验证两种方向下的实际游玩体验。
保持 UI 简洁紧凑，让游戏区域保持清晰，文字可读，并在小屏幕上提供舒适的触控
目标，布局能跨分辨率自适应。默认使用明亮、平易近人的
休闲色彩和触感表面，除非主题或明确的艺术方向要求其他风格。

8x-skills/
├── zero/
│   ├── paean-skills-update/ SKILL.md
│   ├── paean-zero-setup/ SKILL.md
│   ├── paean-game-create/ SKILL.md + references/production-standard.md + scripts/validate-game.mjs
│   ├── paean-sdk/       SKILL.md + reference/{paean-platform,mock-bridge}.js + test-example.mjs
│   ├── paean-publish/   SKILL.md + scripts/publish.mjs
│   └── paean-remix/     SKILL.md + scripts/remix.mjs
├── claude-code/
│   ├── paean-skills-update/ SKILL.md
│   ├── paean-zero-setup/ SKILL.md
│   ├── paean-game-create/ SKILL.md + references/production-standard.md + scripts/validate-game.mjs
│   ├── paean-sdk/       SKILL.md + reference/{paean-platform,mock-bridge}.js + test-example.mjs
│   ├── paean-publish/   SKILL.md + scripts/publish.mjs
│   └── paean-remix/     SKILL.md + scripts/remix.mjs
└── codex/
├── paean-skills-update/ SKILL.md
├── paean-zero-setup/ SKILL.md
├── paean-game-create/ SKILL.md + references/production-standard.md + scripts/validate-game.mjs
├── paean-sdk/       SKILL.md + reference/{paean-platform,mock-bridge}.js + test-example.mjs
├── paean-publish/   SKILL.md + scripts/publish.mjs
└── paean-remix/     SKILL.md + scripts/remix.mjs

三个变体都附带相同的脚本和参考文件；只有 SKILL.md
的打包方式不同。zero/ 和 claude-code/ 变体使用 YAML frontmatter
（name: + description:）实现自动加载——Zero CLI 从
.zero/skills/ / ~/.zero/skills/ 发现技能，Claude Code 从 .claude/skills/ /
~/.claude/skills/ 发现技能。Codex 没有技能加载器，而是显式引用这些文件。

claude-code/ 是规范版本：在那里编辑，然后运行 node scripts/sync-variants.mjs 重新生成
codex/ 和 zero/（当它们出现偏差时 --check 会失败）。测试：node --test tests/.test.mjs。

Square 应用在顶层附带三个资源：favicon.svg、一张 800×400 的 banner.jpg 和一张
512×512 的 icon.jpg。付费应用（Steam 风格：免费观看演示，一次性购买后畅玩）通过
paean-publish --price  声明，并在应用内用 PaeanSDK.access.require() 进行门控；
参见 paean-sdk 及其离线模拟宿主 reference/paean-mock.js。

要求

- Node.js 18+（用于全局 fetch）。
- 发布需要 PATH 中有 zip；混搭需要 PATH 中有 unzip（macOS 和大多数
Linux 发行版都自带这两者）。
- 一个 Paean JWT（Paean Web 应用 / Zero CLI 使用的令牌）。

凭据

安装 Zero CLI 并登录 Paean（推荐）：

npm install -g @paean-ai/zero-cli
zero provider clear
zero login
zero auth status --json

发布/混搭脚本会读取 Zero 保存在 ~/.zero/credentials.json 中的 Paean 凭据。
如果无法通过浏览器登录，请通过环境变量或凭据文件设置你的 Paean JWT：

export PAEAN_AUTH_TOKEN=""
或：~/.paean/credentials.json  →  {"token":""}

如果存在 ~/.zero/credentials.json，这些脚本也会读取它。*切勿将令牌粘贴到
聊天中——请将其保存在环境变量或凭据文件中。可选：PAEAN_API_BASE
会覆盖 API 端点（默认为 https://api.paean.ai）。ZERO_API_BASE /
ZERO_CLI_BASE_URL 仅当它们指向 .paean.ai 主机时才会被采用——特别是
ZERO_CLI_BASE_URL 通常被设置为 LLM 网关（一个兼容 Anthropic 的提供商 URL），
它不是 Paean API 地址，会被忽略。

安装

Zero CLI

Zero 从 skills/ 目录中发现技能——项目级 .zero/skills/ 或全局级
~/.zero/skills/。将每个 Zero 技能目录复制进去：

mkdir -p ~/.zero/skills
cp -r 8x-skills/zero/paean-publish ~/.zero/skills/
cp -r 8x-skills/zero/paean-remix   ~/.zero/skills/
cp -r 8x-skills/zero/paean-zero-setup ~/.zero/skills/
cp -r 8x-skills/zero/paean-game-create ~/.zero/skills/
cp -r 8x-skills/zero/paean-sdk ~/.zero/skills/
cp -r 8x-skills/zero/paean-skills-update ~/.zero/skills/

当请求与其 description 匹配时，Zero 会自动提供该技能；你也可以
显式调用它（“使用 paean-publish 技能”）。

Claude Code

将技能目录复制到你的技能文件夹中（项目级 .claude/skills/ 或全局级
~/.claude/skills/）：

cp -r 8x-skills/claude-code/paean-publish ~/.claude/skills/
cp -r 8x-skills/claude-code/paean-remix   ~/.claude/skills/
cp -r 8x-skills/claude-code/paean-zero-setup ~/.claude/skills/
cp -r 8x-skills/claude-code/paean-game-create ~/.claude/skills/
cp -r 8x-skills/claude-code/paean-sdk ~/.claude/skills/
cp -r 8x-skills/claude-code/paean-skills-update ~/.claude/skills/

Claude Code 会自动发现 SKILL.md，并在相关时提供该技能。你也可以
显式调用它（“使用 paean-publish 技能”）。

Codex

Codex 没有 frontmatter 技能加载器，因此需要显式引用该技能。你可以将此
仓库保留在你的项目中，并在 AGENTS.md 中添加一个指针：

Skills
- To update Paean skills, follow 8x-skills/codex/paean-skills-update/SKILL.md.
- To install Zero CLI or log in to Paean for publishing, follow 8x-skills/codex/paean-zero-setup/SKILL.md.
- To create or substantially polish a Paean game, follow 8x-skills/codex/paean-game-create/SKILL.md.
- To add cloud save or a global leaderboard, follow 8x-skills/codex/paean-sdk/SKILL.md.
- To host on Clide or publish to Paean Apps Square, follow 8x-skills/codex/paean-publish/SKILL.md.
- To remix Paean Apps Square games, follow 8x-skills/codex/paean-remix/SKILL.md.

……或者在你的提示词中直接让 Codex 指向该文件。

用法

在你要发布的项目中：

预览，然后以一个好名称发布到 Apps Square
node /scripts/publish.mjs --dry-run
node /scripts/publish.mjs --yes --title "Neon Drift Racer" --category racing

预览，然后部署到 Clide 托管，无需 Apps Square 上架
node /scripts/publish.mjs --dry-run --hosting-only --dir dist --handle neon-drift
node /scripts/publish.mjs --yes --hosting-only --dir dist --handle neon-drift

在发布新创建或混编的游戏之前，请验证其自包含项目和浏览器
运行时（工作环境中必须安装 Playwright）：

node /scripts/validate-game.mjs  \
--screenshots

要将现有游戏混编为新游戏：

h1 是主源：在服务端克隆（完整资源）到用户的工作区。
h2/h3 通过 8x.gg MCP 服务器读取（文本源，不进入工作区）。
然后构建新游戏并发布它——每个父源都恰好被署名一次。
node /scripts/remix.mjs --yes h1=gameplay h2=art h3=theme --dir my-remix

8x.gg MCP 服务器

https://api.paean.ai/8x/mcp 是混编的发现/研究部分：find_app /
search_apps 可将任何 8x.gg 或 clide.app URL、标题或描述解析为一个应用；
get_app / get_remix_lineage / get_app_growth 说明它是否值得混编；
list_app_files / read_app_file 让智能体无需克隆任何内容即可读取源代码。
这些脚本是交付部分（完整资源、本地脚手架、发布）。paean-zero-setup
按主机注册服务器（zero mcp add / claude mcp add / codex mcp add），使用
相同的 Paean 令牌；在 Paean Mac 应用内，它会自动注册为 8xgg。

使用 --help 运行任何脚本以查看完整用法。请参阅每个技能的 SKILL.md，了解智能体应遵循的完整
工作流。

混编图（clide.json）

paean-remix 会写入一个 clide.json 清单，以两种兼容形式同时记录
谱系：

{
"schemaVersion": 1,
"title": "Neon Drift Racer",
"category": "racing",
"tags": ["neon", "racing"],
"license": "MIT",
"remix": {
"parent": "h1",                                  // 树形式：主上游
"parents": [                                     // 图形式：混编 DAG
{ "hashKey": "h1", "role": "gameplay", "weight": 1 },
{ "hashKey": "h2", "role": "art",      "weight": 1 },
{ "hashKey": "h3", "role": "theme",    "weight": 1 }
]
}
}

remix.parent 使仅支持树形式的消费者（以及后端的 remixOfHashKey 主父源
字段）继续正常工作，而 remix.parents[] 是多父源混编 DAG 的邻接表——
每个直接上游及其贡献的方面，以及建议的收入 weight。
paean-publish 会将直接父源 hashKey 作为 remixOfHashKeys 转发，因此 zero-api 会为
完整图记录 SquareRemixEdge 行。

安全

- 两种模式都会创建一个可公开访问的站点。脚本要求显式确认
（或 --yes）；仅托管模式绝不会创建工作区或 Apps Square 列表。
- Wrangler/Worker/D1/R2 项目会被报告为运行时不兼容，并在上传前被阻止，除非用户通过
--allow-static-only 明确接受仅前端部署。
- 已发布的游戏应在 index.html 中包含标准的 paean.ai 版权注释，并
附带项目 LICENSE；混搭作品还应将直接父项目记录在 clide.json 中。
- 游戏应附带顶层 favicon.svg 和 800x400 的 banner.jpg。发布脚本
会在任一文件缺失或横幅尺寸错误时发出警告，但不会阻止发布。
- 凭据仅从环境 / 凭据文件读取——绝不硬编码，
也绝不写入已发布的输出中。
- 高置信度密钥扫描器会阻止发布看起来像私钥或 API
令牌的文件。
- 原始下载的上游源文件（.remix-sources/）和 clide.json 清单
默认会从已发布站点中排除。
- paean-publish --delete 会感知模式：Square 项目会先取消列出，再移除其 Clide 文件，
而仅托管项目只删除其站点。它可以从已保存/显式指定的 handle 解析缺失的 Square 哈希，
并在无法安全建立 Square 身份时拒绝清理。

许可证

MIT——见 LICENSE。