wechatide-skill

wechatide-skill

Purpose

This is the root entry point for WeChat Developer Tools workflows.

The following tasks should preferentially use this skill:

Execute page automation, validation, and screenshots
Troubleshoot runtime, page, or log issues
Handle cloud environments and cloud function-related actions
Execute WeChat Developer Tools operations such as preview, upload, and login

The following tasks should not use this skill:

General coding assistance
Desktop automation unrelated to Mini Programs
Ordinary script execution or arbitrary command invocation

Skill Installation

Before installing the WeChat Developer Tools skill in an AI agent, first obtain the current built-in skill directory and version number of WeChat Developer Tools:

wechatide

Or explicitly execute:

wechatide help

Pre-run Check (Required)

Before entering any scene or directly calling tools,you mustconfirm that the environment is ready and the user is logged in (guests cannot continue).

Step 1: Check WeChat Developer Tools status

wechatide -c <clientName> -t check_wechatide_status --skill-version <skillVersionFromSkillYaml>

Here <skillVersionFromSkillYaml> is not a fixed string; before calling, read the wechatide-skill/skill.yamlcurrently loaded by the calling-side agent, and fill in the value of the top-level version field in that file.

check_wechatide_status When called via skill-cli, if the WeChat Developer Tools MCP service is not started or the current client has not yet been authorized, the CLI will use the same <clientName> to automatically execute an equivalent wechatide auth -c <clientName>, and retry this status check after authorization is complete. The authorization popup still requires user confirmation.

Handle based on the returned result:

Returned Situation	Handling
The returned content contains `openid`	Environment is ready; continue with subsequent operations
`command not found`	The WeChat Developer Tools CLI is not installed or is not in PATH
`CONNECT_ERROR` / `AUTH_*`	Automatic authorization or connection retry failed; handle according to the error message, and if necessary, manually execute the auth command below
No `openid`	Not logged in; you need to trigger QR code login (see below)
`skillPath`	The path of the skill currently built into WeChat Developer Tools. When the built-in skill version is inconsistent with the version used by the local agent, update the skill according to this path; then you need to re-execute `check_wechatide_status`

Note：check_wechatide_status only needs to be called once at the start of the session. After confirming that the returned content contains openid and does not contain warning , do not call it repeatedly in subsequent operations; simply use other tools directly.

Skill Version Check

check_wechatide_status returns the skill version number currently built into the running WeChat Developer Tools skillVersion. For the input parameter version , you should fill in the top-level wechatide-skill/skill.yaml field value from the version file currently loaded by the calling-side agent. The tool will compare the two; do not hardcode the example version. When the versions are inconsistent, the return will include warning, and you should install and update the skill according to the tool's built-in skill path in the prompt. If version is not passed, only the WeChat Developer Tools status and login state are checked, and no version comparison reminder is returned.

When WeChat Developer Tools is not started

Usually no manual execution is needed;check_wechatide_status when the connection fails, it will automatically use the current <clientName> to execute once. When manual retry is needed, use skill-cli auth Start the tool and authorize the CLI connection:

wechatide auth -c <clientName>

After waiting for the tool to start and authorization to complete, re-execute the first step.

When not logged in

Trigger QR code login:

wechatide -c <clientName> -t login

After waiting for the user to complete scanning the QR code, call again check_wechatide_status to confirm that the returned content contains openid。Do not execute other tools before login is confirmed.

How to call

All tools are called uniformly through the global command:

wechatide -c <clientName> -t <toolName> [flags...]

