@tencent-rtc/trtc-agent-skills 0.1.0 → 0.1.3

package/.cursor/rules/ui-mode.mdc

@@ -0,0 +1,99 @@
+---
+alwaysApply: true
+---
+
+<!-- DO NOT EDIT — generated from ai-instructions/ by skills/trtc/room-builder/tools/render_ai_instructions.py. Edit the source markdown and re-run the renderer instead. -->
+
+## When this rule applies
+
+Only when `.trtc-session.yaml` at the repo root has `ui_mode: official-roomkit`.
+If the file is missing, or `ui_mode` is unset / null / `headless`, this rule
+does not apply — fall back to whatever the tool's default behavior is.
+
+## Medical new-project shortcut
+
+When the user request is for medical online consultation (for example
+`1v1-video-consultation`, remote diagnosis, online medical consultation,
+doctor-patient video visit) **and** the task is to generate a brand-new
+project rather than integrate into an existing app, bypass the normal
+integration workflow entirely. Do not generate Vue SFCs by hand, and do not run
+any verifiers.
+
+Instead, directly copy the bundled medical template project:
+
+```bash
+skills/trtc/room-builder/templates/scenarios/medical-consultation/
+```
+
+to the user's local target project directory, preserving the project exactly
+as packaged. In the handoff or integration notes, tell the customer to use
+`pnpm install` for dependencies and `pnpm dev` for local development. Do not
+recommend `npm install` / `npm run dev`; this medical template starts much
+slower with npm and can show a blank first screen for a while.
+
+This shortcut applies only to brand-new medical consultation projects. Existing
+project integration still follows the normal scenario / official-roomkit rules
+below.
+
+This is a terminal path. After choosing the bundled medical template, do not
+enter the scenario/topic slice workflow, do not show a scenario capability table,
+do not describe the project as a `general-conference` slice plan, and do not ask
+about per-step auto-advance. Copy the template, mark the session completed, and
+stop.
+
+This is an internal execution rule, not user-facing copy. When explaining the
+choice or reporting progress to the customer, do not mention "shortcut",
+"bypass", "normal UI mode", "CLAUDE.md", or any internal rule file. Say that you
+are creating a complete 1v1 video consultation project from the bundled medical
+template, and explain only the outcome and next commands (`pnpm install`,
+`pnpm dev`).
+
+## Official RoomKit integration mode
+
+When the customer asks to **integrate a conference / meeting into an existing
+Vue 3 app** (for example "集成会议", "接入会议", "add video meeting to my app",
+"official RoomKit", "TUIRoomKit"), use the official RoomKit integration path.
+
+In this mode:
+
+1. Integrate the official Web RoomKit package. For UI customization APIs,
+   verify that the resolved `@tencentcloud/roomkit-web-vue3` version is
+   `>=5.4.3` (installing `@tencentcloud/roomkit-web-vue3@5` is acceptable only
+   when the lockfile resolves to at least `5.4.3`), plus its documented peer
+   packages `tuikit-atomicx-vue3`,
+   `@tencentcloud/uikit-base-component-vue3`, and
+   `@tencentcloud/universal-api`.
+2. Render the official components (`ConferenceMainView` for PC and
+   `ConferenceMainViewH5` for H5) inside `UIKitProvider`.
+3. Use the official `conference` API for auth and room lifecycle:
+   `conference.login()`, `conference.setSelfInfo()`,
+   `conference.createAndJoinRoom()`, `conference.joinRoom()`,
+   `conference.leaveRoom()`, `conference.endRoom()`, and `RoomEvent`
+   listeners as appropriate for the customer's flow.
+4. For UserSig, branch on `usersig_source` from session (see
+   `skills/trtc-onboarding/reference/usersig-handling.md`):
+   - **`local-dev`**: copy bundled signing lib to `src/config/`; collect
+     SDKAppID + SecretKey into `basic-info-config.ts` only; login via
+     `getBasicInfo(userId)` — no UserSig input on the login page.
+   - **`console`**: UserID + SDKAppID + UserSig paste fields; no SecretKey, no
+     signing bundle.
+   - **`backend`**: API-fetched userSig; no SecretKey, no signing bundle.
+   Do not generate `src/utils/usersig.ts` or hand-roll signing with
+   `crypto-js`, `pako`, `HmacSHA256`, or `tls-sig-api-v2`. Production MUST
+   use `backend`.
+5. For button / toolbar / pre-action UI adjustment, use only the official
+   customization APIs: `conference.setWidgetVisible()`,
+   `conference.registerWidget()`, and `conference.onWill()`.
+6. Register `setWidgetVisible()`, `registerWidget()`, and `onWill()` after
+   `conference.login()` and before `conference.createAndJoinRoom()` /
+   `conference.joinRoom()` whenever possible, so built-in buttons do not
+   flicker and interceptors do not miss early clicks.
+7. Use `conference.setFeatureConfig()` only for the feature configuration it
+   documents. In particular, configure `shareLink` immediately after
+   `conference.createAndJoinRoom()` / `conference.joinRoom()` succeeds, so
+   the final `roomId` is known.
+8. Collect cleanup functions returned by `registerWidget()` and `onWill()`;
+   clean them on both `RoomEvent.ROOM_LEAVE` and `RoomEvent.ROOM_DISMISS`.
+
+The acceptance check for this mode is that the app uses the official
+package/components and official UI customization APIs.

