gemdesign-skill

GemDesign Prototyping

Use the gemdesign CLI to create, save, and modify high-fidelity prototype pages on the GemDesign platform. You generate HTML following the GemDesign Page Spec, validate it, then save via CLI.

When to Invoke

• User wants to create a UI prototype or design a page
• User has a requirements document and wants batch page generation
• User wants to modify an existing GemDesign page
• User wants to view existing GemDesign pages

Prerequisites

CRITICAL: Step 1, Step 2, and Step 2.5 MUST be executed strictly in order BEFORE starting any Workflow. Each step MUST fully complete before proceeding to the next. Do NOT skip, parallelize, or advance until the current step is confirmed successful.

IMPORTANT — Step 3 timing: Step 3 (Start the Local Server) is NOT executed immediately after login. It MUST be executed INSIDE a Workflow, AFTER the app is created or reused (i.e., after gemdesign app create / gemdesign app use + gemdesign app info), and BEFORE any page generation. Starting the server before the app exists is a violation — the server serves pages from the project subdirectory derived from the app, so the app must exist first.

Step 1: Verify & Install GemDesign CLI (MUST complete before Step 2)

ALWAYS verify CLI installation and version first before doing any other work. This step is a hard gate — no other operations (auth, app, page, style, etc.) may run until this step is confirmed complete.

1. Check if CLI is installed:

   npm list -g @gemdesign-ai/cli
   

   • If the command returns version info (e.g., @gemdesign-ai/cli@1.2.3), CLI is installed - proceed to step 2.
   • If the command returns empty or error (e.g., (empty) or ERR!), CLI is NOT installed. Run:

     npm install -g @gemdesign-ai/cli
     

     Wait for the installation to finish, then re-verify with npm list -g @gemdesign-ai/cli. Do NOT proceed until re-verification confirms the installed version.

2. Check if CLI is latest version (only after step 1 confirms CLI is installed):

   npm outdated -g @gemdesign-ai/cli
   

   • If the command returns empty or shows Current=Latest, CLI is up-to-date - this step is complete, proceed to Step 2.
   • If the command shows version info with different Current and Latest values, CLI is outdated. Update to latest:

     npm update -g @gemdesign-ai/cli
     

     Wait for the update to finish, then re-verify with npm outdated -g @gemdesign-ai/cli. Do NOT proceed until re-verification confirms the CLI is up-to-date.

After this step is confirmed complete, the gemdesign-ai command is available globally at the latest version. Only then may you advance to Step 2.

Step 2: Verify Login (MUST complete after Step 1, before any Workflow)

ALWAYS verify login status after Step 1 is complete. Run this command:

gemdesign auth whoami

• If it succeeds (returns user info), the user is logged in — proceed to a Workflow (A/B/C). Step 3 (local server) will be executed INSIDE the workflow, after the app is created/reused.
• If it fails (returns an error like "GemDesign令牌 无效" or "未提供 GemDesign令牌"), the user is NOT authenticated. You MUST:
  1. Tell the user: if they don't have an account or GemDesign令牌 yet, go to https://design.gemcoder.com to register an account and get a GemDesign令牌. The GemDesign令牌 retrieval path is: log in to the platform -> click 个人中心 (Personal Center) -> get the GemDesign令牌 (GemDesign令牌).
  2. Ask the user for their GemDesign令牌 (use AskUserQuestion tool to prompt the user to input their GemDesign令牌).
  3. Once the user provides their GemDesign令牌, automatically run the login command for them:

     gemdesign auth login --token 
     

  4. Re-verify with gemdesign auth whoami to confirm login succeeded.
  5. If login still fails, repeat from step 2 (ask the user to provide their GemDesign令牌 again).
  6. Only proceed to a Workflow after login is confirmed.

