CLI tool adaptation
The first step in starting this Skill is to check the connection status:
wpsnote-cli status --json
If the command does not exist or returns a connection failure, stop execution and tell the user they need to first install and open WPS Notes, enable the capability in "Settings" → "AI Lab", and then rerun wpsnote-cli status --json to confirm.
All WPS Notes operations are executed directly in the system command line wpsnote-cli; complex parameters are always passed via --json-args , and all commands that need structured results add --json。
wpsnote-cli manage-tags --note_id "<id>" --json-args '{"add":["工作/项目"],"remove":["旧标签"]}' --json
| MCP semantics | CLI command |
|---|---|
get_note_stats({ detailed: true }) |
wpsnote-cli stats --detailed true --json |
find_tags() |
wpsnote-cli tags --json |
search_notes({ tags }) |
wpsnote-cli find --json-args '{"tags":["标签名"]}' --json |
get_note_info({ limit, page }) |
wpsnote-cli info --json-args '{"page":1,"page_size":50}' --json |
manage_note_tags({ note_id }) |
wpsnote-cli manage-tags --note_id <id> --json |
manage_note_tags({ note_id, add/remove }) |
wpsnote-cli manage-tags --note_id <id> --json-args '{"add":["新标签"],"remove":["旧标签"]}' --json |
get_note_outline({ note_id }) |
wpsnote-cli outline --note_id <id> --json |
read_note({ note_id }) |
wpsnote-cli read --note_id <id> --json |
read_blocks({ note_id, block_ids }) |
wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' --json |
Tag organization writes only use wpsnote-cli manage-tags。read、outline、read-blocks is only used to understand content, not to change tags.
Core principles
Organizing tags is not about executing a standard methodology, but about serving a specific person. There is no unified "correct" way to categorize; all decisions are based on the user's actual needs.
The value of organizing comes from only three directions, and any change that cannot bring about any one of them is not worth doing:
- Improve usage efficiency: reduce maintenance burden and lower categorization anxiety
- Improve retrieval efficiency: help users find target content faster
- Bring new perspectives for knowledge connections: discover connections that were previously invisible
Do not ask the user at the start of the task, "what scope do you want to organize, and how should it be organized?". When users ask AI to organize, it itself means they do not want to make these judgments themselves. AI's responsibility is to proactively provide specific options, letting users make multiple-choice decisions rather than answer open questions.
Operational safety constraints
At the current stage, only tagging is done. Note tags are independent file-level objects, added, deleted, and modified through the dedicated command wpsnote-cli manage-tags .
Hard rules that must be followed for every operation:
-
Only use for modifying tags
wpsnote-cli manage-tags：- Query the current tags of a note:
wpsnote-cli manage-tags --note_id <id> --json - Add:
wpsnote-cli manage-tags --note_id <id> --json-args '{"add":["工作/项目"]}' --json - Delete:
wpsnote-cli manage-tags --note_id <id> --json-args '{"remove":["旧标签"]}' --json - Rename / merge: combine in the same call
remove+add
- Query the current tags of a note:
-
Global operations across notes must first
ask_userconfirm: global renaming, merging, and batch deletion of tags (affecting 2 or more notes) are cross-note batch operations, andask_user。 -
Skip notes with unclear intent directly: when the content topic or purpose cannot be determined, do not guess, do not modify, and list them as "unprocessed" in the plan to inform the user.
-
Do not delete any notes: no matter how empty a note appears, do not delete any notes at this stage.
-
Confirmation must use
ask_usertool: it is forbidden to replaceask_usercalls with text questions—text questions will not pause execution, and the user cannot intervene. In the same round as callingask_user, executing write commands is forbidden.
WPS Notes system behavior description
When operating in WPS Notes, the following system behaviors affect the results and must be understood:
| Behavior | Description | How to handle |
|---|---|---|
/ represents hierarchical separation |
In tag names, / is the hierarchy separator, and WPS automatically parses it as a parent-child relationship |
Write the full path to call wpsnote-cli manage-tags --json-args '{"add":["工作/项目"]}' --json |
| Case-sensitive | Tags are stored exactly as the user entered them,TODO、Todo、todo are three different tags |
When comparing tags, compare literally and do not normalize case |
| Tag input limits | At most 10 levels of hierarchy, each level at most 20 characters; \ : * ? " < > | and emoji are prohibited; duplicate tags are not allowed within the same document |
When generating new tags, proactively comply with these limits; when a system error occurs, adjust according to the returned information and retry |
Task flow
第一步：全局概览，判断健康度
↓
第二步：分析与诊断
↓
第三步：给出具体方案 ──→ [结论：不需要整理] → 说明理由，结束
↓
第四步：用户确认 ──→ [有异议] → 修改方案，回到第四步
↓
第五步：执行
↓
第六步：回顾检查 ──→ [有偏差] → 修正，重新检查
Step 1: Global overview, assess health
Choose appropriate commands to view the current note files and tag list, understand the overall state of the current note system, and then decide where to dig deeper.
First layer: Required (global overview)
-
wpsnote-cli stats --detailed true --json— obtain in one call:- Total number of files, total number of tags, number of untagged files
- Distribution of file counts under each tag (sorted by note count descending, returning at most 30; when there are many tags, combine with
wpsnote-cli tags --jsonto see the full set) - List of recently updated files
-
wpsnote-cli tags --json— obtain:- Complete tag hierarchy structure (parent-child relationships, naming)
- Identify naming style, hierarchy logic, suspicious tag names
After completing these two steps, you can usually already discover most problems (imbalanced granularity, inconsistent naming, too many untagged files, etc.) and form a preliminary judgment on the direction of organization.
Second layer: Investigate as needed (for discovered problems)
Based on the clues found in the first layer, use the following commands as needed for targeted investigation:
| What you want to know | Which command to use |
|---|---|
| Which files are under a suspicious tag | wpsnote-cli find --json-args '{"tags":["标签名"]}' --json |
| Which files are untagged | wpsnote-cli info --json-args '{"page":1,"page_size":50}' --json Paginated query, filter notes where tags is empty |
| Which tags a note currently has | wpsnote-cli manage-tags --note_id <id> --json |
| What a file is roughly about | wpsnote-cli outline --note_id <id> --json |
| The exact content of certain blocks in a file | wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' --json |
| The complete content of a file (when deep understanding of the content is needed) | wpsnote-cli read --note_id <id> --json |
Principle: use the lightest command that satisfies the current need：outline When it can locate, prefer to use it;find --tags When it can filter, prefer to use it; only use read。
Step 2: Analysis and diagnosis
On the basis of complete information, identify the user's classification habits, andcheck item by item against the problem diagnosis table below。
Existing habits are valuable assets, not problems that need correcting. If the user already has fixed habits and the classification logic is reasonable,do not easily break them。
During analysis, also think in combination with the note content: why did the user save each note? What scenario does it serve? What keywords will be used to retrieve it in the future? This determines whether the tags have real retrieval value.
Precondition judgment: too few tags to diagnose
When there are very few existing tags, it is not enough to determine the user's classification preferences. In this case, skip the following diagnosis and instead, based on the note content, for the userdesign a tag system from scratch。
→ Consult references/classification-methods.md, and choose an appropriate classification method from it according to the user's scenario (hierarchical classification / P.A.R.A. / entity-scenario method), and in step threeclearly explain the reason for the choice, and have the user confirm. When uncertain, recommend by defaulthierarchical classification(the most broadly adaptable and easiest to get started with).
Problem Diagnosis Table
1. Duplication / Same meaning
| Description | |
|---|---|
| Normal state | The same concept has only one tag |
| Problem manifestation | 待办、TODO、to-do coexist;AI and 人工智能 coexist;会议 and meeting coexist |
| Suggested handling | Merge into the one the user uses more often; after the original tag loses all references, it is automatically cleaned up by the system |
2. Unreasonable hierarchical structure
| Description | |
|---|---|
| Normal state | The parent-child relationship is semantically valid (the child tag is a concretization of the parent tag); tags at the same level are truly parallel concepts; the number of tags at each level is moderate, and the depth of the hierarchy has practical meaning |
| Problem manifestation (hierarchical misplacement) | Parallel concepts are mistakenly placed as a parent-child relationship:学习/数学/语文，数学 and 语文 are parallel subjects,语文 should not be placed under 数学 under |
| Problem manifestation (too many at the same level) | Dozens of tags in one level are all laid out flat without any grouping, making the tag list lengthy—in this case, similar tags should be grouped under a common parent tag |
| Problem manifestation (redundant hierarchy) | There is only one tag in a level, with no other parallel items in the intermediate layer, and it does not provide additional filtering value—in this case, the intermediate layer should be merged or removed |
| How to judge | Ask at every level: "What is the meaning of this level? What concepts might be parallel to it in the future?" A level that cannot be answered should not exist; when there are many tags at the same level, consider whether there is a common parent under which they can be grouped |
| Suggested handling | Hierarchical misplacement → correct the parent-child relationship; too many at the same level → identify common attributes and create a parent tag for grouping; redundant hierarchy → merge or remove the intermediate layer |
3. Imbalanced tag granularity
| Description | |
|---|---|
| Normal state | The number of files associated with each tag is moderate and can filter effectively (neither too broad nor too fine) |
| Problem manifestation (too fine) | A tag is associated with only 1-2 files, and these files are already covered by a more appropriate parent tag—this tag is redundant |
| Problem manifestation (too broad) | A tag is associated with a large number of files, and after opening it, it is almost equivalent to "all notes," with no filtering value during retrieval |
| Suggested handling | Too fine → merge into the parent tag or a similar tag; too broad → split into child tags and guide the user to use more precise classification |
4. Inconsistent naming style
| Description | |
|---|---|
| Normal state | Tag naming style at the same level is consistent (consistent part of speech, language, and capitalization) |
| Problem manifestation | Among sibling tags, some use nouns and some use verbs; Chinese and English are mixed; full-width and half-width symbols are mixed; English capitalization is inconsistent |
| Handling suggestion | Unify based on the style of the user's existing majority of tags; the naming style itself has no right or wrong, just unify it |
5. Uneven note coverage
| Description | |
|---|---|
| Normal state | Most notes have tags, and the tag system can cover the user's main content types |
| Problem manifestation | A large number of notes have no tags at all, or a certain type of content (such as recently added notes) systematically lacks tags |
| Handling suggestion | Add tags to untagged notes; when the gap is too large, prioritize the most commonly used and most important content |
If none of the above problems exist: → Proceed to step three, directly tell the user "it is recommended to keep the status quo" and explain the reason.
Step three: provide a specific plan
Directly present the target tag system structure after changes, with the reason for each change attached—present the target state completely so the user can compare and judge.
Plan format example:
建议改动后的标签体系：
工作
├── 项目 ← 原 项目A、项目B 统一归入此处
└── 日常 ← 原 工作记录 改为此，更简洁
学习 ← 原 读书 和 网课 合并入此
├── 读书
└── 网课
生活 ← 保持不变
待办 ← 原 TODO、to-do 合并为此（用户最常用的写法）
未处理：「未命名笔记」「未命名笔记(1)」（内容为空或无法判断意图，请用户自行决定）
Case one: only a small number of changes are needed
→ Directly list the specific changes, explain the reasons, and proceed to step four for confirmation.
Case two: a relatively large-scale rebuild is needed
→ First present the overall target structure, then list the main change points, so the user can judge the whole picture before confirming.
Step four: user confirmation
Obtain user confirmation through the ask_user tool.
Case one: the user agrees
→ Proceed to step five for execution.
Case two: the user raises objections or doubts
→ Rethink the plan. The user's doubts usually point to places in the plan that are not logically consistent; modify accordingly, present again, and return to step four.
Case three: the user partially agrees
→ Execute only the part the user confirmed, defer the uncertain part, and wait for further confirmation from the user.
Step five: execution
Execute the changes according to the confirmed plan.
Judging execution scale:
- Few changes (single digits) → complete in one go
- Many changes → execute in batches, with each batch divided by logical unit (e.g., handle global merge operations first, then handle individual note adjustments)
Step six: review and check
After execution is complete, proactively verify the results.
Two levels must be verified:
- The tags of the target notes: check from the
wpsnote-cli manage-tagswrite return value—tagsis the complete updated tag list,added/removedare the items that actually took effect; confirm that the target tags are intagsand that the hierarchy is correctly reflected with/Correct reflection - System tag list（
wpsnote-cli tags --json): confirm that new tags have been created, merged/deleted old tags have disappeared, and the overall structure conforms to the plan
Case one: the result is consistent with expectations
→ Present a summary of changes to the user, and explain whether there are any remaining issues (for example, the reason why some notes were skipped).
Case two: deviations are found
→ Find the cause, correct it, and recheck until the result is consistent with expectations before reporting to the user.