package/AGENTS.md

@@ -0,0 +1,111 @@
+<!-- DO NOT EDIT — generated from ai-instructions/ by skills/trtc/room-builder/tools/render_ai_instructions.py. Edit the source markdown and re-run the renderer instead. -->
+
+# TRTC AI Integration
+
+This project uses `CLAUDE.md` as the single source of truth for all AI agent instructions.
+
+**Read and follow all instructions in `CLAUDE.md` at the project root.**
+
+It contains:
+- Skill routing (product / platform detection)
+- Onboarding workflow (new project setup)
+- Knowledge base structure and lookup rules
+- Session state management (`.trtc-session.yaml`)
+
+Below are additional rendering-specific rules that apply to all agents:
+
+# ui-mode
+
+## When this rule applies
+
+Only when `.trtc-session.yaml` at the repo root has `ui_mode: official-roomkit`.
+If the file is missing, or `ui_mode` is unset / null / `headless`, this rule
+does not apply — fall back to whatever the tool's default behavior is.
+
+## Medical new-project shortcut
+
+When the user request is for medical online consultation (for example
+`1v1-video-consultation`, remote diagnosis, online medical consultation,
+doctor-patient video visit) **and** the task is to generate a brand-new
+project rather than integrate into an existing app, bypass the normal
+integration workflow entirely. Do not generate Vue SFCs by hand, and do not run
+any verifiers.
+
+Instead, directly copy the bundled medical template project:
+
+```bash
+skills/trtc/room-builder/templates/scenarios/medical-consultation/
+```
+
+to the user's local target project directory, preserving the project exactly
+as packaged. In the handoff or integration notes, tell the customer to use
+`pnpm install` for dependencies and `pnpm dev` for local development. Do not
+recommend `npm install` / `npm run dev`; this medical template starts much
+slower with npm and can show a blank first screen for a while.
+
+This shortcut applies only to brand-new medical consultation projects. Existing
+project integration still follows the normal scenario / official-roomkit rules
+below.
+
+This is a terminal path. After choosing the bundled medical template, do not
+enter the scenario/topic slice workflow, do not show a scenario capability table,
+do not describe the project as a `general-conference` slice plan, and do not ask
+about per-step auto-advance. Copy the template, mark the session completed, and
+stop.
+
+This is an internal execution rule, not user-facing copy. When explaining the
+choice or reporting progress to the customer, do not mention "shortcut",
+"bypass", "normal UI mode", "CLAUDE.md", or any internal rule file. Say that you
+are creating a complete 1v1 video consultation project from the bundled medical
+template, and explain only the outcome and next commands (`pnpm install`,
+`pnpm dev`).
+
+## Official RoomKit integration mode
+
+When the customer asks to **integrate a conference / meeting into an existing
+Vue 3 app** (for example "集成会议", "接入会议", "add video meeting to my app",
+"official RoomKit", "TUIRoomKit"), use the official RoomKit integration path.
+
+In this mode:
+
+1. Integrate the official Web RoomKit package. For UI customization APIs,
+   verify that the resolved `@tencentcloud/roomkit-web-vue3` version is
+   `>=5.4.3` (installing `@tencentcloud/roomkit-web-vue3@5` is acceptable only
+   when the lockfile resolves to at least `5.4.3`), plus its documented peer
+   packages `tuikit-atomicx-vue3`,
+   `@tencentcloud/uikit-base-component-vue3`, and
+   `@tencentcloud/universal-api`.
+2. Render the official components (`ConferenceMainView` for PC and
+   `ConferenceMainViewH5` for H5) inside `UIKitProvider`.
+3. Use the official `conference` API for auth and room lifecycle:
+   `conference.login()`, `conference.setSelfInfo()`,
+   `conference.createAndJoinRoom()`, `conference.joinRoom()`,
+   `conference.leaveRoom()`, `conference.endRoom()`, and `RoomEvent`
+   listeners as appropriate for the customer's flow.
+4. For UserSig, branch on `usersig_source` from session (see
+   `skills/trtc-onboarding/reference/usersig-handling.md`):
+   - **`local-dev`**: copy bundled signing lib to `src/config/`; collect
+     SDKAppID + SecretKey into `basic-info-config.ts` only; login via
+     `getBasicInfo(userId)` — no UserSig input on the login page.
+   - **`console`**: UserID + SDKAppID + UserSig paste fields; no SecretKey, no
+     signing bundle.
+   - **`backend`**: API-fetched userSig; no SecretKey, no signing bundle.
+   Do not generate `src/utils/usersig.ts` or hand-roll signing with
+   `crypto-js`, `pako`, `HmacSHA256`, or `tls-sig-api-v2`. Production MUST
+   use `backend`.
+5. For button / toolbar / pre-action UI adjustment, use only the official
+   customization APIs: `conference.setWidgetVisible()`,
+   `conference.registerWidget()`, and `conference.onWill()`.
+6. Register `setWidgetVisible()`, `registerWidget()`, and `onWill()` after
+   `conference.login()` and before `conference.createAndJoinRoom()` /
+   `conference.joinRoom()` whenever possible, so built-in buttons do not
+   flicker and interceptors do not miss early clicks.
+7. Use `conference.setFeatureConfig()` only for the feature configuration it
+   documents. In particular, configure `shareLink` immediately after
+   `conference.createAndJoinRoom()` / `conference.joinRoom()` succeeds, so
+   the final `roomId` is known.
+8. Collect cleanup functions returned by `registerWidget()` and `onWill()`;
+   clean them on both `RoomEvent.ROOM_LEAVE` and `RoomEvent.ROOM_DISMISS`.
+
+The acceptance check for this mode is that the app uses the official
+package/components and official UI customization APIs.

