在过去半年多的时间里，我开发了十几个 Agent Skill。这些 Skill 在 GitHub 上拿到过不少 Star，也有很多朋友在日常使用，给我自己的工作和内容制作带来了很大的提效。
在开发每一个 Skill 的时候，我都是把它当成一个完整的产品来做的。我们可以把 Skill 理解为运行在 Agent 上的软件：Agent 是操作系统，每一个 Skill 都是承担具体功能的软件。既然是软件，在开发时就需要带着完整的产品化思维，而不能只满足于在自己的本地电脑上能跑通。
很多人开发 Skill，可能只是写完在本地测试通过，或者顺手分享给身边的同事。但如果要真正做一个给其他人使用、而且大家用起来觉得稳定顺手的好 Skill，里面的细节其实很多。
Skill 的本质与快速生成的局限
Skill 的本质其实就是一个文件夹。这个文件夹里面通常包含几样东西：固定的工作流程、具体的执行脚本，以及提供给 AI Agent 参考的规范文档或背景知识。
想要创建一个 Skill，本身并不复杂。我们可以直接调用 AI Agent 里的 Skill Creator 工具，或者在执行完一段复杂的流程之后，直接告诉 Agent「帮我把这个流程创建为一个 Skill」。Agent 就会利用文件编辑能力新建目录、读取规范，把刚才执行过的步骤写进文档里。
但是这样生成的 Skill，往往只能算是一个基础骨架。目前大家使用的模型能力参差不齐，Skill Creator 更多只是给出了文件夹结构和基础规范。如果只停留在这一步，这个 Skill 距离真正分发给别人使用、达到好用的程度，还有很长的一段距离。
上手流程：别让模型直接去翻脚本源码
第一个常见的问题，是很多 Skill 根本没有设计上手流程（onboarding）。
比如我自己做过一个给视频加字幕的 Skill，叫做 oil-subtitle。这个 Skill 在转换音频的时候，需要调用百炼的 API Key。如果是在我自己的电脑上，环境变量早就配置好了，运行起来没有任何问题。但如果换到别人的电脑上，AI Agent 往往不会主动提前检查配置，直接调用脚本就会失败。
调用失败以后，弱一点的模型可能会去翻脚本的源码，试图分析为什么拿不到 API Key。但对 Agent 来说，它只需要调用脚本和读取规范，完全没有必要去读里面的实现细节。
比较好的做法是在 SKILL.md 里明确写清楚上手检查：第一次使用的时候，先检查项目里有没有对应的 API Key；如果没有，再提醒用户提供。
这里还有一个细节，就是尽量采用静默后置的处理方式。我们不需要让 Agent 每次调用 Skill 都先去检查一遍配置，因为大部分情况下配置一次就够用了。更合理的逻辑是让它正常执行，一旦遇到调用失败，错误信息里能够直接指引 Agent 去查看对应的配置说明，而不是让它自己去翻脚本猜原因。
稳定的步骤交给程序，变化的部分留给 Agent
在设计工作流的时候，我们要明确程序和 Agent 的分工：固定的、稳定的步骤尽量交给程序，需要灵活调整的部分再交给 Agent。
同样以生成字幕为例，整个流程有两种做法：一种是把模型调用内置到本地脚本里，Agent 只需要运行脚本，就能直接拿到带字幕的视频；另一种是让 Agent 自己去调用 API 获取转写稿，然后再自己逐行检查错别字。两种方式都能跑通，但把稳定步骤封装进脚本，执行起来会稳定得多。
另一个例子是自动发布视频的 Skill video-publisher。跨多个平台发布的流程很长，如果每次都让 Agent 用大模型一步一步去操作，不仅消耗大量 Token，执行速度也很慢。
一旦某套流程被完整跑通，我们可以让 AI 把它编写成 Python 或者 TypeScript 脚本。之后每次使用，Agent 只需要负责运行脚本，把当前 Skill 和其他流程串联起来。如果某天网页结构或者页面元素变了，脚本执行遇到问题，Agent 还可以临时介入做一层微调和兜底。这样既节省了 Token，又比单纯手动运行脚本省心很多。
考虑弱模型的承受能力：拆分文件与保留中间产物
我们在开发 Skill 的时候，往往会使用能力比较强的模型。强模型即使面对写得很乱、正文特别长、缺乏渐进式引导的 SKILL.md，也能在复杂的上下文里勉强把任务完成。
但如果换成能力弱一些的模型，可能直接就无法执行了。弱模型在面对过长的上下文时，指令遵循能力会明显下降；如果流程拆成了七八个手动的琐碎步骤，上下文一旦被压缩，模型就会忘记自己执行到了哪一步，导致执行路径跑偏。文档里多余的重复描述，也会进一步占用宝贵的上下文。
比如我之前做过一个生成 HTML 演示文稿的 Skill oil-ppt。如果把整份演示文稿的两三千行 HTML 代码全部写在同一个文件里，就会遇到两个很现实的问题：
- 第一，生成时间太长，连续生成两三千行可能需要四五分钟。中间一旦遇到网络波动，整个生成过程就会中断，前面的产物全部丢失，必须从头再来。
- 第二，文件太大之后，弱模型后期很难定位和修改。如果某处标签或符号被破坏了，让弱模型在一个几千行的文件里查找具体错误，失败率非常高。
针对这种情况，我们可以把每一页 PPT 拆成一个独立的 HTML 文件，最后再提供一个合并脚本，由程序自动把所有单页缝合成完整的演示文稿。这样每一页生成完都有独立的阶段性产物。就算生成到第六页时网络断开，前面已经做好的前五页依然保留着，重新运行只需继续生成第六页，不会丢失全部进度。
补充可视化页面与跨平台测试
对于一些需要人工确认或复杂操作的 Skill，我们可以给它提供现成的前端页面模板，通过数据注入来实现可视化预览。
比如在生成字幕的 Skill 里，我准备了一个包含字幕编辑功能的 HTML 模板。Agent 生成好初版字幕后，把数据注入模板，并在浏览器中打开页面。用户可以在右侧直接修改识别有误的字词，确认无误后点击「保存并关闭」。
Agent 检测到用户手动修改的内容后，会把最终字幕写入文件，同时把修改记录自动沉淀到「错题本」里。这种固定的可视化交互，比每次让 AI 临时编写一个界面要稳定得多，也能大幅提升复杂工具的使用体验。
另一个容易被忽略的问题是跨平台兼容。很多在 macOS 上开发的命令，在 Windows 环境下可能根本无法运行，不同系统的密钥存储机制也有区别。
我们可以在开发时让 AI 针对不同系统做兼容处理，并利用 GitHub Actions 等 CI 工具，在 Windows、macOS 和 Linux 环境下自动化运行测试，避免因为个人本地缺少对应设备而遗漏兼容性问题。
分发呈现与主观效果的无上下文对比测试
如果想把 Skill 真正当成产品，分发和推广也是必须考虑的环节。
我之前开源的一个 Skill，在两周内拿到了 2000 颗 Star。除了在社交媒体上的分享，GitHub 仓库的 README 也是经过认真设计的：顶部放了直观的 SVG 卡片，中间配了演示效果，文案尽量保持克制，不把过多琐碎的技术细节堆在外面，而是清楚说明这个工具能解决什么问题、具体怎么使用。如果大家想给自己的仓库制作类似的 SVG 卡片，也可以使用我开源的 beautify-github-readme。
另外，并不是所有 Skill 的输出结果都可以由程序或者模型自动量化。
字幕识别是否准确，AI 很容易判断；但如果是优化 UI 界面，或者调整文案让内容更有人味，结果就会比较主观。AI 本身很难客观评价一段文字到底有没有「AI 味」，因为那种生硬感往往就是模型自己带来的。
遇到这种主观场景，我们可以借助子 Agent（Sub-Agent）来进行无上下文的对比测试：
- 使用 Codex 编写完 Skill 后，启动一个没有任何历史上下文的子 Agent，让它读取这个 Skill 去完成一段文案生成或界面设计；
- 人工查看生成结果，提出具体的修改意见，并据此优化 Skill 的配置文档；
- 把 Skill 复制为原版和新版两份配置，同时派发两个无上下文的子 Agent 分别执行同一任务；
- 人工对比两组输出产物。如果新版确实比原版更好，就保留新版配置；如果效果没有提升，则继续调整。
工具沉淀与扫描自查
前面提到的这些关于上手流程、脚本分工、弱模型兼容、可视化页面、跨平台测试以及效果评估的心得，我都已经沉淀到了一个专门的 Skill 里，名字叫做 oil-skill-creator，放在 GitHub 仓库中。
我们可以让 AI Agent 安装这个 Skill，然后对本地现有的 Skill 进行一次全面扫描，通常能发现不少隐藏的设计和体验问题。