【使用反馈】WPS灵犀Claw版本v1.2.3的技能管理体系

WPS灵犀Claw在6月1日进行了一次大版本更新，对技能管理体系进行了重大变更。我在使用过程中一时间难以完全适应，使用过程极为艰难，现在将我的一些发现和体验分享如下。

一、manage_skills工具

manage_skills 是 WPS 灵犀内置工具之一，用于管理SKILL技能的upload（上传）和 delete（删除）。通过 manage_skills，用户可以将本地开发的技能同步到云端永久保存，也可以从云端和本地同时移除不再需要的技能。

具体功能如下：

manage_skills 工具接受两个参数：action（必填）和 names（必填）。

upload — 上传技能

将本地技能目录打包上传到云端。操作逻辑如下：

• 新建：云端不存在同名技能时，自动创建新的云端技能

• 覆盖更新：云端已存在同名技能时，自动覆盖更新为本地最新版本

参数说明：

• names：传入技能目录名列表（非完整路径），例如 ["my-skill"]

使用场景：

场景一：创建新技能后发布

1. 在技能目录下创建新技能目录

2. 调用 manage_skills(action="upload", names=["技能名"]) 同步到云端

3. 云端生效，当前会话及后续会话均可使用该技能

场景二：修改已有技能后同步

1. 修改技能目录下的 SKILL.md 或资源文件

2. 调用 manage_skills(action="upload", names=["技能名"]) 覆盖云端版本

3. 更新即时生效

delete — 删除技能

从云端和本地同时移除指定技能。

参数说明：

• names：传入要删除的技能目录名列表

注意事项：

• 删除操作不可逆，技能及其所有文件将从云端和本地永久移除

• 删除前应确认技能不再被任何工作流依赖

• 官方技能（source 为 official 的技能）不可通过此工具删除。

二、技能目录体系

WPS 灵犀的技能系统涉及以下三个目录，它们各自承担不同的角色：

1、target_skills — 运行时技能目录

C:\Users\用户名\AppData\Roaming\WPS 灵犀\serverdir\target_skills

这是 WPS 灵犀在运行时实际读取的技能目录。manage_skills 工具的 upload 和 delete 操作直接作用于此目录——upload 将技能写入此处并同步到云端，delete 从此处移除技能。

2、user_skills — 用户技能源目录

C:\Users\用户名\AppData\Roaming\WPS 灵犀\serverdir\user_skills

存放用户自行安装、创建或从社区获取的技能。用户通过技能市场安装的技能、自行编写的自定义技能均存放于此。

3、official_skills — 官方技能源目录

C:\Users\用户名\AppData\Roaming\WPS 灵犀\serverdir\official_skills

存放 WPS 灵犀官方提供的技能。这些技能由 WPS 灵犀团队开发与维护，source 标记为 official。官方技能不可通过 manage_skills 删除或直接修改。

我在实际使用过程中发现以下使用特征：

现象一

user_skills 和 official_skills 中的技能不会自动全部出现在 target_skills 中——只有通过manage_skills 的 upload 操作处理过的技能才会出现在 target_skills 中供 Agent 使用。

现象二

在对话过程中，WPS灵犀Claw默认检索的技能路径为target_skills，不会自动检索user_skills 和 official_skills 中的技能。如果WPS灵犀Claw在target_skills中无法检索到用户提及的技能，可能会反复尝试，导致任务持续停留在查找技能所在位置这一步骤，任务无法向前迈一步。直到WPS灵犀Claw扩大搜索范围，或者用户手动中断任务，提供明确的技能路径后，才能使任务正常进行下去。

现象三

对本地target_skills 目录下的文件进行手动增、删、改，一段时间后会自动恢复原样。

这个现象似乎说明新版的技能管理机制采用了类似 Kubernetes 的etcd + Controller 循环：

• 云端是唯一真实来源（source of truth）：所有技能状态以云端为准

• 本地target_skills 技能目录只是运行时缓存：系统会定期或在启动时将云端技能状态同步到本地系统

• 直接操作文件系统相当于修改缓存，当系统进行下一次同步时，缓存会被云端数据覆盖

用户对target_skills 目录下的技能进行手动增、删、改之后，应当马上调用 manage_skills上传到云端。因此，建议用户不要手动对技能进行增、删、改，否则一旦忘了及时调用manage_skills上传到云端，很有可能丢失操作。

现象四

我发出明确指示，让WPS灵犀Claw使用upload 操作将user_skills的全部技能上传至云端，但仍有很多技能无法成功上传。

对上传不成功的技能进行初步观察和分析后，认为原因可能以下几点：

• 系统对技能命名存在规范约束 — 目录名须全小写字母加连字符，含大写、中文、特殊字符会失败

• SKILL.md 中 name 字段格式违规 — name 须全小写字母数字连字符，禁中文、引号、特殊符号

• 目录名与 name 字段不一致 — 双重校验，不一致时上传被拒或无法索引