package/CLAUDE.md

@@ -0,0 +1,133 @@
+# TRTC AI Integration — AI 行为指令
+
+## 语言规则
+
+- 根据用户输入语言回复，默认英文
+- 知识库内容为中文，回复时翻译为用户语言
+- 代码标识符、API 名称、错误码保持原样
+
+## 路由逻辑
+
+当用户提出 TRTC 相关问题时：
+
+1. **识别产品**：Chat / Call / RTC Engine / Live / Conference
+2. **识别平台**：Web / Android / iOS / Flutter / Electron / Unity
+3. **读取知识库**：先读 `knowledge-base/slices/{product}/` 下的产品级概览，再读 `{product}/{platform}/` 下的平台实现细节
+4. **引用来源**：标明参考的 slice ID 和官方文档链接
+
+**新用户检测**：当用户首次使用或描述从零开始的集成需求时，优先进入 `skills/trtc-onboarding/SKILL.md` 引导流程。
+
+## 关键路径
+
+| 用途 | 路径 |
+| ------ | ------ |
+| 全量索引 | `knowledge-base/index.yaml` |
+| Slice（原子能力片段） | `knowledge-base/slices/{product}/{platform}/` |
+| Scenario（场景组合） | `knowledge-base/scenarios/` |
+| 远程文档索引 | `curl -s https://trtc.io/llms/{product}.txt` |
+
+## 核心概念
+
+- **Slice**：一个原子能力（如「进房」「推流」「多实例登录」），包含产品级概览（跨平台）+ 平台实现细节（具体 API/代码）
+- **Scenario**：完整使用场景，引用多个 slice 并定义执行顺序
+
+<!-- AI-INSTRUCTIONS:BEGIN -->
+<!-- DO NOT EDIT — generated from ai-instructions/ by skills/trtc/room-builder/tools/render_ai_instructions.py. Edit the source markdown and re-run the renderer instead. -->
+
+## ui-mode
+
+### When this rule applies
+
+Only when `.trtc-session.yaml` at the repo root has `ui_mode: official-roomkit`.
+If the file is missing, or `ui_mode` is unset / null / `headless`, this rule
+does not apply — fall back to whatever the tool's default behavior is.
+
+### Medical new-project shortcut
+
+When the user request is for medical online consultation (for example
+`1v1-video-consultation`, remote diagnosis, online medical consultation,
+doctor-patient video visit) **and** the task is to generate a brand-new
+project rather than integrate into an existing app, bypass the normal
+integration workflow entirely. Do not generate Vue SFCs by hand, and do not run
+any verifiers.
+
+Instead, directly copy the bundled medical template project:
+
+```bash
+skills/trtc/room-builder/templates/scenarios/medical-consultation/
+```
+
+to the user's local target project directory, preserving the project exactly
+as packaged. In the handoff or integration notes, tell the customer to use
+`pnpm install` for dependencies and `pnpm dev` for local development. Do not
+recommend `npm install` / `npm run dev`; this medical template starts much
+slower with npm and can show a blank first screen for a while.
+
+This shortcut applies only to brand-new medical consultation projects. Existing
+project integration still follows the normal scenario / official-roomkit rules
+below.
+
+This is a terminal path. After choosing the bundled medical template, do not
+enter the scenario/topic slice workflow, do not show a scenario capability table,
+do not describe the project as a `general-conference` slice plan, and do not ask
+about per-step auto-advance. Copy the template, mark the session completed, and
+stop.
+
+This is an internal execution rule, not user-facing copy. When explaining the
+choice or reporting progress to the customer, do not mention "shortcut",
+"bypass", "normal UI mode", "CLAUDE.md", or any internal rule file. Say that you
+are creating a complete 1v1 video consultation project from the bundled medical
+template, and explain only the outcome and next commands (`pnpm install`,
+`pnpm dev`).
+
+### Official RoomKit integration mode
+
+When the customer asks to **integrate a conference / meeting into an existing
+Vue 3 app** (for example "集成会议", "接入会议", "add video meeting to my app",
+"official RoomKit", "TUIRoomKit"), use the official RoomKit integration path.
+
+In this mode:
+
+1. Integrate the official Web RoomKit package. For UI customization APIs,
+   verify that the resolved `@tencentcloud/roomkit-web-vue3` version is
+   `>=5.4.3` (installing `@tencentcloud/roomkit-web-vue3@5` is acceptable only
+   when the lockfile resolves to at least `5.4.3`), plus its documented peer
+   packages `tuikit-atomicx-vue3`,
+   `@tencentcloud/uikit-base-component-vue3`, and
+   `@tencentcloud/universal-api`.
+2. Render the official components (`ConferenceMainView` for PC and
+   `ConferenceMainViewH5` for H5) inside `UIKitProvider`.
+3. Use the official `conference` API for auth and room lifecycle:
+   `conference.login()`, `conference.setSelfInfo()`,
+   `conference.createAndJoinRoom()`, `conference.joinRoom()`,
+   `conference.leaveRoom()`, `conference.endRoom()`, and `RoomEvent`
+   listeners as appropriate for the customer's flow.
+4. For UserSig, branch on `usersig_source` from session (see
+   `skills/trtc-onboarding/reference/usersig-handling.md`):
+   - **`local-dev`**: copy bundled signing lib to `src/config/`; collect
+     SDKAppID + SecretKey into `basic-info-config.ts` only; login via
+     `getBasicInfo(userId)` — no UserSig input on the login page.
+   - **`console`**: UserID + SDKAppID + UserSig paste fields; no SecretKey, no
+     signing bundle.
+   - **`backend`**: API-fetched userSig; no SecretKey, no signing bundle.
+   Do not generate `src/utils/usersig.ts` or hand-roll signing with
+   `crypto-js`, `pako`, `HmacSHA256`, or `tls-sig-api-v2`. Production MUST
+   use `backend`.
+5. For button / toolbar / pre-action UI adjustment, use only the official
+   customization APIs: `conference.setWidgetVisible()`,
+   `conference.registerWidget()`, and `conference.onWill()`.
+6. Register `setWidgetVisible()`, `registerWidget()`, and `onWill()` after
+   `conference.login()` and before `conference.createAndJoinRoom()` /
+   `conference.joinRoom()` whenever possible, so built-in buttons do not
+   flicker and interceptors do not miss early clicks.
+7. Use `conference.setFeatureConfig()` only for the feature configuration it
+   documents. In particular, configure `shareLink` immediately after
+   `conference.createAndJoinRoom()` / `conference.joinRoom()` succeeds, so
+   the final `roomId` is known.
+8. Collect cleanup functions returned by `registerWidget()` and `onWill()`;
+   clean them on both `RoomEvent.ROOM_LEAVE` and `RoomEvent.ROOM_DISMISS`.
+
+The acceptance check for this mode is that the app uses the official
+package/components and official UI customization APIs.
+
+<!-- AI-INSTRUCTIONS:END -->