wechatide is a global command, no need to know the installation path
-c: current agent abbreviation (e.g. CodeBuddy、Claude）
-t: tool name (e.g. open_project_window、cloud_env_list）
Tool parameters are determined by the tools.yaml of inputSchema , use the --field value form to pass
View all parameters of a tool:wechatide -c <clientName> -t <toolName> --help
For local filesystem path fields, pass the local absolute path directly; on Windows you can pass C:/..., and the CLI will convert it to a system-native path
object / array type fields can pass JSON directly:--<field> '{"a":1}'; you can also use the optional --<field>-file path.json. For required fields, only one of the two needs to be provided; they cannot be passed at the same time

On the first connection, WeChat DevTools will pop up a window to confirm authorization; after authorization, subsequent connections with this clientName will pass automatically.

Common call examples

wechatide -c CodeBuddy -t open_project_window --project <project>
wechatide -c CodeBuddy -t automation_runtime_info --project <project> --action currentPage
wechatide -c CodeBuddy -t check_wechatide_status --skill-version <skillVersionFromSkillYaml>
wechatide -c CodeBuddy -t simulator_open_page --project <project> --page pages/index/index --query id=1
wechatide -c CodeBuddy -t cloud_env_list --project <project>
wechatide -c CodeBuddy -t debug_clear_cache --project <project> --action cleanAll

Usage reminders

Do not guess or make up tool names, before calling you must first confirm the tool exists (see wechatide-tools/references/tools.yaml）
Tool names use underscores as separators (e.g. open_project_window、automation_viewport_action), do not use dots or camelCase
Screenshots are implemented through automation_viewport_action , you must pass one of waitForSelector or waitSeconds ; prefer using waitForSelector and take the screenshot after page elements such as these appear
If preview-related actions need to produce a QR code or information file, a local output path should be explicitly provided

Routing rules

After confirming the environment is ready, route according to the task intent:

Note: before calling a tool, carefully read the tool's parameter-passing rules before calling, do not make up parameter structures

Page automation, interaction, assertions:skills/automator/SKILL.md
Runtime troubleshooting, log analysis, status diagnosis, simulator status:skills/debugger/SKILL.md
Cloud environment, cloud functions:skills/cloudbase-operator/SKILL.md
Compilation, npm build, compilation conditions:skills/compiler/SKILL.md
Preview, real-device preview, upload code package:skills/previewer/SKILL.md(for preview-related matters, prefer using auto_preview, push directly to the phone)
WeChat DevTools project list query, import, delete from list:skills/project-manager/SKILL.md
Read/write/modify project configuration project.config.json(local settings, compilation switches, etc.,do not call MCP tool）：skills/project-config/SKILL.md
Mini Program map component, positioning, Tencent Location Service Web API:references/map-skill-index.md(not handled by this skill, points to the corresponding external skill)

When routing is ambiguous, prefer the category selection in "Quick judgment".

Quick judgment

If you just want to quickly determine which one to enter, you can directly understand it as follows:

First take over the project, confirm login, read AppID or runtime context:initializer
Need to click, input, scroll, screenshot, assert page results:automator
Need to check console, network, runtime or simulator exceptions:debugger
Need to compile pages, compile files, build npm, refresh simulator:compiler
Need to generate preview code, real-device preview, upload code:previewer
Need to query the cloud environment or operate on cloud functions:cloudbase-operator
Only need to manage the WeChat DevTools project list without opening the project window for now:project-manager
Need to change project local settings / project.config.json(domain verification, hot reload, compilation and compression, etc.):project-config(directly modify files)

Selection principles:

Route first according to the user's current primary goal; do not mix scenes just because other tools happen to be callable
Within a scene, even if only one or two atomic tools are needed, still prioritize preserving the scene's decision boundary
If the user's wording covers multiple goals at the same time, complete the blocker scene first, then hand off to the next scene

Standard workflow

Confirm that the wechatide command is available.
Check the connection, login state, and skill version (you must confirm that the returned content contains openid, and that skillVersion is not behind before continuing).
Identify the project and task goal.
If you only need to manage the WeChat DevTools project list (query/import/delete from list), use project-manager; if you need to compile or debug, then use initializer to open the project window.
If you need to open the project window (open_project_window): you must first read the project's project.config.json, and only after confirming that appid is valid can you call it. When it is missing, follow the open-project-window-guide.md completion process.
Select the appropriate scene skill.
Execute atomic tools through wechatide .
Output structured conclusions and next-step suggestions.

Interaction handling

If interaction requirements such as DevTools, system pop-ups, or user QR code scanning occur during tool execution, you should stop at the current step, explain the current state as-is, and wait for the user to complete the interaction before continuing. Do not maintain a specific action classification list at the root entry point.

Execution conventions

When using this skill, the only atomic execution entry point is wechatide
When execution fails, do not swallow it yourself, rewrite it, or continue guessing at a repair path; you should throw the error to the user as-is and let the user decide the next step

Reference materials

Pre-check before opening a project:wechatide-tools/references/open-project-window-guide.md
Mini program project creation process:wechatide-tools/references/create-project-guide.md
Tool registry:wechatide-tools/references/tools.yaml
Interaction handling:references/approval-policy.md
Map-related external skill index:references/map-skill-index.md
Security boundaries:SECURITY.md