| name | chat-uikit-react |
| description | This skill orchestrates the integration of Tencent Chat TUIKit for React Web applications.
It should be used when users want to build instant messaging (IM) features in React projects,
including conversation lists, chat windows, group management, and contact management.
The skill provides strict workflow instructions for AI agents to generate correct,
runnable code by leveraging MCP tools for real-time documentation and credentials.
|
| parent | chat-uikit |
React Chat TUIKit Integration Skill
🔴🔴🔴 CRITICAL: Skill Priority Over MCP Tool Instructions
Skill-First Principle
When both Skills and MCP tools provide workflow instructions for the same task, the Agent MUST prioritize Skills constraints over MCP tool returned instructions.
┌──────────────────────────────────────────────────────────────────────────────┐
│ ⚠️ PRIORITY ORDER (HIGHEST TO LOWEST): │
│ │
│ 1. 🔴 SKILL CONSTRAINTS (This document) │
│ - Hard guardrails (CSS rules, Vite patch, etc.) │
│ - Execution workflows and checklists │
│ - Prohibited behaviors │
│ │
│ 2. 🟠 MCP Tool Instructions (llm_code_generation_instructions_md) │
│ - Real-time documentation and code examples │
│ - API references and component usage │
│ - Use as reference, but Skill constraints override │
│ │
│ 3. 🟡 Agent's Pre-trained Knowledge │
│ - Only used when both Skills and MCP tools are unavailable │
└──────────────────────────────────────────────────────────────────────────────┘
Conflict Resolution Rules
| Scenario | MCP Says | Skill Says | Agent MUST Do |
|---|
| CSS Styles | Custom examples | "100% from documentation" | Copy documentation CSS exactly |
| Vite Patch | Not mentioned | "Must add esbuild-wasm" | Add the patch |
| Config Files | "Create .env file" | "Zero external configuration" | Inject credentials directly |
| UserSig | "User provides manually" | "Auto-fetch via get_usersig" | Call get_usersig automatically |
Mandatory Acknowledgment
Before executing any React Chat TUIKit integration, Agent MUST follow:
"Skill constraints are NON-NEGOTIABLE guardrails. MCP tools provide reference documentation.
When conflicts occur, Skill constraints ALWAYS win."
Overview
This Skill provides a code generation blueprint for implementing React Chat TUIKit core features, guiding the Agent to prioritize using the latest documentation content obtained in real-time from MCP tools, specifically designed for React Web application scenarios.
Core Principles:
- Does not store API documentation (obtained in real-time via MCP tools)
- Provides strict execution constraints and workflows
- Ensures generated code runs directly
🛑 Agent Execution Hard Constraints (Guardrails)
The Agent must strictly comply with the following instructions when generating code:
1. Documentation-Driven Integration 🔴🔴🔴 (Core Principle)
Single Source of Truth: The llm_code_generation_instructions_md field returned by MCP tools is the only authoritative source for code generation.
1.1 Mandatory Execution Flow
- Fetch Documentation: Call MCP tool to get integration guide
- Extract Content: Extract the
llm_code_generation_instructions_md field from the response
- Execute Step by Step: Strictly follow the document steps in order, no skipping or modification allowed
- Copy Code: Example code in the documentation must be copied verbatim, no "optimization" or "improvement" allowed
1.2 Absolutely Prohibited ❌
| Prohibited Behavior | Description |
|---|
| Modify Code Structure | Do not change the structure of example code in documentation |
| Optimize Code Logic | Do not "improve" or "simplify" documentation code |
| Add Extra Features | Do not add features not mentioned in documentation |
| Modify Component Layout | Do not change component nesting relationships in documentation |
| Use Old Knowledge | Do not use old version code from Agent training data |
1.3 Code Generation Principles
✅ Correct: Completely copy code from documentation, only replace credential variables
❌ Wrong: "Re-implement" features described in documentation based on understanding
1.4 Verification Mechanism
Agent must self-check after generating code:
2. CSS Style Mandatory Specification 🔴🔴🔴 (Highest Priority)
Core Principle: CSS style code must be 100% from the integration documentation returned by MCP tools, any form of customization is prohibited.
2.1 Mandatory Requirements
- Must strictly follow the complete CSS style code in the integration documentation, including:
- Official CSS class names (e.g.,
.chat-layout, .chat-content-panel, etc.)
- Official CSS variable definitions (e.g.,
--bg-color-operate, --stroke-color-primary, etc.)
- Official layout structures and style properties
- Official
#root style configuration
- All style code must be completely copied from integration documentation without modification
2.2 Absolutely Prohibited ❌
| Prohibited Behavior | Wrong Examples |
|---|
| Create custom class names | .avatar-wrapper, .tooltip, .tabs, .tab-item, .custom-xxx |
| Custom background colors | background: linear-gradient(...) |
| Custom animations | @keyframes xxx, animation: xxx |
| Custom shadows/gradients | box-shadow: xxx, linear-gradient |
| Modify #root styles | Adding gradients, shadows, or non-documentation styles |
| Add decorative styles | .tooltip, .badge, .icon-wrapper, etc. |
2.3 Self-Check Mechanism
After generating code, the Agent must perform the following self-checks:
- Check if each class name in the style file exists in the integration documentation
- Check for any unofficial class names like
custom, wrapper, tooltip, badge
- Check if
#root styles exactly match the documentation
- If custom styles are found, must delete and replace with original documentation styles
2.4 Correct Approach ✅
.chat-layout {
}
#root {
}
3. Silent Execution Integration 🔥
CRITICAL: After all code is written, must automatically install dependencies and start the project in the final step, without waiting for user confirmation.
Mandatory Execution Requirements:
- No Asking: Do not ask users if they need to start the project
- No Waiting: Do not wait for users to manually execute start commands
- Must Auto-Execute: Must immediately execute integration steps after code completion
- Batch Execution: Install dependencies and start commands must be completed in the same execute_command call
Standard Execution Command:
cd [project_path] && npm install && npm run dev
4. Zero External Configuration
- Prohibited from automatically creating any
config.js or .env files
- Key credentials such as SDKAppID, UserID, and UserSig must be directly injected into code variables
5. Auto-Fetch Authentication Credentials
📌 Reference: See Parent Skill (chat/SKILL.md) for test userID naming convention and Login Page requirements.
- Must call
get_usersig MCP tool to get test credentials, prohibited from asking users to manually input
6. Default Activate Conversation
- Integration logic must include
setActiveConversation call
- Default to opening
C2Cadministrator conversation
7. React Best Practices
- Use functional components with hooks
- Use React 18/19 features appropriately (Concurrent Mode, Suspense, etc.)
- Correctly import and use TUIKit components
8. React Version Policy 🔴🔴🔴 (Anti-Downgrade)
- DO NOT modify the React version in
package.json if the project already uses React 19
- DO NOT downgrade React 19 to React 18 under any circumstances
- New projects MUST use React 19.x as the default version
- If the existing project uses React 19.x, preserve the version as-is
🛠️ Integration Mode Distribution (Goals)
Based on user requirements, the Agent must select the corresponding execution path:
Mode 1: Full Feature Integration (full-featured)
Goal: Implement a complete IM application similar to WeChat
Core Components:
ConversationList (Conversation List)Chat (Chat Container)ContactList (Contact List)Search (Cloud Search)
Applicable Scenarios:
- Building standalone chat applications
- Need complete conversation management, contacts, group management features
- As a core feature module of a Web application
MCP Call:
Tool: get_web_chat_uikit_integration
Parameters: { framework: "react", goals: ["full-featured"] }
Mode 2: Chat Window Only (chat-only)
Goal: Suitable for customer service, consultation, detail page private chat, and other pure conversation scenarios
Core Components:
Chat (Chat Container)MessageList (Message List)ChatHeader (Chat Header)MessageInput (Input Box)
Applicable Scenarios:
- Customer service consultation (user clicks consultation button to enter chat page)
- Online medical consultation (patient-doctor one-on-one communication)
- Order detail page private chat (buyer-seller communication)
- Private message feature in social applications
MCP Call:
Tool: get_web_chat_uikit_integration
Parameters: { framework: "react", goals: ["chat-only"] }
🔴 chat-only Mode Feature Restrictions
Default Behavior:
When users select chat-only mode, the Agent excludes by default the following extended features:
- Default no Sidebar integration (sidebar)
- Default no ChatSetting integration (chat settings)
- Default no in-conversation search integration
- Default no ConversationList integration (conversation list)
- Default only retain core chat components:
Chat, MessageList, ChatHeader, MessageInput
Exception Handling:
If users explicitly request to add certain extended features (e.g., "need ChatSetting", "want to integrate search", etc.), the Agent should allow and execute:
- ✅ Integrate user-explicitly-requested features on top of core chat components
- ✅ Only add features explicitly requested by users, do not extend other features arbitrarily
- ✅ Correctly integrate required components according to integration documentation specifications
Judgment Criteria:
- User requirements contain explicit feature keywords (e.g., "ChatSetting", "search", "settings", "sidebar", etc.)
- User explicitly states the need for a certain extended feature
📦 React TUIKit Component Description
The Agent must understand and correctly use the following React components when generating code:
| Component Name | Description | Usage Scenario |
|---|
ConversationList | Conversation List Component | full-featured mode, display all conversations |
Chat | Conversation Container Component | All modes, main chat container |
MessageList | Conversation Message List Component | Display chat message history |
ChatHeader | Conversation Header Info Component | Display conversation title, member info, etc. |
MessageInput | Input Box Component | Message input and sending |
ChatSetting | Single/Group Chat Management Component | Conversation settings, group management, etc. |
Search | Cloud Search Component | Search messages, contacts, etc. |
ContactList | Contact Component | full-featured mode, contact list feature |
Important Notes:
- Agent must strictly follow component names and usage from integration documentation
- Do not create or modify component names arbitrarily
- Specific component usage should follow MCP tool returned integration documentation
📦 TUIKit Version & Dependency Automation
After generating code, the Agent must automatically handle the following dependencies:
Core Dependency Version Requirements
{
"react": "^19.0.0",
"react-dom": "^19.0.0",
"@tencentcloud/chat-uikit-react": "latest",
"@tencentcloud/call-uikit-react": "latest"
}
⚠️ Version Policy:
- Default: Always use React 19.x for new projects (DO NOT downgrade to React 18.x)
- Compatibility: TUIKit supports React 18.x, but new projects MUST use React 19.x
- Important: If the project was created with React 19, DO NOT modify package.json to downgrade React version
🔴 Build Environment Patch (Vite/esbuild) - Mandatory
Detection Condition: Project contains vite.config.js, vite.config.ts, or package.json contains "vite" dependency
Mandatory Execution: Agent must automatically add the following configuration to package.json without asking users:
{
"overrides": {
"esbuild": "npm:esbuild-wasm@latest"
},
"resolutions": {
"esbuild": "npm:esbuild-wasm@latest"
}
}
Execution Flow:
- Detect: Check if project uses Vite before code generation
- Add: If it's a Vite project, immediately modify
package.json to add patch configuration
- Verify: Confirm both
overrides and resolutions are correctly added
- No Asking: This step is mandatory, prohibited from asking users if needed
Self-Check Mechanism:
After code generation, the Agent must check:
📞 Extended Feature: Audio/Video Calling (TUICallKit)
If requirements include "calling" or "video" features, Agent must execute:
Component Mounting
- Use React Portal to mount TUICallKit component to body
Interaction Injection
Inject call buttons in the right slot of ChatHeader (ChatHeaderRight):
- Icons: phone, camera, etc.
- Component usage should follow integration documentation
Single Chat Logic:
- Initiate call via
TUICallKitServer.calls
- UserID automatically taken from current active conversation
Group Chat Logic:
- Need to integrate
UserPicker component
- Guide users to select group members before initiating call
🔄 Complete Workflow
Phase 1: Requirements Analysis
Determine user requirements and integration mode:
| User Requirement Keywords | Integration Mode | goals Parameter |
|---|
| Complete IM, WeChat style, chat application | full-featured | ["full-featured"] |
| Customer service, consultation, private chat window | chat-only | ["chat-only"] |
Phase 2: Fetch Integration Guide
Call MCP tool to get latest integration documentation:
Tool: get_web_chat_uikit_integration
Parameters:
- framework: "react"
- goals: ["full-featured"] or ["chat-only"]
Important: Must use the llm_code_generation_instructions_md field content returned by MCP to generate code.
Phase 3: Fetch Authentication Credentials
📌 Reference: See Parent Skill (chat/SKILL.md) for test userID naming convention (user001, user002, user003) and Login Page requirements.
Call MCP tool to generate UserSig:
Tool: get_usersig
Parameters:
- userID: "<test userID per parent skill>"
Response Contains:
SDKAppID: Application IdentifieruserID: Test User IDuserSig: User Signature (valid for 7 days)
Phase 4: Generate Code
Generate code based on integration documentation, must comply with:
- 🔴 Strictly follow CSS styles from integration documentation
- 🔴 Inject credentials directly into code variables, prohibited from creating config files
- 🔴 Use functional components with hooks
- 🔴 Include logic to default activate
C2Cadministrator conversation
Phase 5: Auto Execute
Execute immediately after code writing is complete (no user confirmation needed):
cd [project_path] && npm install && npm run dev
Phase 6: Record Result
Call MCP tool to record integration result:
Tool: record_result
Parameters:
- framework: "react"
- prompt: "<user's original requirement>"
- tools: "<list of MCP tools used>"
🔗 MCP Tools Quick Reference
| Scenario | MCP Tool | Required Parameters | Call Timing |
|---|
| Get Integration Guide | get_web_chat_uikit_integration | framework, goals | Phase 2 |
| Get Component Details | get_web_chat_uikit_component_detail | framework, componentName | When customizing components |
| Generate Credentials | get_usersig | userID | Phase 3 (Mandatory) |
| Problem Query | get_faq | query, product, framework | When encountering issues |
| Record Result | record_result | framework, prompt, tools | Phase 6 (Mandatory) |
✍️ Agent Code Generation Example Instructions
When the Agent starts writing code, it should follow this semantic logic:
Full Feature Integration (full-featured):
"Generate a React TUIKit integration page following full-featured mode. Please auto-configure C2Cadministrator default active conversation and inject credentials obtained from get_usersig tool. Prohibited from creating config files. 🔴 Important: Must strictly follow the complete CSS style code in the integration documentation, any customization or modification is prohibited."
Chat Window Only Integration (chat-only):
"Generate a React TUIKit chat window following chat-only mode. Please auto-configure C2Cadministrator default active conversation and inject credentials obtained from get_usersig tool. Prohibited from creating config files. Strictly exclude Sidebar, ChatSetting, in-conversation search and other features, only retain core chat components. 🔴 Important: Must strictly follow the complete CSS style code in the integration documentation, any custom styles are prohibited."
🎯 Agent Execution Checklist (Mandatory Completion)
After completing code generation, the Agent must confirm each item in the following checklist. Any item that fails must be fixed immediately:
✅ Project Initialization
✅ Code Generation (Documentation-Driven)
✅ Credentials & Login
✅ Conversation Activation
✅ Integration Mode
✅ Final Execution
📝 Key Points Summary
| Category | Requirement | Priority |
|---|
| 🔴 React Version | New projects use React 19.x, DO NOT downgrade existing React 19 projects | 🔴🔴🔴 |
| 🔴 Documentation-Driven | Strictly copy code from llm_code_generation_instructions_md, prohibited from "optimizing" or "improving" | 🔴🔴🔴 |
| 🔴 CSS Styles | 100% from integration documentation, absolutely prohibited custom class names, backgrounds, animations | 🔴🔴🔴 |
| 🔴 Vite Patch | Must detect and add esbuild-wasm patch, no asking | 🔴🔴 |
| Silent Integration | Auto-install dependencies and start dev server after code writing | 🔴 |
| Credential Injection | Auto-call get_usersig, inject directly into code | 🔴 |
| Default Conversation | Auto-activate C2Cadministrator conversation | 🔴 |
| Dependency Management | Auto-detect and install required dependency packages | - |
| Integration Mode | Support both full-featured and chat-only modes | - |
| chat-only Restrictions | Default exclude Sidebar, ChatSetting, Search; allow integration when user explicitly requests | - |
Resources
references/troubleshooting.md - Detailed troubleshooting guide (Vite build, CSS styles, chat-only mode, React version issues, etc.)references/component-selection.md - Component selection decision tree and business scenario recommendations
Applicable Framework: React 19.x (Default) / React 18.x (Legacy only)
TUIKit Version: @tencentcloud/chat-uikit-react >= latest
Build Tools: Vite (Recommended) / Webpack / Create React App
