CloudBase platform overview and routing guide. This skill should be used when users need high-level capability selection, platform concepts, console navigation, realtime (broadcast / presence / live d
1---2name: cloudbase-platform3description: CloudBase platform overview and routing guide. This skill should be used when users need high-level capability…4---56# config/.claude/skills/cloudbase-platform/SKILL.md
C
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 cloudbase-platform -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
CloudBase platform overview and routing guide. This skill should be used when users need high-level capability selection, platform concepts, console navigation, realtime (broadcast / presence / live database changes), or cross-platform best practices before choosing a more specific implementation skill.
Download config/.claude/skills/cloudbase-platform/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 cloudbase-platform live?
The publisher keeps it at https://github.com/TencentCloudBase/CloudBase-AI-Toolkit.
Which agents can use cloudbase-platform?
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
cloudbase-platform
description
CloudBase platform overview and routing guide. This skill should be used when users need high-level capability selection, platform concepts, console navigation, realtime (broadcast / presence / live database changes), or cross-platform best practices before choosing a more specific implementation skill.
version
2.37.5
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.
Cross-cutting protocols (required before code changes or deployments):
Sensitive Runtime Data Protection: references/protocols/sensitive-runtime-data-protection.md
Post-deployment (optional, non-intrusive): after a deployment is verified successful, you may offer at most once to generate anonymized shareables (Deployment Share) — see references/protocols/deployment-share.md. Deliver the card, the copy and the case-wall entry in one reply; shareables only if that is all the user asked for. Never follow up if declined; never publish or submit on the user's behalf.
Activation Contract
Use this first when
The user asks which CloudBase capability, service, or tool to use, or needs a high-level understanding of hosting, storage, authentication, cloud functions, or database options.
The task is about console navigation, cross-platform differences, permission models, or platform-level best practices before implementation.
Read before writing code if
It is still unclear whether the task belongs to Web, mini program, cloud functions, storage, MySQL / NoSQL, or auth.
The response needs platform selection, conceptual explanation, or control-plane navigation more than direct implementation steps.
Then also read
Minimal Web + database demo (BaaS-first, no cloud functions by default) -> ../minimal-web-baas-demo/SKILL.md
Stack order for 最小前后端 / Lovable-like demos: Web SDK CRUD > MCP schema > template warmup during credential wait > cloud functions (default count = 0). Capability sniff: connector ready → queryEnv → lock one DB plane → MCP schema → CRUD → preview.
@cloudbase/js-sdk
Web app implementation -> ../web-development/SKILL.md
Web auth and provider setup -> ../auth-tool-cloudbase/SKILL.md, ../auth-web-cloudbase/SKILL.md
Mini program development -> ../miniprogram-development/SKILL.md
WeChat Pay, Official Account OAuth, JSAPI Pay, or Native QR-code Pay through CloudBase Integration Center -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/introduce.md)
Cloud functions -> ../cloud-functions/SKILL.md
Official HTTP API clients -> ../http-api-cloudbase/SKILL.md
Document database -> ../cloudbase-document-database-web-sdk/SKILL.md or ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
Realtime / live push / channels / live table change subscriptions / multiplayer sync -> ../postgresql-development-cloudbase/references/realtime.md
PG mode only. Read its Step 0 before writing realtime code: describeRealtime only reads settings, so do not call enableRealtime as a routine step — ask the user before provisioning.
app.realtime() (Broadcast / Presence / Postgres CDC) is not document-database collection.watch(). Do not answer a realtime request with watch() code, or the reverse.
PostgreSQL schema and data modeling -> ../postgresql-development-cloudbase/SKILL.md; existing MySQL only -> ../relational-database-mcp-cloudbase/SKILL.md
Cloud storage -> ../cloud-storage-web/SKILL.md
Do NOT use for
Direct implementation of web pages, auth flows, functions, or database operations when a more specific skill already fits.
Low-level API parameter references or SDK recipes that belong in specialized skills.
Common mistakes / gotchas
Treating this general skill as the default entry point for all CloudBase development.
Staying here after the correct implementation skill is already clear.
Mixing platform overview with platform-specific API shapes or SDK details.
Using this overview skill as a detour in an existing application where the active auth, storage, and data files are already obvious.
Making code or configuration changes without first following the Change Safety Protocol (cloudbase-platform/references/protocols/change-safety-protocol.md).
Starting any deployment, publish, custom domain, or CloudRun work without first completing the checks in cloudbase-platform/references/protocols/deployment-gate.md.
Echoing x-cloudbase-context, full req.headers, or process.env from Cloud Functions / CloudRun (including httpbin-style debug images) — follow references/protocols/sensitive-runtime-data-protection.md.
Confusing security domains with custom domains: these are two different tools for different purposes. See the "Domain Management Tools" table below for the authoritative split.
When to use this skill
Use this skill for CloudBase platform knowledge when you need to:
Understand CloudBase storage and hosting concepts
Compare platform capabilities before implementation
Understand cross-platform auth differences (Web vs Mini Program)
Understand database permissions and access control
Access CloudBase console management pages
This skill provides foundational knowledge that applies to all CloudBase projects, regardless of whether they are Web, Mini Program, or backend services.
How to use this skill (for a coding agent)
Understand platform differences
Web and Mini Program have completely different authentication approaches
Must strictly distinguish between platforms
Never mix authentication methods across platforms
If the workspace is already an application with TODOs or prebuilt handlers, do not stay in platform overview mode. Move quickly to the concrete implementation skill and the existing files that own the flow.
Prefer @cloudbase/js-sdk direct DB access for browser CRUD; use cloud functions only for secrets, scheduled/background jobs, or elevated cross-collection logic that security rules / RLS cannot express (see ../minimal-web-baas-demo/SKILL.md for the demo default)
Use correct SDKs and APIs
Different platforms require different SDKs for data models
MySQL data models must use models SDK, not collection API
PostgreSQL / CloudBase PG work must route to postgresql-development-cloudbase; do not reuse NoSQL app.database() / db.collection(...) snippets or MySQL queryMysqlDatabase / manageMysqlDatabase for PG data paths
Use queryEnv tool to get environment ID
In an existing Web application with fixed structure, inspect the existing src/lib/backend.*, src/lib/auth.*, src/lib/*service.*, and bound page handlers before broad concept reading.
Use the canonical CloudBase MCP setup from the main cloudbase guideline
This platform overview intentionally does not duplicate the full MCP / mcporter config block
For the canonical config snippet, CLI commands, and auth examples, read the main cloudbase guideline first
Keep the same core rules here: prefer MCP when tools are available in this session; if not, configure MCP for next session and use tcb CLI now (../cloudbase-cli/SKILL.md, ../cloudbase/references/tooling-fallback.md). Inspect tool schemas before MCP execution. Do not hard-code Secret ID / Secret Key / Env ID in config
Keep the auth split explicit: management-side login uses auth, while application-side auth configuration uses queryAppAuth / manageAppAuth
CloudBase Platform Knowledge
Domain Management Tools: Clear Distinction
When working with domain-related tasks, use the correct tool based on the requirement:
domain = *.tcloudbaseapp.com (DomainType=STATIC_STORE, IsDefault=true), usually path="/"
Turns off public access on the shared hosting CDN default host. Do not use manageHosting.
Key indicators for choosing the right tool:
Task mentions "自定义域名访问" but env already has a custom domain → listCustomDomains then createRoute(domain=...) (no certificateId)
Task mentions "certificate ID" or "SSL" and needs to bind a new domain → manageGateway(action="bindCustomDomain")
Task mentions "浏览器上传" or "CORS" or "安全域名" → Use manageEnv(action="addSecurityDomain" / "removeSecurityDomain")
Task mentions "public access" or "HTTPS" with domain → Prefer reuse via createRoute when possible; only bindCustomDomain for first-time domain bind
Task mentions "关闭/禁用静态托管默认域名" / *.tcloudbaseapp.com → queryGateway(listRoutes) then manageGateway(disableRoute) with that STATIC_STORE domain; never invent ModifyGatewayRoute
Task asks about the whole onboarding flow (能不能绑、要等多久、解析怎么配、备案是不是前置) or a bound domain is not reachable → follow ../cloud-api-operations/references/recipes/custom-domain.md: run the read-only VerifyHTTPServiceRoute pre-check first, then bind, then poll Status / DNSStatus. That recipe also covers why domain registration / DNS / ICP calls may return UnauthorizedOperation for an account-level identity.
Error Code Troubleshooting: Route Through Official Docs
When a CloudBase tool call fails and the error message contains a specific error code (pattern Category.Code, e.g. OperationDenied.FreePackageDenied, ResourceNotFound.*), always route through the official docs before acting — do not guess the meaning, do not hardcode fix recipes here:
Extract the error code from the error message.
Look it up: searchKnowledgeBase(mode="docs", action="searchDocs", query="<错误码>") — official docs search covers error-code pages. Act on the documented meaning and the fix steps the doc prescribes (plan limits → upgrade guidance, misconfiguration → config fix, etc.).
If docs search returns nothing, fall back to the canonical error-code pages:
Control-plane cloud API error codes: https://cloud.tencent.com/document/product/876/34823
Never assert capability-per-plan or error-code semantics from memory — official docs and the console plan comparison are the only authoritative sources. Example: for Web 安全域名 plan requirements, cite https://cloud.tencent.com/document/product/876/127357 rather than assuming which tier unlocks it.
Billing and service-stop codes are a special case: the code's own reading is misleading, so diagnose before acting. When a failure is InsufficientBalance (a cloud function answers it with HTTP 410), EXCEED_REQUEST_LIMIT, or a service that is simply down, InsufficientBalance reads as an account problem and is not one: what runs out is the environment's resource points, which are drawn down ahead of any account balance (plan quota → resource packs → pay-as-you-go) and are not restored by a top-up. The official status-code table for the serverless service says "top up and retry", so a reader who follows the text sends the user to the account and the failure stays.
Diagnose first, then advise — four causes need four different answers (free-trial points exhausted / paid plan points exhausted / plan expired / account genuinely in arrears), and only the last one involves topping up. Run manageEnv(action="usage") for the environment's credit usage for the current cycle and read the account balance alongside it (callCloudApi, billing), both read-only; the decision table, per-plan remedies and the console entries are in credits-exhaustion. Two facts to carry into any advice: a free trial cannot buy resource packs or enable pay-as-you-go (upgrading to a paid plan is the only path), and the plan names are exactly 免费体验版 / 个人版 / 标准版 / 企业版 / 企业高级版.
Recording Operation Results
When a task explicitly requires recording operation steps or results to a file (e.g., RESULT.json): perform the tool calls first, then write a complete record containing every attempt (action, success/failure, message) plus a summary with total / succeeded / failed counts. Do not write the file from memory before the calls finish.
Storage and Hosting
Static Hosting vs Cloud Storage:
CloudBase static hosting and cloud storage are two different buckets
Generally, publicly accessible files can be stored in static hosting, which provides a public web address
Cloud storage is suitable for files with privacy requirements, can get temporary access addresses via temporary file URLs
If the task needs COS SDK polling, file metadata lookup, or temporary URLs for an uploaded object, use cloud storage tools (manageStorage / queryStorage), not manageHosting(action="upload")
Static Hosting Domain:
CloudBase static hosting domain and website document config can be obtained via queryHosting(action="websiteConfig")
Combine with static hosting file paths to construct final access addresses
Default shared host looks like <envId>-<appId>.tcloudbaseapp.com (DomainType=STATIC_STORE, often IsDefault=true in queryGateway(listRoutes))
To disable that default public host: manageGateway(action="disableRoute", domain="<that-host>", path="/") (or updateRoute with enable=false). Re-enable with enableRoute. Do not look for a manageHosting disable-default-domain action; do not call non-existent ModifyGatewayRoute — the API is ModifyHTTPServiceRoute
Important: If access address is a directory, it must end with /
Cloud Storage Public URL:
CRITICAL: manageStorage(action=upload) and queryStorage(action=url) return temporaryUrl which is a temporary signed URL that expires (default 1 hour). Do NOT use this as a permanent public URL.
To get the permanent public access URL for a cloud storage object:
Call queryEnv(action=info) to get environment details
Extract the storage CDN domain from EnvInfo.Storages[0].CdnDomain (e.g., your-env-id.tcb.qcloud.la)
Construct the public URL: https://{CdnDomain}/{cloudPath}
Example: If CdnDomain is env-xxx.tcb.qcloud.la and cloudPath is uploads/avatar.jpg, the public URL is https://env-xxx.tcb.qcloud.la/uploads/avatar.jpg
Note: The public URL is accessible only if the storage bucket ACL allows public read (default is PRIVATE which requires signed URLs)
Shared-Bucket (ExternalStorage) Environments:
Some environments keep files in a COS bucket shared with other environments, each isolated under its own directory prefix (BasePath). Detect it with queryEnv(action="info"): cloud storage uses a shared bucket when EnvInfo.Storages[0].Bucket is empty and Storages[0].ExternalStorage.Enabled === true; check static hosting the same way on EnvInfo.StaticStorages[0]. Storage and hosting can use different buckets and BasePaths.
Paths stay logical. Storage and hosting tools add the BasePath themselves, so pass cloudPath exactly as in a normal environment and never prepend the BasePath or bucket name. Example: with BasePath tenant-a, upload with cloudPath="images/a.png", not "tenant-a/images/a.png" (that nests the file under tenant-a/tenant-a/). Build hosting and CDN URLs from the logical path too — the domain resolves the BasePath, and adding it to a hosting URL returns 404.
manageHosting(action="setWebsiteDocument") changes a bucket-level setting that would affect every environment in the bucket, so it fails on shared-bucket hosting. Reading with queryHosting(action="websiteConfig") still works. Tell the user this setting is managed by the platform instead of retrying.
Storage security rules are maintained per environment, not as a COS bucket ACL, so read and update them the same way as in a normal environment.
What happens to files when a shared-bucket environment is deleted is decided by the platform. Do not promise that its BasePath directory is kept or removed.
Environment and Authentication
SDK Initialization:
CloudBase SDK initialization requires environment ID
Can query environment ID via queryEnv tool
If the user only provides an environment alias, nickname, or other short form, resolve it with queryEnv(action="list", alias=..., aliasExact=true) first and use the returned full EnvId
Do not pass alias-like short forms directly into SDK init, auth.set_env, console URLs, or generated config files
Defaults to all three when omitted. MCP always sends non-empty Resources to CreateEnv.
flexdb (document database) is not offered: new environments are created without a NoSQL tenant. Do not pass it — it is rejected by the schema. To find out whether an environment actually has NoSQL, read queryEnv(action="info") → EnvInfo.RuntimeBackends rather than assuming.
Region is selectable: pass region (e.g. region="ap-shanghai") to choose where the environment is created. It is applied as the X-TC-Region request context, not as a CreateEnv body field — so do not put Region inside params. Omit it to use the current session region (cloudBaseOptions.region → TCB_REGION → project config / rc binding → site default: ap-shanghai for the domestic site, ap-singapore for the intl site). Equivalent CLI: tcb env create --region ap-shanghai.
⚠️ If you pass region, repeat the same value on the confirming call together with confirm="yes"; otherwise the second call falls back to the session region and the environment may be created somewhere other than the summary you confirmed.
externalStorage (optional, create only): { bucketName, region, basePath } creates the environment's cloud storage on an existing shared COS bucket instead of a dedicated one, isolating its files under basePath (must be unique within the bucket). All three fields are required when the object is passed. Use it only when the user provides the bucket — typically a platform creating many environments under one account, where one bucket per environment would hit the account's COS bucket quota; never invent bucket names. It does not cover static hosting: the hosting bucket is chosen by the platform when hosting is enabled and cannot be set through this tool.
⚠️ Like region, repeat the same externalStorage on the confirm="yes" call. The confirming call reads only its own arguments, so leaving it out creates the environment with a dedicated bucket instead.
⚠️ That list is filtered to the packages the console offers in its new-purchase / new-environment menus: baas_personal (个人版), baas_pf_standard (标准版), baas_pf_enterprise (企业版), baas_pf_enterprise_senior (企业高级版), baas_trial (体验版), baas_integration (集成版). Package families (default / basic / trial / vip) do not map onto that set — legacy packages such as starter (入门版), baas_team (团队版) and enterprise_basic (企业基础版) share families with the current ones and are deliberately excluded. The platform still accepts other valid packageIds, so the actual create result is authoritative.
Changing plan (use a packageId from listPackages):
Important: Authentication methods for different platforms are completely different, must strictly distinguish!
Web Authentication
Must use SDK built-in authentication: CloudBase Web SDK provides complete authentication features
Recommended method: SMS login with auth.getVerification(), for detailed, refer to web auth related docs
Forbidden behavior: Do not use cloud functions to implement login authentication logic
Session management: For route guards and login proof, use auth.getSession() and require data.session; do not use deprecated getLoginState() or auth.getUser() / auth.getCurrentUser() as proof of real login.
Provider and login-method setup: Use queryAppAuth / manageAppAuth, not the MCP auth tool
Anonymous login is disabled by default. Publishable accessKey alone does not create a gateway-authenticated anonymous session. With @cloudbase/js-sdk3.x, call await auth.signInAnonymously() (or an equivalent authenticated session) before NoSQL app.database() CRUD, or the gateway returns 401. If the app uses AuthGuard or RLS for access control, ensure is_anonymous checks are in place when anonymous access is allowed.
⚠️ PG RLS: Use auth.uid(), NOT current_user. When writing RLS policies for CloudBase PostgreSQL, the user identity must use auth.uid() (returns the JWT sub / actual user ID as text, not uuid — unlike Supabase). Prefer owner columns as varchar(64) / text; if the column is uuid, cast with auth.uid()::uuid or you get operator does not exist: uuid = text. Do NOT use current_user or current_setting(...) — these PostgreSQL built-in functions return the database role name (e.g. authenticated), not the CloudBase auth user ID. CloudBase PG provides four auth helper functions: auth.uid(), auth.role(), auth.email(), auth.jwt(). Verify availability with SELECT proname FROM pg_proc WHERE pronamespace = 'auth'::regnamespace.
Mini Program Authentication
Login-free feature: Mini program CloudBase is naturally login-free, no login flow needed
User identifier: In cloud functions, get wxContext.OPENID via wx-server-sdk
User management: Manage user data in cloud functions based on openid
Forbidden behavior: Do not generate login pages or login flow code
Cloud Functions
Node.js Cloud Functions:
Node.js cloud functions need to include package.json, declaring required dependencies
Can use manageFunctions(action="createFunction") to create functions
Use manageFunctions(action="updateFunctionCode") to deploy cloud functions
Prioritize cloud dependency installation, do not upload node_modules
functionRootPath refers to the parent directory of function directories, e.g., cloudfunctions directory
Database Permissions
⚠️ CRITICAL: Always configure permissions BEFORE writing database operation code!
Permission Model:
CloudBase database access has permissions
Default basic permissions include:
READONLY: Everyone can read, only creator/admin can write
PRIVATE: Only creator/admin can read/write
ADMINWRITE: Everyone can read, only admin can write (⚠️ NOT for Web SDK write!)
ADMINONLY: Only admin can read/write
CUSTOM: Fine-grained control with custom rules
Platform Compatibility (CRITICAL):
⚠️ Web SDK cannot use ADMINWRITE or ADMINONLY for write operations
✅ For user-generated content in Web apps, use CUSTOM rules
✅ For admin-managed data (products, settings), use READONLY
✅ Cloud functions have full access regardless of permission type
Use managePermissions(action="updateResourcePermission") to configure resource permissions
If permissions were just changed, retry after a few seconds (typically within ~30s). Do not blind-wait 2-5 minutes. If it still fails, re-check the actual rule shape and active client write pattern first — most failures are misconfigured rules, not cache.
See no-sql-web-sdk/security-rules.md for detailed resourceType="noSqlDatabase" examples only; do not treat doc._openid, auth.openid, query-subset validation, or create / update / delete JSON templates as generic rules for functions, storage, or SQL tables
Official references:
General security rules overview: https://cloud.tencent.com/document/product/876/41802
E-commerce products: READONLY (admin manages via cloud functions)
Shopping carts: CUSTOM with auth.uid check (users manage their own)
Orders: CUSTOM with ownership validation
System logs: PRIVATE or ADMINONLY
Cross-Collection Operations:
Prefer security rules / RLS and client SDK when the permission model allows it
Use cloud functions when the operation needs elevated privileges, server secrets, or multi-collection logic that rules cannot express
For minimal Web demos (Todo / Notes / Kanban / 最小前后端), do not introduce cloud functions for CRUD — follow ../minimal-web-baas-demo/SKILL.md
Role Management (MCP)
CloudBase MCP provides role management via queryPermissions and managePermissions (CLI equivalent: tcb role). See each tool's schema for the full action list.
⚠️ CRITICAL: Role policies and resource permissions are two independent systems with NO automatic synchronization.
Resource permissions (security rules) control access to specific resources (tables, collections, functions, storage)
Roles (identity dimension) control policy bundles and member assignments
Use manageDataModel tool's docs method to get specific SDK usage
Console Management
After creating/deploying resources, provide corresponding console links. All console URLs follow the pattern: https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path} — replace ${envId} with the real EnvId resolved via queryEnv (resolve aliases first; see Environment and Authentication below), and resource names with actual values.
The CloudBase console is updated frequently. If a live, logged-in console shows a different hash path from this list, prefer the live console path over stale documentation and then update this skill to match.
CloudRun: #/platform-run (a per-environment capability that must be provisioned first — manageCloudRun(action="initEnv"), then poll queryCloudRun(action="envStatus") until normal; an env can exist without CloudRun, and in that case CloudRun APIs still return success with empty fields)