HARD GATE: Until login is confirmed via gemdesign auth whoami, you MUST NOT perform ANY page-generation work — this includes CLI commands (app, page, style, validate) AND local file operations (writing .html, streaming write, creating the ./output/ directory). Local HTML generation is NOT a workaround for the login gate; a page can only be saved to the platform by an authenticated user, so generating it before login is wasted work. If login fails, stop and resolve authentication first — do not start writing any HTML.

Step 2.5: Clean Up and Configure htmlWorkdir (MUST complete after Step 2, before any Workflow)

After login is confirmed, FIRST clean up stale empty project directories left over from previous interrupted sessions, THEN configure the HTML working directory (htmlWorkdir). The order is MANDATORY: cleanup MUST run BEFORE workdir --path, never after. Both operations MUST complete before starting any Workflow (in particular, before app create).

CRITICAL — Why cleanup MUST run BEFORE workdir (order is non-negotiable): gemdesign server workdir --path ./output creates the ./output directory — at this moment it is an empty workdir with NO project subdirectories ({projectName}__{appuuid}) yet, because app create has not run. gemdesign server cleanup runs pruneEmptyWorkdirs(), which deletes any workdir directory that contains zero project subdirectories AND removes it from the htmlWorkdir config. If you run workdir first and then cleanup, the freshly-created empty ./output is treated as a stale empty workdir — cleanup deletes the directory and wipes it from config, leaving htmlWorkdir empty. Downstream effect: app create skips local folder creation (returns a warning), and server start refuses to start ("未配置 htmlWorkdir..."), causing "page generated but canvas not showing". Running cleanup FIRST avoids this: it clears stale state from previous sessions, then workdir creates ./output LAST so it survives. (Note: cleanup does NOT require htmlWorkdir to be pre-configured — when unconfigured it simply returns "未配置 htmlWorkdir，无需清理" and exits cleanly.)

1. Clean up empty project directories (MUST run FIRST, before configuring htmlWorkdir):

   gemdesign server cleanup
   

   • If htmlWorkdir is not configured yet, the command returns {"success":true,"message":"未配置 htmlWorkdir，无需清理","removedDirs":[],"removedLocks":[],"removedWorkdirs":[],"removedWorkdirDirs":[]} — this is normal, continue to step 2.
   • If htmlWorkdir is already configured from a previous session, the command scans each configured workdir for project subdirectories (named {projectName}__{appuuid}) and:
     • Deletes empty project directories: project subdirectories that contain zero .html files (created by app create but never had a page saved — e.g., the session was interrupted).
     • Cleans orphaned streaming files: .stream.lock files left over from streaming write that was started but never completed.
     • Removes empty workdirs: workdir directories that contain zero project subdirectories are deleted and removed from config (this is exactly why workdir --path MUST run AFTER cleanup, not before).
   • Returns JSON: {"success":true,"message":"清理完成：删除 N 个空项目目录，清理 M 个遗留文件，移除 K 个无项目的 htmlWorkdir","removedDirs":[...],"removedLocks":[...],"removedWorkdirs":[...],"removedWorkdirDirs":[...]}
   • This step is non-blocking: cleanup failures do not prevent proceeding to a Workflow. The command always returns success: true unless an unexpected error occurs.

2. Configure htmlWorkdir (MUST run AFTER step 1; run once, persists across sessions):

   CRITICAL - app create sync-creates the local project folder under htmlWorkdir, and server start validates htmlWorkdir before launching. If htmlWorkdir is not configured, app create skips local folder creation (returns a warning), and server start returns {"success":false,"error":"未配置 htmlWorkdir，请先执行 gemdesign server workdir --path 设置 HTML 工作目录"} and refuses to start. This prevents the background process's cwd from mismatching the actual HTML generation directory, which would cause fileWatcher to miss .html changes and the canvas to stay blank ("page generated but canvas not showing").

   gemdesign server workdir --path ./output
   

   • Relative paths are resolved against the current working directory to an absolute path.
   • Verify with gemdesign server workdir (no flags) - returns {"success":true,"htmlWorkdir":[""]}.
   • The ./output directory created here will NOT be deleted by cleanup within this same Step 2.5, because cleanup already ran in step 1. Do NOT re-run cleanup after this step — re-running it would delete the freshly-created empty ./output (since app create has not run yet and there are no project subdirectories).

