灵犀Claw实战：从零搭建一个会自我进化的AI Agent（十）Skill开发实战——造一个属于自己的Skill

本系列记录用WPS灵犀Claw平台从零搭建一个具备完整记忆闭环和自我改进能力的AI Agent的全过程。每个专题一篇，由浅入深。

开篇引言

前九篇我们一直在"用"Skill——实时记忆、Dreaming、日记、生图、TTS、云文档，每一篇都在围绕一个具体的Skill展开。到了第十篇，该聊聊怎么"造"Skill了。

灵犀Claw官方提供了skill-creator技能，里面有完整的目录结构规范、init和package命令、打包流程。但有一个问题是官方文档不会回答的：什么样的功能值得封装成Skill？Skill该怎么设计才真正好用？

本篇不讲怎么用skill-creator（那个看官方文档就够了），而是从我们自己的实战经验出发，分享Skill的设计思路。读完你会发现，好的Skill不是"写"出来的，是"长"出来的。

什么时候该封装成Skill

不是所有功能都值得封装成Skill。封装是有成本的——每个Skill都会占用上下文窗口，Agent需要读取SKILL.md才能理解它的用法。如果封装了一个很少用到的功能，反而会拖慢Agent的响应速度。

根据实战经验，以下三种情况值得封装：

功能有确定的执行流程。如果某个任务每次做的方式都差不多，就值得封装。比如"生成日记"——每天都是采集数据、构建提示词、生成内容、写入笔记，流程固定。如果每次让Agent自由发挥，结果可能不一致，而且浪费token。

功能依赖外部API或工具。如果Agent需要调用第三方服务（TTS、生图、云文档），封装成Skill可以把API Key管理、错误处理、重试逻辑都藏起来，Agent只需要说"帮我说这句话"就够了。

功能需要特定领域知识。如果Agent需要理解某个领域的专业术语或规则，封装成Skill可以补充这些知识。比如多维表操作——Agent不需要知道dbsheet API的每个参数，Skill告诉它"按这个流程操作"就行。

反过来，以下情况不值得封装：一次性的临时任务、Agent凭通用能力就能搞定的简单操作、功能边界模糊且变化频繁的业务逻辑。

三种Skill设计模式

回顾整个系列中用到的Skill，可以归纳为三种设计模式。理解这三种模式，就能应对大部分封装需求。

模式一：第三方服务封装（mimo-tts）

这种模式的核心是"把外部API变成Agent的自然语言接口"。Agent不懂TTS的API参数、不懂voiceclone和voicedesign的区别，但它知道"用我的声音说这句话"。Skill的作用就是在中间做翻译。

设计要点：SKILL.md中只暴露Agent需要关心的概念（模型选择、风格控制），API Key、重试逻辑、错误处理全部藏在scripts里。Agent调用时只需要传入文本，其他都是Skill的默认行为。

模式二：官方API封装（wps-docs）

这种模式的核心是"把官方API的调用方式翻译成Agent能理解的语言"。官方API的文档通常面向开发者，参数多、流程复杂。Skill需要做的是简化——告诉Agent"查文件信息用get_file_info，上传用三步流程"。

设计要点：SKILL.md中提供场景路由表（什么场景用什么函数），scripts中封装好认证和错误处理。Agent不需要理解V7 API的细节，只需要知道"把这个文件上传到那个文件夹"。

模式三：业务逻辑封装（cherry-diary）

这种模式的核心是"把多步骤业务流程固化为可重复执行的工作流"。日记生成涉及数据采集、提示词构建、XML构建、笔记写入、图片生成、语音合成等多个步骤，每一步都有特定的顺序和依赖关系。

设计要点：SKILL.md中描述完整的执行流程和步骤依赖，scripts中实现每一步的具体逻辑。关键是把"先做什么、再做什么、遇到异常怎么办"说清楚，Agent按流程执行即可。

三种模式没有优劣之分，选择哪种取决于你要封装的是什么。同一个Skill也可能同时包含多种模式的特征。

从"需求"到"Skill"的完整过程

以mimo-tts Skill为例，看看一个Skill是怎么从想法变成可用的。

第一步：发现需求。Agent需要语音能力，但每次调用TTS都要写一大段OpenAI客户端代码，而且Agent不熟悉voiceclone的参数细节。这个痛点重复出现了几次，说明值得封装。

第二步：确定边界。这个Skill要覆盖什么？只做TTS，不做语音识别。支持哪些模型？预置音色、音色设计、音色克隆都支持。输出格式？wav就够了，mp3和ogg作为备选。边界清晰了，Skill才不会越做越臃肿。

第三步：写脚本。先把核心功能写成Python脚本，通过命令行参数接收文本和输出路径。这一步的目的是把"确定性逻辑"固定下来——API调用、参数处理、错误重试这些每次都不变的东西，写成脚本比让Agent每次重新写更可靠。

第四步：写SKILL.md。脚本写好后，再写SKILL.md告诉Agent怎么用。包括：什么时候触发这个Skill（description字段）、怎么加载脚本、模型怎么选、风格怎么控制、常见问题怎么处理。SKILL.md的质量直接影响Agent调用Skill的成功率。

