tirtc-device-builder 0.8.1 → 0.9.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.0
+
+- Add native Skill-directory installation for Codex, Claude Code, OpenCode,
+  Gemini CLI, GitHub Copilot, Qwen Code, Windsurf Cascade, Cline, and Kiro.
+- Add `--client` support to both `install` and the resumable `setup` workflow,
+  plus a `clients` command that reports resolved user directories.
+- Keep one portable `SKILL.md` and supporting resource tree across clients,
+  while preserving explicit replacement and hardware-operation approvals.
+
 ## 0.8.1
 
 - Separate rapid `idf.py flash` iteration from portable evidence-bundle export,

package/README.md

@@ -1,6 +1,6 @@
 # TiRTC Device Builder
 
-TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
+TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
 当前仓库提供一个 Skill：
 
@@ -43,9 +43,15 @@ npm --version
 npx --yes tirtc-device-builder@latest setup esp32 --install
 ```
 
+默认安装到 Codex。使用其他客户端时增加 `--client`，例如：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install --client qwen-code
+```
+
 这条命令会：
 
-- 把 `tirtc-esp32-builder` 安装到 Codex Skill 目录；
+- 把 `tirtc-esp32-builder` 安装到所选 Agent 客户端的 Skill 目录；
 - 下载 ESP32 Device Kit 并校验 SHA-256；
 - 复用当前可用的 ESP-IDF 5.5.x，找不到时安装 ESP-IDF 5.5.4；
 - 安装 Espressif 管理的 ESP32-S3 工具链；
