GemDesign Skill 用户指南
概述
gemdesign-skill 是一个面向各个通用 AI Agent 平台的 Skill（技能），让你通过给 Agent 下达简单指令，就能自动生成高保真可交互的完整 UI 原型Demo。比如直接给它一份PRD需求文档，让它自动设计所有原型页面、在浏览器中实时预览、在本地 GemDseign 设计器中手动编辑、并同步到 GemDesign 平台。
生成的原型不是静态图片，而是包含真实交互（弹窗、切换、页面导航）的高保真页面，可以直接用于需求评审和用户测试。
安装指南
一键自动安装（推荐）
如果你使用的 AI Agent 平台支持 SKILL ，只需在对话中发送以下指令，AI 会自动完成全部安装：
帮我安装gemdesign-skill：https://design.gemcoder.com/libs/gemdesign-skill-installation-guide.md
AI 会自动判断当前平台、选择正确的技能目录、安装 CLI 并验证。以下是各主流平台的具体差异：
| 平台 | 技能目录（全局） | 技能目录（项目级） |
|---|---|---|
| Qoder (QoderWork) | ~/.qoderworkcn/skills/ | — |
| Claude Code | ~/.claude/skills/ | .claude/skills/ |
| Codex | ~/.codex/skills/ | .codex/skills/ |
| Trae | — | .trae/skills/ |
| OpenClaw | ~/.claude/skills/ | .claude/skills/ |
| Hermes | ~/.hermes/skills/ 或 ~/.agents/skills/ | .agents/skills/ |
| Opencode | ~/.config/opencode/skills/ | .opencode/skills/ |
| WorkBuddy (CodeBuddy) | 通过 UI 上传 | — |
| Qclaw | 通过项目内 AGENTS.md 引用 | — |
各平台手动安装
第一步 下载技能包
如果选择手动安装（见下方各平台说明），请先下载 GemDesign Skill 压缩包。压缩包内包含完整的技能文件：SKILL.md（技能指令）和 resource/ 目录（本地预览服务器及静态资源），下载后即可按下方对应平台的步骤安装。
下载后根据具体平台要求导入zip文件，或解压得到
gemdesign-skill文件夹，其中包含SKILL.md和resource/目录。安装时按需将这两个文件/目录复制到对应平台的技能目录即可。
第二步 手动安装 ( 以 WorkBuddy 为例 )
- 打开 WorkBuddy 的新建任务/技能市场页面，点击 技能
- 选择 导入技能，将
gemdesign-skillZIP 文件上传（上传过程中平台安全检测需等待一段时间，可选择“跳过检测，直接安装”） - 系统自动完成配置，无需额外操作
也可以在技能市场中搜索是否有已发布的 GemDesign Skill ，直接安装。
GemDesign CLI 安装与验证（ 无需操作，Agent 自动执行 ）
无论使用哪个平台，都会自动安装 GemDesign CLI。
如果 AI 助手在执行技能时发现 CLI 未安装或版本过旧，会自动帮你安装或更新。
登录账号与获取 MCP 令牌
在 AI 对话中首次使用 GemDesign 技能时，AI 会检查登录状态。如果未登录，需要输入 GemDesign MCP 令牌：
- 访问 https://design.gemcoder.com 登录或注册账号
- 登录后进入 个人中心
- 获取 MCP 令牌（复制给 Agent ，用于登录）
登录成功后无需重复登录，后续使用直接开始生成页面。
GemDesign 设计器
GemDesign 设计器是技能内置的本地预览/手动编辑工具。当你让 AI 生成页面时，设计器会自动打开，实时展示页面构建过程，并提供丰富的预览和编辑功能。
生成效果如下
本地预览与流式显示
AI 生成页面时不是一次性结束，而是逐步写入——就像打字机一样，页面内容从上到下逐步出现在浏览器中。这让你能实时看到 AI 的生成进度，包括头部、导航、内容区、弹窗等组件的逐步构建过程。
设计器运行在本地端口 4056（如被占用则自动切换到 4057-4066），不需要互联网连接即可预览。
手动编辑
继承了 GemDesign 强大的手动编辑能力，提供类似 Figma 的无限画布等功能，具体文档可见无限画布 - 手动编辑
设计系统页面 （应用视觉风格）
当你创建新应用时，AI 会在生成业务页面前，先自动生成一个设计系统页面。这个页面定义了整个应用的视觉风格基线——色彩体系、圆角规范、阴影效果和组件样式。后续所有业务页面都会遵循这个风格，确保应用整体视觉一致性。
设计系统页根据应用类型自动选择风格：
- 移动端应用（app 类型）：展示 C 端常见的图文卡片、社交互动元素、底部导航等组件，页面包裹在手机框内模拟真实移动端界面
- Web 应用（web 类型）：展示后台系统常见的数据表格、表单元素、侧边导航等组件，全宽后台布局模拟真实管理系统界面
设计系统页保存在平台后，你也可以像修改普通页面一样对它进行调整。修改设计系统页后，后续生成的业务页面会遵循更新后的风格。
使用场景
场景一：根据需求批量生成页面
你有一份需求文档（PRD、功能清单），需要一次性生成多个页面。把需求发给 AI，它会自动拆解为各个页面、为每个页面分配唯一标识，然后逐页生成。
对话示例：
使用gemdesign-skill，按xxxPRD需求（拖到输入框中）设计出一个全新的原型demo
AI 会确认应用信息 → 生成设计系统页（如果是新应用）→ 逐页生成并保存。每个页面在浏览器中实时显示生成过程，完成后可以立即预览交互效果。
场景二：对话式逐页生成
没有完整需求文档，想通过对话逐步生成。每次描述一个页面，AI 帮你创建。后续可以继续描述新页面，AI 会在同一应用中继续生成。
对话示例：
使用gemdesign-skill，帮我设计一个后台管理系统的登录页面，需要账号密码输入框和登录按钮，
顶部有系统名称和 Logo。
AI 确认应用后生成页面。你可以继续说：
再帮我做一个数据看板页面，顶部有四个数据卡片显示总用户数、
今日新增、活跃用户、转化率，用图表展示。
场景三：修改已有页面
平台上已有页面，需要调整内容或样式。告诉 AI 要改什么，它会拉取现有页面、修改、重新验证并保存。
对话示例：
帮我修改商品列表页，把排序按钮改成下拉选框，并添加一个价格区间筛选的输入框。
AI 会拉取页面 → 修改 → 验证 → 保存更新。
场景四：老项目迁移与持续优化
GemDesign 平台上已有"页面原型"或"应用原型"中的老项目，受限于文件格式与结构，会 AI 影响持续高效迭代的准确性，也无法进行高效的手动修改。你可以让 Agent 将这些老项目 转写为无限画布版本的新格式页面。迁移完成后，老项目即可继承无限画布模式优势，继续进行修改、新增和迭代优化。
适用情况：
- 平台上有存量"页面原型"或"应用原型"老项目，希望迁移到 agent 可迭代的新格式
- 老项目页面结构与内容需要保留，但后续要交给 AI 持续优化和扩展
对话示例
应用原型 - 迁移：
我在 GemDesign 平台上有一个老的"应用原型"项目，appuuid 是 123xxx，
里面有xxx几个页面。使用gemdesign-skill，把这些页面在新应用中还原，
要求保留原有的页面风格、结构、交互、图片、图标等，将navigation整合到每个主菜单页面中。
页面原型 - 迁移：
我在 GemDesign 平台上有一个老的"页面原型"项目，appuuid 是 123xxx，
里面有xxx几个页面。使用gemdesign-skill，把这些页面在新应用中还原，
要求保留原有的页面名称、风格、结构、交互、图片、图标等。注意原页面间跳转交互，还原时要符合gemdesign-skill的交互规范。
迁移完成后，老项目就变成了 agent 可直接编辑的无限画布版本。你可以继续通过对话/编辑对任意页面进行后续迭代。
AI 会像处理新页面一样拉取、修改、验证、保存，实现存量项目的持续 AI 驱动迭代。
提示： 迁移前建议先确认 appuuid（可在平台的应用中查看）。如果不确定 appuuid，也可以告诉 AI 项目名称，让它通过
gemdesign app list查找。
常见问题
Q：我想让 AI 一次做完，但是 Agent 运行过程老是中断，让我确认权限怎么办？
可以在开始任务时，设置“完全访问权限”。
Q：AI 提示"CLI 未安装"或版本过旧
Agent 会自动帮你安装或更新。如果网络较慢，耐心等待 npm install -g @gemdesign-ai/cli 执行完成即可。也可以提前在终端手动运行此命令。
Q：Skill 使用的次数是怎么界定的？
AI Agent 操作生成/修改一次页面，记为“ Skill 使用 1 次 ”。
Q：登录失败，提示"token 无效"
检查从 https://design.gemcoder.com → 个人中心获取的 MCP 令牌是否完整复制。令牌可能较长，确保没有截断或多余空格。
Q：浏览器没有出现实时预览
Agent 会自动启动本地服务器并打开预览。如果没有出现，可以发出指令“使用内置浏览器打开GemDesign设计器”让 Agent 解决。如果是 4056-4066 端口被占用，尝试关闭可能占用这些端口的程序后重试，或者让 Agent 自行检测和调整。
Q：我想在已有应用中继续添加页面
直接在对话中描述新页面的需求即可。AI 会自动检查已有应用并复用，不会重复创建。
Q：设计系统页可以修改吗？
可以。设计系统页和普通页面一样可以修改。修改后，后续生成的业务页面会遵循更新后的风格。
Q：一个应用可以有多少个页面？
没有硬性限制。建议一个应用聚焦一个产品/系统，避免混杂不同产品的页面。
Q：技能在哪个平台支持最好？
所有平台（Claude Code、Codex、Trae、OpenClaw、Hermes、Opencode、WorkBuddy、Qclaw 等）都提供完整的技能管理和预览集成，功能体验一致。
Q：页面生成后保存在哪里？
页面通过 CLI 同步保存到 GemDesign 平台（https://design.gemcoder.com）。本地也会在 ./output/项目名__应用ID/ 目录下保存文件副本，方便离线查看和编辑。
Q：分享的链接需要对方也安装软件吗？
不需要。分享链接打开后是一个网页，对方只需浏览器和密码即可查看，无需安装任何软件。