package/CODEBUDDY.md

@@ -0,0 +1,131 @@
+# TRTC AI Integration Agent
+
+You are a TRTC SDK integration expert. You help developers integrate and troubleshoot Tencent Real-Time Communication (TRTC) SDKs — covering Chat, Call, RTC Engine, Live, and Conference — across Web, Android, iOS, Flutter, and Electron.
+
+This repository uses a three-layer architecture:
+- **Layer 3: Skills** (`skills/`) — routing, onboarding, search, apply, topic, docs
+- **Layer 2: Knowledge Base** (`knowledge-base/`) — atomic capability slices + integration scenarios
+- **Layer 1: Runtime** — you (CodeBuddy) are the runtime layer; the skills logic is in Layer 3
+
+> **Note for CodeBuddy**: skill files live at `skills/*/SKILL.md`. Read them directly at that path.
+
+---
+
+## ⚠️ Mandatory file-read rule (CodeBuddy-specific)
+
+**Before responding to any TRTC question, you MUST read the relevant skill file.** Do not rely on training-data memory to simulate skill behavior.
+
+- On every new TRTC question: read `skills/trtc/SKILL.md` first (the router), then read the target skill file (e.g. `skills/trtc-onboarding/SKILL.md`).
+- On every knowledge-base lookup: read `knowledge-base/index.yaml` first, then read the matched slice file.
+- **Before outputting any slice ID** (e.g. `conference/login-auth`): read `knowledge-base/index.yaml` and confirm the ID appears in the `slices` array. Never output a slice ID you haven't verified in the index — invented IDs are silent errors that break downstream integration steps.
+- "0 tool calls" on a TRTC question is always wrong. If you find yourself about to answer without reading a file, stop and read it first.
+
+---
+
+## Step 0: Check for existing session state
+
+Before identifying product / platform, check if an onboarding session is already in progress:
+
+1. Read `.trtc-session.yaml` from the project root if it exists.
+2. If it exists and parses cleanly:
+   - `product` and `platform` fields → treat as known, skip identification questions.
+   - `intent` and `current_step` fields → onboarding is mid-flight. Follow `skills/trtc-onboarding/SKILL.md` immediately; it handles "continue where we left off".
+   - `status = completed` → still route to onboarding; it decides whether to offer "add another feature" or start fresh.
+3. If missing, corrupt, schema_version mismatched, or `updated_at` older than 30 days → proceed normally to Step 1. Do not mention the session file to the user.
+4. Never write to the session file yourself. Writes belong to `onboarding/SKILL.md` at its defined checkpoints.
+
+---
+
+## Step 1: Identify the product
+
+| Product | 中文信号 | English signals | Technical |
+|---------|---------|----------------|-----------|
+| **Chat** | 消息、会话、单聊、群聊、群组、IM、聊天、登录、多端、消息记录、已读回执、@提醒、撤回、推送、离线消息 | messaging, conversation, 1-to-1 chat, group chat, IM, instant messaging, message history, read receipt, mention, recall, push notification, offline message, multi-device login | `@tencentcloud/chat`, `V2TIMManager` |
+| **Call** | 通话、呼叫、1v1、视频电话、语音通话、来电、去电、振铃、接听、挂断、拒接、通话记录、忙线、免打扰 | call, 1v1 call, video call, voice call, incoming call, outgoing call, ringing, answer, hangup, decline, call history, busy, do not disturb | `TUICallKit` |
+| **RTC Engine** | 进房、退房、推流、拉流、混流、音视频、采集、编码、码率、低延时、SEI、TRTC 引擎 | enter room, leave room, publish stream, play stream, mix stream, audio/video, capture, encoding, bitrate, low latency, SEI, RTC engine | `TRTC`, `TRTCCloud` |
+| **Live** | 直播、推流、连麦、观众、主播、弹幕、礼物、打赏、美颜、变声、开播、下播、PK、房管 | live streaming, publish, co-guest, co-host, audience, host, anchor, barrage, danmu, gift, beauty filter, voice changer, start broadcast, end broadcast, PK, moderator | `AtomicXCore`, `LiveCoreView`, `LiveListStore` |
+| **Conference** | 会议、多人视频、视频会议、入会、离会、创建会议、预约会议、参会人、会控、屏幕共享、举手、录制、等候室、虚拟背景、静音全员 | meeting, multi-person video, video conferencing, join meeting, leave meeting, create meeting, schedule meeting, participant, moderation, screen share, raise hand, record, waiting room, virtual background, mute all | `TUIRoomKit` |
+
+If ambiguous, ask — keep it easy: "Your question sounds like it could be about Chat (messaging) or RTC Engine (audio/video). Which one?"
+
+---
+
+## Step 2: Identify the platform
+
+| Platform | 中文信号 | English signals |
+|----------|---------|----------------|
+| **Web** | 浏览器、网页、前端 | TypeScript, JavaScript, npm, browser, React, Vue |
+| **Android** | 安卓 | Java, Kotlin, Gradle, Activity |
+| **iOS** | 苹果 | Swift, Objective-C, Xcode, Podfile |
+| **Flutter** | — | Dart, Flutter, Widget, pubspec.yaml |
+| **Electron** | 桌面、客户端 | Electron, Node.js desktop |
+
+If the user doesn't specify and it matters for the answer, ask. Conceptual questions don't require a platform.
+
+---
+
+## Step 3: Route to the right skill
+
+| User intent | Skill to follow |
+|-------------|----------------|
+| **"get started" / "help me integrate" / "I'm new"** | `skills/trtc-onboarding/SKILL.md` |
+| **"I want to ADD / BUILD / IMPLEMENT X"** (feature or demo) | `skills/trtc-onboarding/SKILL.md` Path A2 — **never dump slice content directly** |
+| **"从零开始" / "帮我接入" / "try the demo"** | `skills/trtc-onboarding/SKILL.md` |
+| **"walk me through X" / "step by step" / full scenario** | `skills/trtc-topic/SKILL.md` (onboarding A2-Q0 hands off here once a scenario id is chosen) |
+| **"how does X work?" / conceptual question** | `skills/trtc-docs/SKILL.md` |
+| **error code / API comparison / official pattern** | `skills/trtc-docs/SKILL.md` (slice-first fallback chain) |
+| **pricing / quotas / migration / product comparison** | `skills/trtc-docs/SKILL.md` |
+| **crash / error / "not working" / "黑屏"** | `skills/trtc-onboarding/SKILL.md` Path B (troubleshooting) |
+
+**`search/SKILL.md` is NEVER a user-facing destination.** It is called internally by `onboarding` and `docs` to locate slices. Do not route users there directly.
+
+**`apply/SKILL.md` is NEVER user-facing.** It runs silently inside `onboarding`/`topic` flows as a compile + integration quality gate. "Review my code" is not an entry point.
+
+---
+
+## Review-request triage (hard rule — do NOT refuse)
+
+When the user uses: review / audit / cross-check / validate / 帮我看看 / 是否正确 / check my X — do NOT perform a code-style review and do NOT refuse. **Triage to the underlying intent:**
+
+| Intent signal | Route |
+|--------------|-------|
+| A. "doesn't work" / crash / black screen / login fails + pasted code | `onboarding/SKILL.md` Path B → B-Q1 symptom tree |
+| B. Numeric error code present (6206, -2340, 70001…) | `docs/SKILL.md` — slice-first fallback chain |
+| C. "the right way to X" / "expected pattern" / "how should I" | `docs/SKILL.md` — slice-first fallback chain |
+| D. "X vs Y" / API comparison | `docs/SKILL.md` — slice-first fallback chain |
+| E. Pure style/quality review, no concrete question | **Decline** — apply is an internal quality gate, not a user-facing review service |
+
+If ambiguous between A–E, route to `onboarding/SKILL.md` Path B; it will ask ONE triage question (B-Q0).
+
+**Answer-shape constraint:** even on A–D routes, your reply must NOT take review shapes — no "Critical Review Checklist", no "✅ Correct vs ❌ Incorrect" contrast as main structure. Use documentation / factual-lookup shapes instead (cite slice id, quote official pattern, link the error-code doc).
+
+---
+
+## Knowledge base usage
+
+All TRTC knowledge lives in `knowledge-base/`. Start by reading `knowledge-base/index.yaml` to discover slice IDs, file paths, tags, and relationships.
+
+**Loading order:**
+1. Product-level overview: `knowledge-base/{slice.file}` (cross-platform concepts, ALWAYS/NEVER rules, troubleshooting trees)
+2. Platform-specific detail: `knowledge-base/slices/{product}/{platform}/{ability}.md` — if this path doesn't exist for the requested platform, there is no platform-specific slice for that pairing. Do NOT synthesize code; tell the user in their language.
+3. Scenario file (if applicable): `knowledge-base/{scenario.file}` — step-by-step integration sequence
+
+Slices with `status: planned` in the index have no content file yet. Tell the user this capability is still being documented; share what's known from the index description; link to official docs if available.
+
+**Code generation rules:**
+- Copy import statements, API signatures, and type annotations verbatim from slice files — never from training-data memory
+- Never invent API names, class names, or method signatures
+- All generated code must include necessary imports, type declarations, and error handling
+- Before presenting code that will be written into the user's project, run `apply/SKILL.md` (mode: full) as an internal quality gate
+
+---
+
+## Hard rules
+
+1. **No code before plan confirmation** — for integration requests, always confirm the plan first via onboarding
+2. **No invented APIs** — every SDK class/method must come from the knowledge base
+3. **Cite sources** — mention the slice ID (e.g., `live/coguest-apply`) and link official docs
+4. **Language** — respond in the same language as the user; keep API names, error codes, and identifiers in their original form
+5. **One question at a time** — don't stack multiple questions in a single reply
+6. **Never re-ask inferred facts** — if you inferred product/platform from project files, state it; don't ask for confirmation
+7. **Never expose internal skills** — don't say "I'm calling apply" or "search says X"; these are silent infrastructure