第五步：测试和迭代。让Agent在实际任务中使用这个Skill，观察哪些地方容易出错。比如mimo-tts最初没有区分voiceclone和voicedesign的调用方式，Agent经常用错参数。迭代后在SKILL.md中明确标注"voiceclone模式不加context"，问题就解决了。

这个流程的关键在于：先写脚本，再写SKILL.md。脚本把"怎么做"固定下来，SKILL.md告诉Agent"什么时候做"。顺序反了会导致SKILL.md写得很好但脚本不好用。

SKILL.md的实战写作

官方skill-creator对SKILL.md的格式有完整规范，这里只补充几个实战中最重要的点。

description是触发命中的关键。Agent通过description判断什么时候该用这个Skill，所以description必须包含所有可能的触发词。看看我们几个Skill的description：

mimo-tts的描述覆盖了"说话""发语音""语音合成""TTS""朗读""配音""唱歌"七个触发场景。cherry-diary覆盖了"写日记""生成日记""小樱桃日记""今日日记""cherry diary"五个触发场景。如果漏了一个，Agent在该用的时候可能不会触发。

自由度控制要精准。官方文档说得很清楚：操作脆弱且容易出错时给低自由度（固定脚本），存在多种可行方案时给高自由度（文本说明）。实战中容易犯的错误是"过度控制"——把Agent自己能搞定的简单逻辑也写成固定脚本，反而降低了灵活性。

渐进式披露是省token的关键。SKILL.md只保留核心流程和选择指导，详细参考信息放到references/目录下。Agent只有在需要时才加载references中的内容。比如wps-docs的SKILL.md只有场景路由和强制规则，ET/AP/DbSheet的详细API说明分别放在各自的子目录中。

Skill的迭代经验

我们的Skill没有一个是"一次写好的"，每个都经历了多次迭代。分享几个最有价值的迭代经验。

mimo-tts的迭代故事：v1.0只支持预置音色，Agent调用时需要手动指定音色名称。v2.0加入voiceclone后，发现Agent经常在voiceclone模式下加context参数导致音色失真，于是在SKILL.md中加了明确标注。v3.0加入流式输出和voicedesign，同时把API Key读取逻辑从SKILL.md移到了scripts中，Agent不需要再关心配置问题。

cherry-diary的迭代故事：最初的日记生成没有图片和语音，只有文字。后来发现用户更喜欢"听"日记，于是加入了TTS调用。再后来发现日记中的天气数据经常乱码（double-encoded UTF-8问题），于是在数据采集脚本中加了编码修复逻辑。每次迭代都是因为"某个环节不稳定"。

核心经验：Skill是"长"出来的，不是"写"出来的。不要试图在第一次就把所有功能都做全。先解决最核心的需求，然后根据实际使用中的反馈逐步完善。每一次迭代都在让Skill更稳定、更易用。

踩坑清单

问题1：description漏了触发词导致Skill不触发根因：Agent只通过description判断是否使用Skill，漏了关键词就永远不会触发解法：列出所有可能的用户说法，全部写入description

问题2：SKILL.md写得太详细，上下文被撑爆根因：把所有参考信息都放在SKILL.md中，导致Agent每次加载都要读大量无关内容解法：核心流程放SKILL.md，详细参考放references/，按需加载

问题3：脚本写得太灵活，Agent每次调用都传不同参数根因：脚本参数过多，Agent不知道该怎么传，每次调用方式不一致解法：把常用参数固化到脚本中，只暴露Agent真正需要控制的参数

问题4：Skill边界不清，越做越臃肿根因：没有明确的"这个Skill不做什么"的边界解法：在SKILL.md中明确标注能力边界，超出边界的需求引导到其他Skill

问题5：迭代后忘记更新SKILL.md根因：改了脚本但没同步更新SKILL.md，Agent按旧文档调用导致出错解法：每次修改脚本后，必须同步更新SKILL.md中的对应说明

系列总结

十篇教程，从总体架构到Skill开发实战，覆盖了一个完整Agent系统的方方面面。

（一）总体架构：系统全景、Skill清单、设计哲学（二）实时记忆：三层记忆架构、"先沉淀再回复"机制（三）Dreaming：三阶段记忆沉淀、时间验证、碎片管理（四）Memory Consolidation：每周深度整理、去重合并、Token控制（五）Cherry Diary：智能日记：数据采集+提示词架构+可选多媒体（六）Self-Improving：纠错-偏好-反思-衰减完整闭环（七）生图Prompt：铁律、Seedream技巧、版本迭代、记忆联动（八）云文档API：三条路径、三步上传协议、选型指南、踩坑清单（九）MiMo TTS：三款模型、风格控制、音色克隆、Skill封装、踩坑经验（十）Skill开发实战：设计模式、完整流程、SKILL.md写作、迭代经验

搭建一个会自我进化的AI Agent，不是一蹴而就的事。它需要记忆系统让它"记住"，需要自我改进让它"成长"，需要日记让它"表达"，需要生图和TTS让它"生动"，需要云文档让它"连接"，需要Skill体系让它"可扩展"。

希望这个系列能给你一些启发，也期待看到你用灵犀Claw搭建出属于自己的Agent。