Use this skill when a browser/Web app (React, Vue, Next, Nuxt, static sites, SPAs, dashboards, AI chat UI, 页面, 前端, 网页) needs AI models via @cloudbase/js-sdk. Default routing for Web/frontend AI — call
1---2name: ai-model-web3description: Use this skill when a browser/Web app (React, Vue, Next, Nuxt, static sites, SPAs, dashboards, AI chat UI, 页面…4---56# config/.claude/skills/ai-model-web/SKILL.md
A
SKILL.mdAgent skill
Transport
File
Status
Listed
SKILL.md
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill ai-model-web -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
Use this skill when a browser/Web app (React, Vue, Next, Nuxt, static sites, SPAs, dashboards, AI chat UI, 页面, 前端, 网页) needs AI models via @cloudbase/js-sdk. Default routing for Web/frontend AI — call directly from the browser, do NOT propose a Node.js proxy. Covers generateText and streamText; models via ai.createModel with groups cloudbase, the legacy hunyuan-v3 / hunyuan-exp, or custom-*, model id in the `model` field. MUST run two-step preflight before code — see body. NOT for Node.js backend (use ai-model-nodejs), Mini Program (use ai-model-wechat), or image generation (Node SDK only).
Download config/.claude/skills/ai-model-web/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does ai-model-web live?
The publisher keeps it at https://github.com/TencentCloudBase/CloudBase-AI-Toolkit.
Which agents can use ai-model-web?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
ai-model-web
description
Use this skill when a browser/Web app (React, Vue, Next, Nuxt, static sites, SPAs, dashboards, AI chat UI, 页面, 前端, 网页) needs AI models via @cloudbase/js-sdk. Default routing for Web/frontend AI — call directly from the browser, do NOT propose a Node.js proxy. Covers generateText and streamText; models via ai.createModel with groups cloudbase, the legacy hunyuan-v3 / hunyuan-exp, or custom-*, model id in the `model` field. MUST run two-step preflight before code — see body. NOT for Node.js backend (use ai-model-nodejs), Mini Program (use ai-model-wechat), or image generation (Node SDK only).
version
2.37.6
license
MIT
alwaysApply
false
Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
When to use this skill
Use this skill for calling AI models in browser/Web applications via @cloudbase/js-sdk.
🧭 Runtime-plane default for Web. Any time the user's request is framed around a page, a Web app, the frontend, React/Vue/Next/Nuxt, a dashboard UI, or "add AI to my H5", this skill is the default routing target. Do NOT first propose a Node.js / cloud-function / CloudRun proxy; @cloudbase/js-sdk can call the model from the browser directly. Only switch to ai-model-nodejs if the user explicitly asks for a backend/server call, image generation, or a scenario that truly needs server-side keys or long-running work. This decision is independent of which concrete model the user picks — model names (deepseek-*, glm-*, hunyuan-*, kimi-*, …) only affect the model field, not the routing plane.
Use it when you need to:
Integrate AI text generation into a frontend Web app
Stream AI responses for a better UX
Call Hunyuan / DeepSeek / GLM / Kimi / MiniMax models from the browser
Do NOT use for:
Node.js backend or cloud functions → use the ai-model-nodejs skill
WeChat Mini Program → use the ai-model-wechat skill
Image generation → use the ai-model-nodejs skill (Node SDK only)
Runtimes without a CloudBase SDK (native apps, Python, Go, etc.) → use the http-api-cloudbase skill (it now includes the ai_model OpenAPI spec for direct HTTP calls; do NOT build a custom HTTP proxy)
⛔ STOP — ai.createModel(...) argument is not a vendor / model name
Read this before writing any line. The single most common mistake when agents generate code for this SDK is hallucinating the argument. There are legal shapes. Anything else is a bug.
createModel(...)
exactly four
✅ Legal ai.createModel(...) argument
When to use it
"cloudbase"
The main managed group for new projects (TokenHub-backed, multi-vendor pool). Vendor + concrete model go into the model field of generateText / streamText, e.g. { model: "deepseek-v4.1-flash" }. No model is enabled by default — always check DescribeAIModels first and, if the target model is missing, enable it with UpdateAIModel before calling the SDK.
"hunyuan-v3"
Legacy plan group, being retired. Only hy3 is available and the platform adds no new models to it. Existing code keeps working — new code should use cloudbase + { model: "hy3" }.
"hunyuan-exp"
Only if DescribeAIModels explicitly returns this older legacy builtin group for the current env. Its original default model hunyuan-2.0-instruct-20251111 is offline (2026-05-31) — never target that id.
"custom-<your-name>"
A user-defined GroupName you onboarded via CreateAIModel. Must start with custom- (e.g. custom-kimi, custom-openai-compat).
❌ Do NOT write any of these — they are all wrong
ai.createModel("deepseek") // wrong — that's a vendor, not a GroupName
ai.createModel("deepseek-v4.1-flash") // wrong — that's a model name, goes in the `model` field
ai.createModel("hunyuan") // wrong — vendor family, not a GroupName
ai.createModel("hunyuan-2.0-instruct-20251111") // wrong — model name
ai.createModel("glm") / ai.createModel("kimi") / ai.createModel("minimax") // wrong — vendor names
ai.createModel("openai") / ai.createModel("moonshot") // wrong — vendor names
ai.createModel("custom") // wrong — placeholder; use your real custom-<name>
ai.createModel(modelName) // wrong — do not reuse the variable that holds the model id
✅ Correct pattern — GroupName vs Model are two different fields
const model = ai.createModel("cloudbase"); // ← GroupName
await model.generateText({
model: "deepseek-v4.1-flash", // ← concrete model id
messages: [...]
});
Decision procedure (when the user names a specific model)
The user says "use DeepSeek v3.2" / "use hunyuan instruct" / "use Kimi k2.6" / "use GLM-5" / …
createModel("cloudbase") stays the same.
Put the model id into the model field: { model: "deepseek-v4.1-flash" }, { model: "hy3" }, { model: "kimi-k2.6" }, { model: "glm-5.3" }, …
Never assume the model is already enabled. Before writing the SDK call, verify it is present in DescribeAIModels({ GroupName: "cloudbase" }).Models[]. If missing, call DescribeManagedAIModelList to confirm the exact Model name the platform supports (case-sensitive — do not guess the spelling), then enable it via UpdateAIModel with Status: 1 (remember Models is a full replacement, so resend everything already enabled + the new one).
If you are about to type ai.createModel( and the thing inside the parentheses is a vendor name, a model name, or a guess — stop. It is almost certainly one of the four legal values above.
Mandatory Two-Step Preflight (before any SDK code)
Before generating any AI-related SDK code, run the two-step preflight: ① eligibility, ② group readiness. Emitting createModel(...) straight away and letting the user debug runtime errors is significantly more costly.
Step 0: obtain the environment ID
Call the MCP tool queryEnv with action=info and read EnvId from the response. Every subsequent check and purchase link uses this EnvId.
Preflight ① — Eligibility (Token Credits resource pack)
envPostpayPackageInfoList contains at least one entry
That entry's postpayPackageId starts with pkg_tcb_tokencredits_
That entry's status is NOT in [3, 4] (3 / 4 typically mean expired / disabled; trust the live response)
❌ Not satisfied → stop writing code and surface this to the user (replace {region} with the environment's Region from queryEnv, e.g. ap-shanghai, and {envId} with the real id):
Let me know once it's done and I'll re-check the resource pack status.
✅ Satisfied → proceed to preflight ②.
Parameter casing is PascalCase by contract. If the call returns InvalidParameter, fall back to camelCase (envId / envPostpayPackageInfoList) and trust the live response. For the Mini Program scenario there is an additional growth-plan branch — switch to the ai-model-wechat skill.
Preflight ② — Group readiness (DescribeAIModels → UpdateAIModel if needed)
Eligibility alone is not enough. Do not write createModel("cloudbase") yet. First confirm that the target GroupName exists in the env with Status=1, and that the target Model is present in its Models[].
Returns AIModelGroups: AIModelGroup[], where each AIModelGroup includes GroupName, Type (builtin / custom), Models: [{ Model, EnableMCP, Tags }], Status (1 = on / 2 = off), BaseUrl, Secret, Remark. The main managed GroupName is cloudbase.
Never assume a model is already enabled. Inspect AIModelGroups[?].Models[].Model for the cloudbase group. If the target model (or, when the user did not specify one, the model you intend to default to such as deepseek-v4.1-flash) is missing, jump to step 4 and enable it — do not call createModel("cloudbase") yet. If the cloudbase group itself is missing or has Status=2, also jump to step 4.
User asked for a model that belongs to the managed catalog (e.g. deepseek-v4.1-flash, hy3, glm-5.3, kimi-k2.6, …): check whether that Model is already in the cloudbase group's Models[]. If not, jump to step 4. Do not guess the exact model id — verify the canonical spelling in DescribeManagedAIModelList first (step 4 covers this).
Enable / add a managed model (always inspect the authoritative catalog + pricing first):
Returns ManagedAIModelGroup[], where each group lists GroupName (e.g. cloudbase), Remark, and Models: [{ Model, EnableMCP, ModelSpec{ContextLength, MaxInputToken, MaxOutputToken}, ModelChargingInfo[{Type, InputPrice, OutputPrice, InputOutputUnit, CachePrice}] }]. This is the single source of truth for supported model names and pricing — do not infer them from memory. Use the exact Model string returned here when calling UpdateAIModel. Also surface the prices to the user before enabling.
Then enable (note: Models is a full replacement — always resend the already-enabled models together with the new one):
callCloudApi(service="tcb", action="UpdateAIModel", params={
EnvId,
GroupName: "cloudbase",
Models: [
// resend every model that DescribeAIModels already showed as enabled
{ Model: "<already-enabled model, e.g. deepseek-v4.1-flash>" },
// append the newly-requested one, using the exact spelling from DescribeManagedAIModelList
{ Model: "<target model>" }
],
Status: 1
})
The requested model is not in the managed catalog (not found by DescribeManagedAIModelList) → jump to the next section, Custom onboarding (models outside the managed catalog).
All Actions use service=tcb, Version=2018-06-08. Parameters are PascalCase (EnvId / GroupName / Models / Status). Fall back to camelCase only if the call returns InvalidParameter.
Available Providers and Models
ai.createModel(<GroupName>) accepts exactly four kinds of legal values:
1. "cloudbase" — the main managed group (recommended)
Backed by Tencent Cloud TokenHub, a unified managed pool covering multiple vendors — Hunyuan (HY 2.0 Instruct, HY 2.0 Think, Hunyuan-role, Hy3 preview, …), DeepSeek (DeepSeek-V4-Pro, DeepSeek-V4-Flash, Deepseek-v3.2, Deepseek-v3.1, Deepseek-r1-0528, Deepseek-v3-0324, …), Zhipu GLM (GLM-5, GLM-5-Turbo, GLM-5.1, GLM-5V-Turbo), Kimi (K2.5, K2.6), MiniMax (M2.5, M2.7), and more. The roster evolves — do not hard-code specific SKUs in application code; discover at runtime.
No model is enabled by default. Always call DescribeAIModels first to see what the env has actually enabled; if your target model is missing, call DescribeManagedAIModelList for the authoritative catalog + pricing and then UpdateAIModel (Status: 1, Models full-replacement) to enable it before making the SDK call.
2. "hunyuan-v3" — legacy plan group (being retired)
Only hy3; the group gets no new models and is on its way out. Migration target is cloudbase + { model: "hy3" }
Still legal for existing code — do not "fix" createModel("hunyuan-v3") into createModel("hy3"); hy3 is a model id, not a GroupName
Mainly matters for Mini Program Growth Plan environments (see ai-model-wechat)
3. "hunyuan-exp" — older legacy builtin group (kept for compatibility)
Do not use it from Web unless the env explicitly still returns it (switch to the ai-model-wechat skill for that flow)
Its original default hunyuan-2.0-instruct-20251111 went offline on 2026-05-31 — never target that model id. Whatever models the group still exposes must be read from DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]
4. User-defined GroupName
Onboarded via CreateAIModel (see the next section). The custom GroupNameMUST start with custom- (e.g. custom-kimi, custom-moonshot, custom-openai-compat). This naming convention prevents future collisions with built-in / vendor GroupNames (cloudbase, hunyuan-exp, deepseek, glm, kimi, minimax, …) that the platform may introduce over time
Never write guesses like createModel("deepseek") or createModel("custom") unless DescribeAIModels explicitly returned that exact GroupName (old envs may still carry historical deepseek / hunyuan-exp builtin groups — that stays legal for compatibility, but new projects should always go through cloudbase).
Custom onboarding (models outside the managed catalog)
When the user wants to call a non-managed model (self-hosted, enterprise-internal, third-party OpenAI-compatible endpoint, …), do not block. Guide them through onboarding:
Option 1: console flow (recommended, user handles it)
callCloudApi(service="tcb", action="CreateAIModel", params={
EnvId: "<envId>",
GroupName: "custom-<your-name>", // MUST start with "custom-" (e.g. custom-kimi, custom-openai-compat); never start with "cloudbase"
BaseUrl: "<OpenAI-compatible endpoint, e.g. https://api.moonshot.cn/v1>",
Models: [
{ Model: "<model name, e.g. kimi-k2.5>", EnableMCP: true }
],
Remark: "<optional remark>",
Status: 1,
Secret: { ApiKey: "<vendor api key supplied by the user>" }
})
Once onboarded, confirm with DescribeAIModels that the group is ready, then call ai.createModel("<the GroupName you just registered>") from your code. Use UpdateAIModel to add/remove models, rotate keys, or change BaseUrl (remember Models is a full replacement). Use DeleteAIModel to remove a custom group (builtin groups cannot be deleted).
Custom-model billing is covered by the third-party provider and does not draw from the Token Credits resource pack. Field casing follows the live contract — fall back to camelCase on InvalidParameter.
Installation
npm install @cloudbase/js-sdk
Initialization
⚠️ Do not use anonymous sign-in as the default. Anonymous login is disabled by default for new environments, and inactive existing environments have also been automatically disabled. Even when anonymous login is manually enabled, anonymous users are denied AI model invocation permissions by default. The AI-model skill does not prescribe a specific login UI — delegate that concern:
Enabling / configuring login providers (phone SMS, email, WeChat Open Platform, username+password, OAuth, …) → follow the auth-tool-cloudbase skill (backend config via callCloudApi).
Building the actual sign-in flow in the browser (login form, callbacks, session guarding) → follow the auth-web-cloudbase skill (@cloudbase/js-sdk auth API, e.g. signInWithPassword, signInWithPhone, getSession).
Do not fall back to signInAnonymously() for AI features — anonymous users cannot call AI models. Only use anonymous login for non-AI read-only demos where the user explicitly requests it and accepts the trade-off.
import cloudbase from "@cloudbase/js-sdk";
const app = cloudbase.init({
env: "<YOUR_ENV_ID>",
accessKey: import.meta.env.VITE_PUBLISHABLE_KEY // auto-provision via queryAppAuth / manageAppAuth, write to .env.local (see auth-web-cloudbase prerequisites)
});
const auth = app.auth;
// CRITICAL: Use auth.getSession() to check login — NOT the deprecated getLoginState().
// getLoginState() returns uid even without real login (just accessKey), causing false positives.
// getSession() returns data.session === undefined when no real login exists.
// Anonymous users are DENIED AI model permissions — calling AI without real login will fail.
const { data: sessionData } = await auth.getSession();
if (!sessionData?.session || sessionData.session.user?.is_anonymous) {
// No real login or anonymous session — route to sign-in page
window.location.href = "/login";
return;
}
const ai = app.ai();
Important notes:
Use synchronous initialization with a top-level import
accessKey causes getLoginState() to return misleading auth data — the deprecated getLoginState() returns an object with uid even without real login, which breaks naive !!loginState checks. Use auth.getSession() instead: it returns data.session === undefined when no real login exists, so !!data.session is a reliable auth gate.
The user MUST be authenticated with a verified login (phone, email, WeChat, username+password, custom) before using AI features. Anonymous users are denied AI model permissions. The exact flow is the responsibility of the auth-web-cloudbase skill.
Get accessKey from the CloudBase console
generateText() — non-streaming
Prerequisite: the two-step preflight (eligibility + group readiness) has passed, and the target model has been confirmed present in DescribeAIModels({ GroupName: "cloudbase" }).Models[] — if it was not, it should already have been enabled via UpdateAIModel. The example below uses deepseek-v4.1-flash only for illustration; substitute the actual model the user asked for.
const model = ai.createModel("cloudbase");
const result = await model.generateText({
model: "deepseek-v4.1-flash", // must already be enabled in this env (DescribeAIModels → UpdateAIModel)
messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],
});
console.log(result.text); // generated text string
console.log(result.usage); // { prompt_tokens, completion_tokens, total_tokens }
console.log(result.messages); // full message history
console.log(result.rawResponses); // raw model responses
streamText() — streaming
Prerequisite: the two-step preflight has passed.
const model = ai.createModel("cloudbase");
const res = await model.streamText({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "Give me a one-paragraph intro to Li Bai." }],
});
// Option 1: iterate the text stream (recommended)
for await (let text of res.textStream) {
console.log(text); // incremental text chunks
}
// Option 2: iterate the data stream for full response chunks
for await (let data of res.dataStream) {
console.log(data); // full response chunk with metadata
}
// Option 3: access final results
const messages = await res.messages; // full message history
const usage = await res.usage; // token usage
Error Handling Pattern
const model = ai.createModel("cloudbase");
try {
const result = await model.generateText({
model: "deepseek-v4.1-flash",
messages: [{ role: "user", content: "Generate a concise onboarding checklist." }],
});
console.log(result.text);
} catch (error) {
console.error("Failed to call CloudBase AI from Web", error);
}
Type Definitions
interface BaseChatModelInput {
model: string; // required: model name
messages: Array<ChatModelMessage>; // required: message array
temperature?: number; // optional: sampling temperature
topP?: number; // optional: nucleus sampling
}
type ChatModelMessage =
| { role: "user"; content: string }
| { role: "system"; content: string }
| { role: "assistant"; content: string };
interface GenerateTextResult {
text: string; // generated text
messages: Array<ChatModelMessage>; // full message history
usage: Usage; // token usage
rawResponses: Array<unknown>; // raw model responses
error?: unknown; // error if any
}
interface StreamTextResult {
textStream: AsyncIterable<string>; // incremental text stream
dataStream: AsyncIterable<DataChunk>; // full data stream
messages: Promise<ChatModelMessage[]>;// final message history
usage: Promise<Usage>; // final token usage
error?: unknown; // error if any
}
interface Usage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
}
Best Practices
Run the two-step preflight first — ① eligibility (Token Credits resource pack via DescribeEnvPostpayPackage) + ② group readiness (DescribeAIModels to inspect what is enabled, DescribeManagedAIModelList for the authoritative supported-model catalog, UpdateAIModel with a full-replacement Models[] and Status: 1 when the target model is missing). Skipping preflight leads straight to "model not found" / "model not enabled" errors at runtime.
Never assume any model is already enabled — not deepseek-v4.1-flash, not hunyuan-*, not anything. Always verify with DescribeAIModels first; if the target is missing, look up the exact Model string in DescribeManagedAIModelList (do not guess the spelling or invent vendor prefixes) and then UpdateAIModel to enable it.
createModel accepts exactly four kinds of values — "cloudbase" (the main managed group), "hunyuan-v3" (legacy plan group, only hy3, being retired), "hunyuan-exp" (older legacy builtin), or a user-defined GroupName registered via CreateAIModel (MUST start with custom-, e.g. custom-kimi, custom-openai-compat). Never guess with createModel("deepseek") / createModel("kimi") / createModel("custom").
Do not invent SDK method names or parameters. This SKILL.md is the authoritative reference for @cloudbase/js-sdk's AI surface — look up the method signature here (or in the Type Definitions section below) before writing code. If a method or field is not documented here, stop and ask, or check the live contract via the MCP tools. No guessing.
Show pricing before enabling a new managed model — DescribeManagedAIModelList returns ModelSpec (context length, max input/output tokens) + ModelChargingInfo (input / output / cache prices, billing unit). Surface the prices to the user before calling UpdateAIModel.
Use streaming for long responses — better perceived latency and interactivity.
Handle errors gracefully — wrap AI calls in try/catch.
Keep accessKey safe — use a publishable key, never a secret key.
Initialize early — set up the SDK at app entry so auth and AI are both ready before routing.
Do NOT use anonymous auth for AI features — anonymous login is disabled by default for new environments, and anonymous users are denied AI model permissions. Require a verified sign-in (phone, email, username+password, WeChat, custom) before calling any AI API. Delegate provider configuration to the auth-tool-cloudbase skill and the browser sign-in flow to the auth-web-cloudbase skill; the AI-model skill checks auth.getSession() and verifies loginType before gating the call.
Distinguish "preflight failure" from "model call failure" — the former means the user needs to buy a resource pack or call UpdateAIModel; the latter is a prompt / parameter / network issue. Give the user different guidance for each.
TypeScript: do NOT use any to silence type errors from the SDK. The SDK ships its own types; if an error shows up, narrow with unknown + a type guard, write a precise interface for the shape you actually consume, or augment types in a local .d.ts. Never : any, as any, @ts-ignore, or @ts-nocheck. See the Engineering constitution in the web-development skill.
Self-verify before claiming done. Run tsc --noEmit + the project build + open the page with agent-browser and actually trigger the AI call. Confirm: (a) the text stream reaches the UI, (b) no new console errors, (c) result.usage is non-zero. Saying "it should work" without evidence is not acceptable — follow web-development/browser-testing.md.