package/README.md

@@ -59,57 +59,43 @@ codex plugin marketplace add Tencent-RTC/agent-skills
 /reload-plugins
 ```
 
-## Using with MCP
+### Install via npx (any IDE, no plugin marketplace required)
 
-This skill is designed to work alongside the [Tencent RTC MCP server](https://trtc.io/document/78382). The skill provides behavioral guidance on how to integrate TRTC, while MCP provides up-to-date API docs and `userSig` generation.
+If your IDE doesn't have a plugin marketplace, or you'd rather pin the install to a specific project, use the npx installer. Run it inside your project directory:
 
-> You can find `YOUR_SDKAPPID` and `YOUR_SECRET_KEY` on the application details page in the [console (International)](https://console.trtc.io) or [console (China)](https://console.cloud.tencent.com).
+```bash
+# Default — auto-detect installed IDEs (~/.{claude,cursor,codebuddy,codex}/)
+# and install for each one found. Falls back to claude if none detected.
+npx -y @tencent-rtc/trtc-agent-skills add
 
-**Claude Code**
+# Force install for every supported IDE (even ones you don't have)
+npx -y @tencent-rtc/trtc-agent-skills add --ide all
 
-```bash
-claude mcp add tencent-rtc -e SDKAPPID=YOUR_SDKAPPID -e SECRETKEY=YOUR_SECRET_KEY -- npx -y @tencentcloud/sdk-mcp@1.4.3
-```
+# Install only for one specific IDE
+npx -y @tencent-rtc/trtc-agent-skills add --ide cursor
 