• 与云端已有技能同名冲突 — 官方技能不可覆盖，系统预装技能不受 manage_skills 管理

• name 字段重复冲突 — name 必须在全局唯一，不同目录名不能声明相同 name

• 技能包体积限制 — SKILL文件体积过大时可能上传失败

• 网络超时 — 处理时间过长时可能上传失败

除了以上原因之外，还有一个重要的原因：manage_skills 的 upload 操作是从 target_skills 目录读取技能然后上传，而不是从 user_skills，所以上传前需要先把技能复制到 target_skills。如果WPS灵犀Claw在执行过程中遗漏了将技能文件先复制到target_skills这个步骤，也会导致上传失败。

现象五

user_skills下会自动许多带.tmp后缀的文件，即使手动删除了，一会儿又会重新生成。

原因可能有以下两种可能性：

第一种可能性是WPS 灵犀可能存在一个技能名规范化后台进程，它会自动扫描 user_skills 中名称不合规的技能（含大写字母、特殊字符等），并创建小写规范化副本。这个后台进程会周期性运行（或在特定触发器下启动）。只要原始不规范命名的技能（如 Anthropic、openAI）仍存在于 user_skills 中，进程每次扫描到它们，就会重新尝试规范化，再次生成 .tmp 文件——即使我手动删除了之前的 .tmp。

解决办法：

1. 规范化原始目录名：修改user_skills 中的目录名，确保不含大写/中文/特殊字符的名称，消除触发条件。

2. 从 user_skills 移走：如果这些技能已通过 manage_skills 上传到云端，可以将 user_skills 中对应目录删除或移出，让后台进程不再扫描到它们。

第二种可能性是，如下文现象六所述，user_skills文件夹也可能受到同步机制管控，如果该技能体积过大或者存在格式规范性问题时，文件从云端同步到本地时可能出现失败，然后重试多次。这重试过程中产生的临时文件，就可能以.tmp文件的形式存在。

我对带.tmp的技能文件进行初步观察和分析后，发现有的技能文件夹会突然缺失SKILL.md或scripts、references文件，而最近生成的一份.tmp文件却是完整的，这说明.tmp产生的原因更可能是以上所说的第二种可能性：不带.tmp后缀的技能文件夹是因同步失败而被覆盖了；而最近生成的一份.tmp文件却是最终成功同步了的。

现象六

如果我从user_skills手动删除了某个技能，但未调用manage_skills从云端移除，一会儿这个技能会重新出现在user_skills中。

这个现象似乎说明，user_skills与target_skills之间存在某种关联：当同步机制从云端向本地更新了target_skills目录之后，对于source≠ official 的技能会在user_skills自动创建相应的技能目录。因此，当用户从user_skills手动删除了某个技能，但该技能仍然保留在云端中，同步之后就会导致这个被删的技能重新出现在user_skills中。如果用户对user_skills某个技能进行了手动修改，但未对云端版本进行修改，同步之后也可能会导致云端版本覆盖已修改的本地版本。

因此，建议用户对user_skills中的技能进行手动增、删、改之后，应当马上调用 manage_skills上传到云端。建议用户最好不要手动对技能进行增、删、改，否则一旦忘了及时调用manage_skills上传到云端，很有可能丢失操作。

三、file工具

file 工具是 WPS 灵犀内置工具之一，用于操作本地磁盘上的文件，提供read（读取）、write（覆盖写入）、append（追加写入）、edit（精确查找替换）四种操作。file工具是技能管理过程中的重要工具：

1、技能加载的入口

每次任务开始时，Agent 通过 file 工具读取 target_skills 目录下对应技能的 SKILL.md 文件，获取操作指南、决策树、代码示例等内容。只有通过file 工具，技能知识才能进入 Agent 的上下文。

2、技能开发的编辑工具

当需要创建或修改一个技能时，用户需使用 file 工具的 write、append、edit 操作，在技能目录下编写 SKILL.md、references/、scripts/ 等文件。

3、协作关系

file 工具操作的是本地文件系统，而 target_skills 目录是云端技能的本地缓存，受声明式同步机制管控。用 file 工具直接修改 target_skills 下的文件，未经manage_skills 上传的话，效果等同于修改缓存，当系统下一次同步时文件仍会被云端数据覆盖。

用户如果修改了本地技能目录的文件夹，务必要及时上传云端，才能在对话过程中被WPS灵犀Claw默认检索到：

如果修改了user_skills文件夹下的技能，需将文件复制到target_skills文件夹后，立即调用 manage_skills(action="upload", names=["技能名"]) 上传到云端。

如果修改了target_skills 文件夹下的技能后，立即调用 manage_skills(action="upload", names=["技能名"]) 上传到云端。

只要上传动作紧跟在修改之后、没有等待同步周期介入，云端版本就会被更新为最新内容，后续再同步下来的也是正确版本。

因该技能管理机制复杂、繁琐，仍有许多精微之处未能细致测试，望社区的各位朋友一同协助，理清逻辑，发掘问题，提供建议。