Step 3: Start the Local Server (MUST complete after app is created/reused, before any page generation)

CRITICAL - HARD GATE: You MUST open the browser in this step. This is NON-NEGOTIABLE and MUST NOT be skipped, deferred, or treated as optional. Generating any page before the browser is open is a SERIOUS VIOLATION - the user needs the real-time preview surface to see pages as they are generated. You MUST actively open the browser yourself using your platform's built-in browser/preview tool (see step 3 below for the fallback strategy). Do NOT just output a URL in chat text and wait for the user to click it — you MUST programmatically open the browser.

TIMING — Execute INSIDE a Workflow, NOT immediately after login. Step 3 is invoked from within Workflow A/B/C (see each workflow's "Start the local server" step), AFTER the app has been created or reused via gemdesign app create / gemdesign app use and confirmed via gemdesign app info. Do NOT start the server right after Step 2 (login) — the server serves pages from the project subdirectory derived from the app ( = {projectName}__{appuuid}), so the app must exist first. Starting the server before the app exists is a violation.

After Step 1 (CLI installed), Step 2 (Login verified), AND the app is created/reused (inside a Workflow) are all confirmed complete, start the local server for real-time streaming preview.

The local server provides real-time streaming preview of HTML pages as they are being generated. The server is built into the CLI and managed via the gemdesign server commands. The server runs on port 4056 by default; if that port is occupied it auto-retries the next available port (up to 4066).

1. Ensure htmlWorkdir is configured (MUST complete before app create in a Workflow, and before server start):

   htmlWorkdir is configured in Step 2.5 (persists across sessions). app create sync-creates the local project folder under htmlWorkdir, and server start validates htmlWorkdir before launching — if it is not configured, app create skips local folder creation (returns a warning) and server start refuses to start, causing fileWatcher to miss .html changes and the canvas to stay blank ("page generated but canvas not showing").

   If Step 2.5 was skipped (e.g. resuming a session), verify now: gemdesign server workdir (no flags) returns {"success":true,"htmlWorkdir":""}. If it returns an empty htmlWorkdir, run gemdesign server workdir --path ./output before proceeding.

2. Stop any previously running server (MANDATORY before every server start, CANNOT be skipped):

   CRITICAL — 执行 server start 之前必须先执行 server stop 终止之前启动的服务，无论应用是新建还是复用都不可跳过。这确保 fileWatcher 绑定到正确的项目目录，避免残留进程干扰新会话。

   HARD GATE - 严禁跳过此步：无论你认为当前是否已有服务在运行，都必须执行 gemdesign server stop 命令。禁止以"服务器未运行"、"上一次会话已启动"、"浏览器预览已打开"、"为了节省时间"等任何理由跳过 stop。必须以 gemdesign server stop 的实际返回结果作为唯一判定依据。

   gemdesign server stop
   

   • 返回 {"success":true,"message":"本地服务已停止"} 表示已停止，继续下一步。
   • 返回 {"success":false,"error":"未发现运行中的本地服务"} 表示无运行中的服务，忽略此错误继续下一步。
   • 必须等待上述命令返回结果后才能进入第 2 步。在 stop 命令未返回前，不得执行任何 server start 操作。

3. Start the local server using the CLI command:

   gemdesign server start
   

   必须在执行此命令前先完成上一步的 gemdesign server stop，不得在未停止旧服务的情况下直接 start。

   HARD GATE - 顺序约束：server start 必须在 server stop 命令返回结果（成功或"未发现运行中的本地服务"错误）之后才能执行。严禁以下行为：

   • 将 server stop 与 server start 并行执行（例如在同一个并行工具调用批次中）；
   • 在 server stop 命令尚未返回结果时就发起 server start；
   • 先执行 server start 再执行 server stop；
   • 因为"觉得没必要 stop"而跳过 stop 直接 start。

   正确顺序：执行 gemdesign server stop -> 等待命令返回结果 -> 执行 gemdesign server start。这是不可逆的串行依赖关系。

   • If the server starts successfully, the command returns JSON: {"success":true,"port":,"url":"http://localhost:"}
   • If the server fails to start, the command returns JSON with an error: {"success":false,"error":""}
   • On error: Read the error message carefully. Common errors:
     • "服务文件不存在": The CLI installation is incomplete — reinstall the CLI.
     • "服务启动失败，进程已退出": Possible port conflict or config file error — check ~/.gemdesign/config.json.
   • Record the `` from the success response for subsequent steps.

4. Check server status (optional, for debugging):

   gemdesign server status
   

   Returns: {"success":true,"status":"running","port":,"url":"http://localhost:"} or {"success":true,"status":"stopped"}

5. Open the preview (MANDATORY — HARD GATE, DO NOT SKIP): After the server is confirmed running (the server start command returned success), you MUST open the browser and navigate to the service page named GemDesign设计器 (URL: http://localhost: - use the port from the server start response).

   This step is NON-NEGOTIABLE. Do NOT proceed to any page generation workflow (Workflow A/B/C) until the browser is open at http://localhost:. The server being up is NOT the same as the preview being open - the user must SEE the preview surface in the browser.

   DO NOT just output a URL in chat text. You MUST use a tool to actually open the browser. Outputting something like "服务器启动成功！请在浏览器中打开 http://localhost:4056" is a VIOLATION — the browser must be opened programmatically, not by asking the user to click a link.

   How to open the browser — use the following methods in priority order:

   Try the following methods in priority order. Use the FIRST one that is available and succeeds. If a method fails, skip it and try the next:

   Priority	Method	How to use
   1	Your platform's built-in browser/preview tool	You MUST check what browser/preview tools are available on your current agent platform and use the most appropriate one. Different platforms provide different built-in tools — use whichever one your platform offers. Examples of platform-specific tools: Trae provides OpenPreview and the integrated_browser MCP's browser_navigate; Cursor provides its own preview mechanism; other platforms may have equivalent tools. The key requirement is: you MUST use a tool to programmatically open the browser, not just output a URL in chat. Navigate to http://localhost:/ using the tool.
   2	OS default browser command	If no built-in browser/preview tool is available (or it failed), open the default browser via OS command: Windows start http://localhost:/, macOS open http://localhost:/, Linux xdg-open http://localhost:/.
   3	Tell the user to open the URL	If ALL above methods fail or are unavailable, as a last resort, clearly tell the user: "请在浏览器中打开 http://localhost:/ 查看设计器预览" and wait for the user to confirm before proceeding.

   How to find your platform's built-in tool: Check your available tools list — look for tools with names like OpenPreview, browser_navigate, preview, browser, or similar. Any tool that can open a URL in a browser panel qualifies. Use it with the URL http://localhost:/.

   Ensuring success:

   • If the highest-priority method returned an error or you're unsure whether it succeeded, immediately fall back to the next method in the table.
   • After opening the browser, verify the server is still accessible by re-checking the debug endpoint (http://localhost:/api/local/stream/debug returns 200).
   • Only proceed to page generation after you have made a best-effort attempt to open the browser using at least one available method.

   After the preview is open, you may proceed to page generation workflows.

   CRITICAL - The browser is opened EXACTLY ONCE, only here in Step 3. Once the browser is open at http://localhost: (the designer SPA root), you MUST NEVER open the browser again — not during page generation (Workflows A/B/C), not during modification flows, not to "refresh" or "show" a generated page. The designer SPA stays open for the entire session; generated HTML is loaded into an iframe INSIDE the designer via SSE (see "Streaming Write Workflow"), NOT by navigating the browser to a new URL.

   Opening the browser again will navigate it away from the designer to whatever URL you passed — this OVERWRITES the designer with the generated HTML (or a 404), destroying the preview surface the user needs. The URL used to open the browser MUST ALWAYS be the designer root URL http://localhost:/ — NEVER a path to a generated .html file (e.g. http://localhost:/output//.html), NEVER a page-specific URL. Generated pages have no direct browser URL; they are only viewable through the designer's iframe via SSE.

CLI Command Reference

Server Management

gemdesign server start [--port ]   # 启动本地设计器服务（默认端口 4056）
gemdesign server stop                    # 停止本地设计器服务
gemdesign server status                  # 查看服务运行状态
gemdesign server workdir --path    # 保存 HTML 工作目录（htmlWorkdir，相对路径基于当前目录解析为绝对路径）
gemdesign server workdir                 # 查看当前 htmlWorkdir
gemdesign server workdir --clear         # 清除 htmlWorkdir 配置
gemdesign server cleanup                 # 清理空项目目录和遗留的流式文件

server workdir 保存 HTML 工作目录到 ~/.gemdesign/config.json 的 htmlWorkdir 字段。本地服务启动后通过 fileWatcher 监听此目录下的 .html 文件变更，并经 SSE 推送到浏览器画布。app create 会在此目录下同步创建项目子目录 {projectName}__{appuuid}，server start 也会在启动前校验 htmlWorkdir 是否已配置--未配置时 app create 跳过本地目录创建（返回 warning），server start 拒绝启动并返回错误提示，避免后台进程 cwd 与实际 HTML 生成目录不一致导致"页面生成但画布不显示"。建议在登录后、app create 之前执行一次 gemdesign server workdir --path ./output（路径通常是 ./output，即页面 HTML 的根目录）。配置一次后持久化，后续无需重复设置。 server start 以后台进程方式启动本地服务。执行 server start 之前必须先执行 server stop 终止之前的服务，不得在未停止旧服务的情况下直接 start。server stop 严禁跳过（即使你认为没有运行中的服务也必须执行该命令），且 server start 必须等 server stop 命令返回结果后才能执行——禁止将两者并行执行、或在 stop 未返回时就发起 start。启动成功返回含 port 和 url 的 JSON；失败返回含 error 的 JSON，需仔细阅读错误信息诊断并修复后再重试（重试前同样要先 stop）。 server stop stops the running server. On Windows, uses taskkill to terminate the process tree. Returns error if no server is running or if the process cannot be terminated — 此时该错误可忽略（表示本就无运行中的服务），但仍视为 stop 步骤已执行完成，可继续 start。 server status returns the current status (running or stopped), port, and URL if running.

Authentication

gemdesign auth login --token    # 配置 GemDesign 令牌
gemdesign auth whoami                  # Verify identity

App Management

gemdesign app create --name "MyApp" --workdir  [--type web|app] [--width ] [--height ]    # Create new app (sync-creates local project folder under --workdir), --type defaults to web
gemdesign app list                     # List all apps
gemdesign app info [--appuuid ]    # App details
gemdesign app use --appuuid  --workdir        # Switch current default app (creates/locates local project folder under --workdir)

app create 画布尺寸: --width/--height 用于指定画布像素尺寸。不传时按 --type 取默认值：web -> 1920×1080，app -> 440×956。传入的尺寸会随应用信息同步到本地设计器画布（覆盖默认值）。示例：gemdesign app create --name "PadApp" --type app --width 768 --height 1024。 CRITICAL - app create and app use require --workdir: app create 和 app use 的 --workdir 是必填参数，指定本地项目子目录 {projectName}__{appuuid} 的父目录。路径由 agent 显式给出，CLI 不再通过配置自动猜测。--workdir 会自动追加到 htmlWorkdir 配置数组（去重），local-server 据此扫描所有项目目录。建议传入 ./output（即 gemdesign server workdir --path ./output 配置的同一目录）。page create 的 --file 同理：lock 文件直接写入 --file 推导出的项目子目录，保证 lock 与 html 同目录。 appuuid priority: --appuuid flag > defaultAppUuid (set by app create/app use) > GEMDESIGN_APPUUID env Once you run app create or app use, subsequent page commands don't need --appuuid. IMPORTANT: Always check gemdesign app list BEFORE creating a new app. Reuse existing apps to keep all pages in the same project folder. Only create a new app when the user explicitly asks for one. CRITICAL - Never create duplicate apps: Never call gemdesign app create more than once in a single session/task. If you have already run app create in this session, you MUST NOT run it again — even if a later workflow step or retry seems to require app setup. Instead, reuse the existing app by running gemdesign app list to find it, then gemdesign app use --appuuid --workdir ./output. Creating a second app leaves the first one empty and orphaned on the platform. CRITICAL - Session lock error handling: The CLI now automatically verifies session locks via appuuid. If app create returns stage: "appCreateSession" (session lock exists and the app still exists on remote), do NOT retry with --force. Instead: (1) Run gemdesign app use --appuuid --workdir ./output to reuse the app. (2) If the existing app is from a different completed task, run gemdesign app end-session, then app create (without --force). (3) Only use --force if you have verified via app list that the session-lock app was deleted from the remote — note that the CLI now auto-cleans stale session locks (app deleted from remote), so --force should rarely be needed. (4) If app create returns stage: "appCreateSessionVerify" (unable to verify app existence due to network error), wait and retry — do NOT use --force. CRITICAL - Restart the server around every app create or app use: 正确顺序为：gemdesign server stop -> (等待 stop 命令返回结果) -> (确保 htmlWorkdir 已配置) -> gemdesign app create / gemdesign app use -> gemdesign server start。该顺序由 workflow 步骤强制执行，不要作为独立序列重复执行。执行 server start 之前必须先执行 server stop 终止之前的服务，无论应用是新建还是复用，否则旧服务的 fileWatcher 仍绑定在前一个 app 的 ，新页面不会推送到画布。**`server stop` 这一步严禁跳过**（即使你认为没有运行中的服务也必须执行），且 **`server start` 必须等 `server stop` 命令返回结果后才能执行**，禁止并行执行或先 start 后 stop。 **IMPORTANT - Output app info to user**: After selecting/switching/creating an app (i.e., after any `app create`, `app use`, or `app info` call that establishes the working app), you MUST clearly tell the user in your text response which app is now the active target for page generation. At minimum, output the **app name** and **appuuid** (and ideally the computed ). This ensures the user always knows which app pages will be generated/modified in, and can interrupt if the wrong app was picked. See the "Output current app info to user" step in each workflow for the exact format. CRITICAL - App type determines page type: Apps have a type - web (桌面端) or app (移动端) - returned by app info as the pageScene field. When generating new pages, the page type MUST match the app type: a web app can only contain web pages (desktop layout, wide screen), and an app app can only contain app pages (mobile layout, narrow screen). Before generating any HTML, check the app's pageScene from app info and design the page accordingly. Do NOT generate a desktop-width page for an app type app, or a mobile-width page for a web type app.

Style Search (optional helper)

gemdesign style search --keywords "科技,深蓝,企业" --limit 5   # Search styles
gemdesign style get --id 


  
    <!-- Page DOM -->
  

  <!-- jsHandle functions (optional) -->
  <!--  -->

  <!-- Interaction DSL (MUST be last script) -->
  

Validation Rules Summary

The gemdesign validate command checks:

Tips

• Always validate before saving — gemdesign validate catches errors early
• For batch generation, validate each page individually before saving
• Save HTML locally for every page: ./output//.html for editing and saving to the platform. Always compute = {projectName}__{appuuid> first via gemdesign app info. The CLI is idempotent - passing a path that already contains `` will not duplicate it.
• When creating a new page, pass a readable --pageuuid (e.g. home, login) - use the same value as data-uuid in navigation elements, so you don't need to update them after saving
• Use gemdesign page get --file to retrieve editable HTML+DSL before modifying
• The full page spec is available at page-spec.md in the CLI project directory