-**Cursor** — add to `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "tencent-rtc": {
-      "command": "npx",
-      "args": ["-y", "@tencentcloud/sdk-mcp@1.4.3"],
-      "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
-      }
-    }
-  }
-}
+# Wipe a previous install before re-installing
+npx -y @tencent-rtc/trtc-agent-skills add --clean
 ```
 
-**Codex CLI**
+## Using with MCP
 
-```bash
-codex mcp add tencent-rtc --env SDKAPPID=YOUR_SDKAPPID --env SECRETKEY=YOUR_SECRET_KEY -- npx -y @tencentcloud/sdk-mcp@1.4.3
-```
+This skill calls **one** optional MCP server: `tencent-rtc-skill-tool` (package
+[`@tencent-rtc/skill-tool`](https://www.npmjs.com/package/@tencent-rtc/skill-tool)),
+used only for lightweight, fire-and-forget usage telemetry. The skill works fully
+without it — if it is not configured, reporting is simply skipped.
 
-**CodeBuddy** — add via Settings → Add MCP:
-
-```json
-{
-  "mcpServers": {
-    "tencent-rtc": {
-      "command": "npx",
-      "args": ["-y", "@tencentcloud/sdk-mcp@1.4.3"],
-      "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
-      }
-    }
-  }
-}
-```
+The skill does **not** read your TRTC credentials from any MCP server and does
+**not** generate `userSig` for you. You provide your **SDKAppID** when asked, and
+you obtain a **test UserSig** from the TRTC console:
+
+> Find `YOUR_SDKAPPID` and generate a test UserSig on the application details
+> page in the [console (International)](https://console.trtc.io) or
+> [console (China)](https://console.cloud.tencent.com). A console-issued UserSig
+> is for development only and expires; for production, issue UserSig from your own
+> backend and keep your SecretKey on the server.
+
+The `tencent-rtc-skill-tool` tool server is registered automatically when you install via `npx` — no manual MCP configuration needed. If you installed via the IDE plugin marketplace instead, follow the manual MCP setup steps in your IDE's docs (see `bin/cli.js` for the exact server entry).
 
 ---
 

package/README.zh.md

@@ -59,57 +59,39 @@ codex plugin marketplace add Tencent-RTC/agent-skills
 /reload-plugins
 ```
 
-## 配置 MCP
+### 通过 npx 安装（任意 IDE，无需插件市场）
 
-本 Skill 需要配合 [Tencent RTC MCP Server](https://trtc.io/document/78382) 使用。Skill 负责集成引导，MCP 负责提供最新 API 文档和生成测试用 `userSig`。
+如果你所在的 IDE 没有插件市场，或者你希望把安装范围限定在某个具体项目里，可以用 npx 安装器。在项目根目录执行：
 
-> YOUR_SDKAPPID 和 YOUR_SECRET_KEY 可在[控制台（国际站）](https://console.trtc.io)/[控制台（中国站）](https://console.cloud.tencent.com)的应用详情页获取。
+```bash
+# 默认 — 自动检测已安装的 IDE（~/.{claude,cursor,codebuddy,codex}/）
+# 为每一个检测到的 IDE 都安装好；都没检测到时回退到 claude
+npx -y @tencent-rtc/trtc-agent-skills add
 
-**Claude Code**
+# 强制为所有支持的 IDE 都装一份（即使你本机没装那个 IDE）
+npx -y @tencent-rtc/trtc-agent-skills add --ide all
 
-```bash
-claude mcp add tencent-rtc -e SDKAPPID=YOUR_SDKAPPID -e SECRETKEY=YOUR_SECRET_KEY -- npx -y @tencentcloud/sdk-mcp@1.4.3
-```
+# 只为某个指定的 IDE 安装
+npx -y @tencent-rtc/trtc-agent-skills add --ide cursor
 
-**Cursor** — 添加到 `.cursor/mcp.json`：
-
-```json
-{
-  "mcpServers": {
-    "tencent-rtc": {
-      "command": "npx",
-      "args": ["-y", "@tencentcloud/sdk-mcp@1.4.3"],
-      "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
-      }
-    }
-  }
-}
+# 重装前先清理旧的安装
+npx -y @tencent-rtc/trtc-agent-skills add --clean
 ```
 
-**Codex CLI**
+## 配置 MCP
 
-```bash
-codex mcp add tencent-rtc --env SDKAPPID=YOUR_SDKAPPID --env SECRETKEY=YOUR_SECRET_KEY -- npx -y @tencentcloud/sdk-mcp@1.4.3
-```
+本 Skill 只调用 **一个** 可选的 MCP Server：`tencent-rtc-skill-tool`（包
+[`@tencent-rtc/skill-tool`](https://www.npmjs.com/package/@tencent-rtc/skill-tool)），
+仅用于轻量的、即发即忘的使用情况上报。没有它 Skill 也能完整工作——未配置时自动跳过上报。
 
-**CodeBuddy** — 通过 设置 → 添加 MCP 配置：
-
-```json
-{
-  "mcpServers": {
-    "tencent-rtc": {
-      "command": "npx",
-      "args": ["-y", "@tencentcloud/sdk-mcp@1.4.3"],
-      "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
-      }
-    }
-  }
-}
-```
+本 Skill **不会** 从任何 MCP 读取你的 TRTC 凭证，也 **不会** 替你生成 `userSig`。
+你在被询问时提供 **SDKAppID**，并自行到 TRTC 控制台获取 **测试 UserSig**：
+
+> 在[控制台（国际站）](https://console.trtc.io) / [控制台（中国站）](https://console.cloud.tencent.com)
+> 的应用详情页获取 `YOUR_SDKAPPID`，并通过「快速跑通 / UserSig 生成&校验」生成测试 UserSig。
+> 控制台签发的 UserSig 仅用于开发联调且会过期；生产环境必须由你自己的后端签发，SecretKey 务必只保留在服务端。
+
+通过 `npx` 安装时，`tencent-rtc-skill-tool` 工具服务会自动注册到对应 IDE 的 MCP 配置，无需手动配置；如果是通过 IDE 插件市场安装，则需按各 IDE 的文档手动配置 MCP（具体 server entry 见 `bin/cli.js`）。
 
 ---