@@ -59,21 +65,21 @@ npx --yes tirtc-device-builder@latest setup esp32 --install
 ```text
 OVERALL: PASS
 SETUP: READY
-Start a new Codex session and invoke $tirtc-esp32-builder.
+Start a new Codex session, then ask it to use tirtc-esp32-builder.
 ```
 
 如果看到 `OVERALL: NEEDS_SETUP`、`MISS` 或 `FAIL`，先看[常见问题](#常见问题)。
 
-### 3. 重新打开 Codex
+### 3. 重新打开 Agent 客户端
 
-Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex 会话，再打开一个新会话。
+Skill 通常在 Agent 会话启动时被发现。安装完成后，关闭当前会话，再打开一个新会话。
 
-### 4. 把板卡和目标告诉 Codex
+### 4. 把板卡和目标告诉 Agent
 
 把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。先指定工作区根目录，本地路径尽量相对工作区填写；不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
 ```text
-请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
+请使用 tirtc-esp32-builder Skill 完成这块开发板的 TiRTC 移植。
 
 开发板：
 - 厂商、完整型号、PCB/硬件版本：<填写>
@@ -339,25 +345,52 @@ tirtc-device-builder setup esp32 --install
 
 安装命令是 `npm install`，不要写成 `npm --install`。
 
-只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Codex Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
+只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Agent Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
 
 安装公开包不需要执行 `npm login`；这个命令只和维护者发布新版本有关。
 
 ### 只安装 Skill
 
-如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Codex Skill：
+如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Agent Skill：
 
 ```bash
 npx --yes tirtc-device-builder@latest install esp32
+npx --yes tirtc-device-builder@latest install esp32 --client gemini
 ```
 
 这条命令不安装 ESP-IDF，也不下载 Device Kit。完整的新用户环境仍建议使用 `setup esp32 --install`。
 
+### 支持的 Agent 客户端
+
+同一个 `tirtc-esp32-builder` Skill 会完整复制到所选客户端的原生目录，不维护客户端专用的内容副本。先用下面的命令查看当前机器解析出的目录：
+
+```bash
+npx --yes tirtc-device-builder@latest clients
+```
+
+| `--client` | 客户端 | 默认 Skill 根目录 |
+|---|---|---|
+| `codex` | Codex（默认） | `${CODEX_HOME:-~/.codex}/skills` |
+| `claude-code` | Claude Code | `~/.claude/skills` |
+| `opencode` | OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode/skills` |
+| `gemini` | Gemini CLI | `~/.gemini/skills` |
+| `copilot` | GitHub Copilot | `~/.copilot/skills` |
+| `qwen-code` | Qwen Code | `~/.qwen/skills` |
+| `windsurf` | Windsurf Cascade | `~/.codeium/windsurf/skills` |
+| `cline` | Cline | `~/.cline/skills` |
+| `kiro` | Kiro | `~/.kiro/skills` |
+
+也可以使用 `claude`、`gemini-cli`、`github-copilot`、`qwen`、`cascade`、`kiro-cli` 等别名。`--skills-dir` 的优先级高于默认目录，适合项目级安装或客户端使用非默认配置目录的情况。
+
+`--client` 只选择 Skill 的安装目录和提示文案，不绑定模型服务。DeepSeek、Qwen、GLM、Kimi、OpenAI 或 Claude 等模型仍在对应客户端中配置；只要客户端能发现 Skill 并允许文件、终端等所需工具，就继续使用同一份工作流。
+
+Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实验性 Skills 功能；安装器不会修改客户端自身的权限或功能开关。
+
 ### 默认目录
 
 | 内容 | 默认位置 |
 |---|---|
-| Codex Skill | `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder` |
+| Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
 | Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.1` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
@@ -436,6 +469,7 @@ npx --yes tirtc-device-builder@latest setup esp32
 ```bash
 npx --yes tirtc-device-builder@latest --help
 npx --yes tirtc-device-builder@latest list
+npx --yes tirtc-device-builder@latest clients
 npx --yes tirtc-device-builder@latest setup esp32 --help
 ```
 
@@ -759,15 +793,16 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 如果指定目录已存在但内容不完整或版本错误，安装器会拒绝覆盖。换一个空的新路径，或先人工备份原目录。
 
-### 安装完成后 Codex 找不到 Skill
+### 安装完成后 Agent 客户端找不到 Skill
 
-关闭当前 Codex 会话并重新打开。再检查默认文件是否存在：
+关闭当前 Agent 会话并重新打开。先查看客户端目录，再检查对应文件是否存在：
 
 ```bash
-ls -l ~/.codex/skills/tirtc-esp32-builder/SKILL.md
+npx --yes tirtc-device-builder@latest clients
+ls -l <skills-dir>/tirtc-esp32-builder/SKILL.md
 ```
 
-设置过 `CODEX_HOME` 或 `--skills-dir` 时，要检查对应目录。不要同时把 Skill 安装到多个位置。
+确认安装和启动的是同一个客户端，例如 Qwen Code 要使用 `--client qwen-code`。设置过 `CODEX_HOME`、`XDG_CONFIG_HOME` 或 `--skills-dir` 时，要检查对应目录。项目级目录由客户端自身规则决定，可以用 `--skills-dir` 显式指定。
 
 ### 已有 Skill，安装器拒绝覆盖
 
@@ -926,8 +961,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.8.1 -m "v0.8.1"
-git push origin v0.8.1
+git tag -a v0.9.0 -m "v0.9.0"
+git push origin v0.9.0
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/agent-clients.js

@@ -0,0 +1,141 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DEFAULT_AGENT_CLIENT = "codex";
+
+const CLIENTS = [
+  {
+    id: "codex",
+    displayName: "Codex",
+    aliases: ["codex"],
+    skillsDir(environment, home) {
+      const codexHome = environment.CODEX_HOME
+        ? resolve(environment.CODEX_HOME)
+        : join(home, ".codex");
+      return join(codexHome, "skills");
+    },
+  },
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    aliases: ["claude-code", "claude"],
+    skillsDir(_environment, home) {
+      return join(home, ".claude", "skills");
+    },
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    aliases: ["opencode", "open-code"],
+    skillsDir(environment, home) {
+      const configHome = environment.XDG_CONFIG_HOME
+        ? resolve(environment.XDG_CONFIG_HOME)
+        : join(home, ".config");
+      return join(configHome, "opencode", "skills");
+    },
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    aliases: ["gemini", "gemini-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".gemini", "skills");
+    },
+  },
+  {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    aliases: ["copilot", "github-copilot"],
+    skillsDir(_environment, home) {
+      return join(home, ".copilot", "skills");
+    },
+  },
+  {
+    id: "qwen-code",
+    displayName: "Qwen Code",
+    aliases: ["qwen-code", "qwen"],
+    skillsDir(_environment, home) {
+      return join(home, ".qwen", "skills");
+    },
+  },
+  {
+    id: "windsurf",
+    displayName: "Windsurf Cascade",
+    aliases: ["windsurf", "cascade"],
+    skillsDir(_environment, home) {
+      return join(home, ".codeium", "windsurf", "skills");
+    },
+  },
+  {
+    id: "cline",
+    displayName: "Cline",
+    aliases: ["cline"],
+    activationNote:
+      "Cline may require Settings > Features > Enable Skills before discovery.",
+    skillsDir(_environment, home) {
+      return join(home, ".cline", "skills");
+    },
+  },
+  {
+    id: "kiro",
+    displayName: "Kiro",
+    aliases: ["kiro", "kiro-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".kiro", "skills");
+    },
+  },
+];
+
+const CLIENT_BY_ALIAS = new Map(
+  CLIENTS.flatMap((client) =>
+    client.aliases.map((alias) => [alias, client]),
+  ),
+);
+
+function userHome(environment) {
+  if (process.platform === "win32") {
+    if (environment.USERPROFILE) {
+      return resolve(environment.USERPROFILE);
+    }
+    if (environment.HOMEDRIVE && environment.HOMEPATH) {
+      return resolve(`${environment.HOMEDRIVE}${environment.HOMEPATH}`);
+    }
+  } else if (environment.HOME) {
+    return resolve(environment.HOME);
+  }
+  return homedir();
+}
+
+export function listAgentClients() {
+  return CLIENTS;
+}
+
+export function resolveAgentClient(identifier) {
+  return CLIENT_BY_ALIAS.get(String(identifier).trim().toLowerCase()) ?? null;
+}
+
+export function requireAgentClient(identifier) {
+  const client = resolveAgentClient(identifier);
+  if (!client) {
+    throw new Error(
+      `unsupported client: ${identifier}; supported clients: ${CLIENTS.map((item) => item.id).join(", ")}`,
+    );
+  }
+  return client;
+}
+
+export function defaultSkillsDir(client, environment = process.env) {
+  const resolvedClient =
+    typeof client === "string" ? requireAgentClient(client) : client;
+  return resolvedClient.skillsDir(environment, userHome(environment));
+}
+
+export function clientSessionHint(client, skillName) {
+  const lines = [
+    `Start a new ${client.displayName} session, then ask it to use ${skillName}.`,
+  ];
+  if (client.activationNote) {
+    lines.push(client.activationNote);
+  }
+  return lines.join("\n");
+}

package/bin/setup-esp32.js

@@ -10,6 +10,13 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { ESP32_KIT } from "./esp32-kit-metadata.js";
 
 const EXPECTED_IDF_LINE = "5.5";
@@ -43,10 +50,10 @@ function setupRootFrom(environment) {
   );
 }
 
-function takeValue(args, index, option) {
+function takeValue(args, index, option, kind = "a path") {
   const value = args[index + 1];
   if (!value || value.startsWith("--")) {
-    throw new Error(`${option} requires a path`);
+    throw new Error(`${option} requires ${kind}`);
   }
   return value;
 }
@@ -54,13 +61,15 @@ function takeValue(args, index, option) {
 export function parseSetupOptions(args, defaults = {}) {
   const environment = defaults.environment ?? process.env;
   const options = {
+    client:
+      defaults.client ?? requireAgentClient(DEFAULT_AGENT_CLIENT),
     forceSkill: false,
     help: false,
     idfDir: null,
     install: false,
     kitArchive: null,
     rootDir: setupRootFrom(environment),
-    skillsDir: defaults.skillsDir,
+    skillsDir: null,
     thingConnectRoot: null,
   };
 
@@ -78,6 +87,13 @@ export function parseSetupOptions(args, defaults = {}) {
       options.forceSkill = true;
       continue;
     }
+    if (argument === "--client") {
+      options.client = requireAgentClient(
+        takeValue(args, index, argument, "a name"),
+      );
+      index += 1;
+      continue;
+    }
     if (
       argument === "--root" ||
       argument === "--skills-dir" ||
@@ -103,9 +119,7 @@ export function parseSetupOptions(args, defaults = {}) {
     throw new Error(`unknown setup option: ${argument}`);
   }
 
-  if (!options.skillsDir) {
-    throw new Error("setup requires a default skills directory");
-  }
+  options.skillsDir ??= defaultSkillsDir(options.client, environment);
   if (options.forceSkill && !options.install) {
     throw new Error("--force-skill requires --install");
   }
@@ -123,8 +137,9 @@ Usage:
 
 Options:
   --install                    Install missing user-space components
+  --client <name>              Agent client (default: codex)
   --root <path>                Managed files (default: ~/.tirtc-device-builder)
-  --skills-dir <path>          Codex skills directory
+  --skills-dir <path>          Override the selected client's Skill directory
   --thing-connect-root <path>  Reuse an existing Device Kit or legacy workspace
   --kit-archive <path>         Install from a local verified Kit archive
   --idf-dir <path>             Reuse or install ESP-IDF at this path
@@ -133,12 +148,13 @@ Options:
 
 Examples:
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder setup esp32 --install --root /opt/tirtc-dev
 
 Check mode is read-only. --install downloads the pinned ESP32 Device Kit,
 may clone ESP-IDF v5.5.4, runs Espressif's user-space tool installer, and
-installs the Codex Skill. It does not run sudo or edit shell profiles.`);
+installs the Agent Skill. It does not run sudo or edit shell profiles.
+Supported clients: ${listAgentClients().map((client) => client.id).join(", ")}.`);
 }
 
 function printCheck(status, name, detail) {
@@ -420,6 +436,7 @@ function writeManagedEnvironment(context, packageVersion) {
     device_kit_version: context.deviceKit.version,
     device_kit_root: context.thingConnectRoot,
     thing_connect_root: context.thingConnectRoot,
+    client: context.client.id,
     skills_dir: context.skillsDir,
   };
   writeAtomic(
@@ -542,6 +559,7 @@ function setupContext(options, runtime) {
   const skillVersion = readSkillVersion(skillTarget);
   return {
     activeIdf: active,
+    client: options.client,
     configPath,
     idf,
     idfDir,
@@ -569,8 +587,8 @@ function printState(context, runtime) {
   printCheck("INFO", "setup root", context.rootDir);
   printCheck(
     context.skillReady ? "PASS" : "MISS",
-    "Codex Skill",
-    `${context.skillTarget} (version ${
+    "Agent Skill",
+    `${context.client.displayName}: ${context.skillTarget} (version ${
       context.skillVersion || "missing"
     }; expected ${runtime.packageVersion})`,
   );
@@ -639,13 +657,13 @@ function installSkill(options, context, runtime) {
   const present = existsSync(join(context.skillTarget, "SKILL.md"));
   if (present && context.skillReady && !options.forceSkill) {
     console.log(
-      `SKIP  Codex Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
+      `SKIP  ${context.client.displayName} Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
     );
     return;
   }
   if (present && !options.forceSkill) {
     throw new Error(
-      `Codex Skill at ${context.skillTarget} has version ${
+      `${context.client.displayName} Skill at ${context.skillTarget} has version ${
         context.skillVersion || "missing"
       }, expected ${runtime.packageVersion}; rerun with --force-skill to replace it`,
     );
@@ -654,6 +672,8 @@ function installSkill(options, context, runtime) {
     runtime.cliPath,
     "install",
     runtime.platform.name,
+    "--client",
+    context.client.id,
     "--skills-dir",
     options.skillsDir,
   ];
@@ -830,8 +850,8 @@ export function runEsp32Setup(args, input) {
   let options;
   try {
     options = parseSetupOptions(args, {
+      client: input.defaultClient,
       environment: runtime.environment,
-      skillsDir: input.defaultSkillsDir,
     });
   } catch (error) {
     console.error(
@@ -849,8 +869,12 @@ export function runEsp32Setup(args, input) {
   if (!options.install) {
     if (!isReady(context)) {
       console.log("OVERALL: NEEDS_SETUP");
+      const clientOption =
+        context.client.id === "codex"
+          ? ""
+          : ` --client ${context.client.id}`;
       console.log(
-        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install`,
+        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install${clientOption}`,
       );
       return 1;
     }
@@ -867,7 +891,9 @@ export function runEsp32Setup(args, input) {
     return 1;
   }
   console.log("INSTALL PLAN:");
-  console.log(`  Skill:        ${context.skillTarget}`);
+  console.log(
+    `  Skill:        ${context.skillTarget} (${context.client.displayName})`,
+  );
   console.log(`  Device Kit:   ${context.thingConnectRoot} (${ESP32_KIT.version})`);
   console.log(`  ESP-IDF:      ${context.idfDir} (${PINNED_IDF_VERSION})`);
   console.log(`  IDF tools:    ${context.idfToolsPath || "existing default"}`);
@@ -917,6 +943,6 @@ export function runEsp32Setup(args, input) {
   }
   console.log("SETUP: READY");
   console.log(`Environment helper: ${join(context.rootDir, "env.sh")}`);
-  console.log("Start a new Codex session and invoke $tirtc-esp32-builder.");
+  console.log(clientSessionHint(context.client, runtime.platform.skill));
   return 0;
 }

package/bin/tirtc-device-builder.js

@@ -9,9 +9,15 @@ import {
   renameSync,
   rmSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { runEsp32Setup } from "./setup-esp32.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -35,7 +41,8 @@ function printHelp() {
 
 Usage:
   tirtc-device-builder list
-  tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
+  tirtc-device-builder clients
+  tirtc-device-builder install <platform> [--client <name>] [--skills-dir <path>] [--force]
   tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
   tirtc-device-builder boards <platform> <list|validate|match|init-identity|candidate> [options]
@@ -46,15 +53,18 @@ Platforms:
 
 Examples:
   npx tirtc-device-builder install esp32
+  npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
   npx tirtc-device-builder doctor esp32 --project /absolute/path/project
   npx tirtc-device-builder boards esp32 match --identity ./board-identity.json
 
-Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
-preserved unless --force is explicitly supplied. Setup checks are read-only;
-setup --install installs missing user-space components without running sudo.`);
+Install defaults to the selected client's user Skill directory; Codex is the
+default client. Run "clients" to list supported names and resolved directories.
+Existing skills are preserved unless --force is explicitly supplied. Setup
+checks are read-only; setup --install installs missing user-space components
+without running sudo.`);
 }
 
 function fail(message) {
@@ -71,17 +81,11 @@ function resolvePlatform(identifier) {
   return null;
 }
 
-function defaultSkillsDir() {
-  const codexHome = process.env.CODEX_HOME
-    ? resolve(process.env.CODEX_HOME)
-    : join(homedir(), ".codex");
-  return join(codexHome, "skills");
-}
-
 function parseInstallOptions(args) {
   const options = {
+    client: requireAgentClient(DEFAULT_AGENT_CLIENT),
     force: false,
-    skillsDir: defaultSkillsDir(),
+    skillsDir: null,
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -90,6 +94,15 @@ function parseInstallOptions(args) {
       options.force = true;
       continue;
     }
+    if (argument === "--client") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--client requires a name");
+      }
+      options.client = requireAgentClient(value);
+      index += 1;
+      continue;
+    }
     if (argument === "--skills-dir") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
@@ -102,6 +115,7 @@ function parseInstallOptions(args) {
     throw new Error(`unknown install option: ${argument}`);
   }
 
+  options.skillsDir ??= defaultSkillsDir(options.client);
   return options;
 }
 
@@ -151,8 +165,10 @@ function installSkill(platform, options) {
   if (movedExisting && existsSync(backup)) {
     rmSync(backup, { force: true, recursive: true });
   }
-  console.log(`Installed ${platform.skill} ${PACKAGE.version} to ${target}`);
-  console.log(`Start a new Codex session, then invoke $${platform.skill}.`);
+  console.log(
+    `Installed ${platform.skill} ${PACKAGE.version} for ${options.client.displayName} to ${target}`,
+  );
+  console.log(clientSessionHint(options.client, platform.skill));
 }
 
 function runDoctor(platform, args) {
@@ -214,6 +230,15 @@ function main(args) {
     }
     return 0;
   }
+  if (args[0] === "clients") {
+    for (const client of listAgentClients()) {
+      const marker = client.id === DEFAULT_AGENT_CLIENT ? " (default)" : "";
+      console.log(
+        `${client.id}\t${client.displayName}${marker}\t${defaultSkillsDir(client)}`,
+      );
+    }
+    return 0;
+  }
 
   const [command, identifier, ...rest] = args;
   if (
@@ -244,7 +269,7 @@ function main(args) {
     }
     return runEsp32Setup(rest, {
       cliPath: fileURLToPath(import.meta.url),
-      defaultSkillsDir: defaultSkillsDir(),
+      defaultClient: requireAgentClient(DEFAULT_AGENT_CLIENT),
       packageRoot: PACKAGE_ROOT,
       packageVersion: PACKAGE.version,
       platform,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.1",
-  "description": "Install and run TiRTC device-development skills for Codex.",
+  "version": "0.9.0",
+  "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {
     "name": "TangeAI",
@@ -30,6 +30,10 @@
   },
   "keywords": [
     "codex",
+    "agent-skills",
+    "claude-code",
+    "gemini-cli",
+    "qwen-code",
     "skill",
     "tirtc",
     "esp32",

package/skills/tirtc-esp32-builder/USAGE.md

@@ -5,14 +5,15 @@
 ```bash
 npx tirtc-device-builder@latest setup esp32
 npx tirtc-device-builder@latest setup esp32 --install
+npx tirtc-device-builder@latest clients
 ```
 
-第一条命令只检查；第二条命令自动安装用户目录内缺失的 Skill、带校验的 ESP32 Device Kit、ESP-IDF 5.5.4 和 ESP32-S3 工具链，最后复跑 Doctor。它不执行 `sudo`，也不修改 shell 配置。安装完成后新开 Codex 会话即可调用 Skill。
+第一条命令只检查；第二条命令自动安装用户目录内缺失的 Skill、带校验的 ESP32 Device Kit、ESP-IDF 5.5.4 和 ESP32-S3 工具链，最后复跑 Doctor。它不执行 `sudo`，也不修改 shell 配置。默认客户端是 Codex；Gemini CLI、GitHub Copilot、Qwen Code、Windsurf、Cline、Kiro、Claude Code 和 OpenCode 可通过 `--client <name>` 选择，第三条命令会列出名称和实际安装目录。安装完成后重新启动所选 Agent 客户端。
 
-安装后可在 Codex 中显式调用：
+安装后可直接要求 Agent 使用该 Skill：
 
 ```text
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 开发板：<厂商、完整型号、PCB 版本>
 资料与实物对应：<是/否/未知>
@@ -48,24 +49,24 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 只有板卡型号：
 
 ```text
-$tirtc-esp32-builder 分析 <厂商> <型号> <硬件版本>，目标是 H5 实时视频、talkback 和 AI 对讲。先输出缺失资料与能力结论。
+请使用 tirtc-esp32-builder Skill 分析 <厂商> <型号> <硬件版本>，目标是 H5 实时视频、talkback 和 AI 对讲。先输出缺失资料与能力结论。
 ```
 
 提供本地资料：
 
 ```text
-$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI/CALL/VOIP ESP-IDF 工程并编译；AI/CALL/VOIP 必须通过 AEC 门禁。
+请使用 tirtc-esp32-builder Skill、原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI/CALL/VOIP ESP-IDF 工程并编译；AI/CALL/VOIP 必须通过 AEC 门禁。
 ```
 
 完整实机流程：
 
 ```text
-$tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧录到 /dev/ttyACM0，验证绑定、H5 和 AI，并生成 TIRTC_PORTING_REPORT.md。
+请使用 tirtc-esp32-builder Skill 和 /path/hardware-ir.json 生成工程，编译后烧录到 /dev/ttyACM0，验证绑定、H5 和 AI，并生成 TIRTC_PORTING_REPORT.md。
 ```
 
 ## ESP-IDF 环境检查
 
-将 `<skill-dir>` 替换为安装后的 Skill 路径，例如 `~/.codex/skills/tirtc-esp32-builder`。
+将 `<skill-dir>` 替换为 `clients` 命令显示的 Skill 根目录下的 `tirtc-esp32-builder`，例如 `~/.qwen/skills/tirtc-esp32-builder`。
 
 生成工程前检查工作区和开发环境：
 

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.8.1
+0.9.0

package/skills/tirtc-esp32-builder/assets/developer-intake-prompt.md

@@ -5,7 +5,7 @@
 ## 精简模板
 
 ```text
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 请为下面这块开发板完成 ThingConnect TiRTC ESP32 接入。
 

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -1,28 +1,30 @@
-$tirtc-esp32-builder
+请使用 tirtc-esp32-builder Skill。
 
 请在当前工作区完成一次立创·实战派 ESP32-S3 的 ThingConnect TiRTC clean-room L-1/L0/L1 接入验证。
 
 这是 Skill、提示词和开发板资料的独立有效性测试。允许访问外网。
 
-前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
+前置条件（必须由开发者在启动本次 Agent 会话前完成，不属于本提示词内的操作）：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.1 setup esp32 --install --force-skill
+export TIRTC_AGENT_CLIENT=codex
+npx --yes tirtc-device-builder@0.9.0 setup esp32 --install \
+  --client "$TIRTC_AGENT_CLIENT" --force-skill
 ```
 
-该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
+把 `TIRTC_AGENT_CLIENT` 改为 `clients` 命令列出的目标客户端名称。该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Agent 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
 
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.8.1 --version
-npx --yes tirtc-device-builder@0.8.1 setup esp32
+npx --yes tirtc-device-builder@0.9.0 --version
+npx --yes tirtc-device-builder@0.9.0 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.8.1、已安装 Skill 的 `VERSION` 为 0.8.1、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.9.0、已安装 Skill 的 `VERSION` 为 0.9.0、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
-- 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。
+- 将启动 Agent 客户端时的当前目录定义为 `WORKSPACE_ROOT`。
 - 所有工程输入和输出必须位于 `WORKSPACE_ROOT`。
 - 不得读取 `WORKSPACE_ROOT` 之外的项目、兄弟目录、父目录项目、备份、旧构建、日志、报告或 artifact。
 - 如果目标输出目录已经存在，停止并报告 clean-room 条件不成立；不要读取、覆盖或删除该目录。

package/skills/tirtc-esp32-builder/references/environment.md

@@ -37,7 +37,7 @@ Add `--project <generated-project>` after generation so the doctor can compare `
 
 The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. A managed Kit is ready only when its generator and SDK files exist and `manifest.json` declares the exact pinned `kit_version`. A stale environment or managed configuration that points at an older Kit is ignored in favor of the current versioned managed path. The setup configuration records the version read from that manifest; it never substitutes the desired version for the actual one.
 
-The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new Codex session.
+The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new session in the selected Agent client.
 
 For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise resolve the generation root in this order: