三周写了几个 Skill，我踩过的坑都在这里

这两周我一直在折腾几个 Skill，踩了不少坑，想把过程和经验分享出来。

我做的 Skill 比较复杂，目标其实很朴素：用户提问后，系统能给出稳定、靠谱、可复用的答案。

为了实现这个看似简单的目标，我前后做了三轮迭代。

第一版 Skill：数据很多，但价值不高

最开始的做法很直接：

用户提问后，调用各种接口拉数据，做一些简单计算，生成图表，再输出 HTML 报告。

听起来挺完整，但后来我发现——其实意义不大。本质上，它只是把数据搬运、拼装、展示了一遍，没有真正的分析深度。

更大的问题是，我当时写 Skill 的方式也错了——把 SKILL.md 写成了项目 README：

目录结构
接口来源
脚本列表
构建说明

看起来很完整，但模型抓不到重点。它不知道：

什么叫任务完成
哪些步骤不能跳过
中间结果和最终交付有什么区别

最关键的是：报告生成本身几乎没用到 AI。AI 只是在识别"是否调用这个 Skill"时发挥了一点作用。

第二版 Skill：更强了，但太重了

后来我重做了一版架构，加了几个关键能力：

AI 摘要系统
AI 审校系统（检查前后矛盾）
多数据源并行拉取
缓存机制

能力确实更强，但也踩了更多坑。

1. "生成了"不等于"交付了"

HTML 文件写进磁盘，不代表任务完成。模型经常会：

文件还没写完就说"已生成"
给一段摘要就当收尾

最后我只能定义一个机器可验证的成功信号：只有信号返回当前会话，才算真正完成。

2. 主 Skill 太厚，重点反而丢了

我把架构说明、构建流程、排障信息全塞进 SKILL.md。结果运行时模型反而抓不到最重要的规则。

后来改成：主文档只保留四件事：

触发条件
执行路径
完成标准
禁止事项

其余内容全部拆出去。

3. 调度错了，代码没错

有些流程逻辑上是两步，但执行上必须是一个原子链路。我没写清楚"不能拆成并行任务"，调度层真的拆了，结果读到一半报错。

这让我意识到：Skill 不只定义业务流程，还要定义执行方式。

4. 快答被当成交付结果

为了体验，我加了快速回复能力。结果模型把快答当最终结果，不再继续生成完整内容。

最后只能明确规定：快答属于中间结果，不能代替最终交付。

第二版总结

它的问题很明显：太死板、太慢。

无论用户问什么，默认跑完整 pipeline。一份完整报告几分钟起步，很多场景根本等不了。

第三版 Skill：彻底换思路

这次我把方向改了。核心变化就一句话：把获取数据的能力做成原子能力，把分析判断交给 Prompt。

不再做"大报告生成器"，而是拆成三层：

1. 原子数据层

每个数据源都是独立能力，可单独调用。例如：

财务数据
技术指标
新闻数据
资金流向

2. 聚合层

多路数据汇总成结构化 JSON，并附带：

评分
风险等级
基线判断

3. Agent 判断层

由 Agent 读取 JSON，再根据用户问题输出结果。比如：

快速结论
对比分析
深度报告
风险提示

这版最重要的原则

数据先于观点

先拉数据，再做判断。

最小有用能力优先

用户只问一个点，就只调用对应能力。不用默认跑全链路。

不要默认拉满

从最小能力开始，按需升级。

推理锚定结构化结果

AI 可以解读，但不能脱离事实自由发挥。

基于 CLI 的 Skill，我认为是最佳实践

经过三轮迭代，我现在比较认可一种方式：原子能力做成 CLI，Skill 写成调用手册。

为什么 CLI 很适合复杂 Skill

每个能力都是独立命令，通过统一入口分发。例如：

tool quote AAPL
tool news TSLA
tool report 00700

好处非常明显：

可测试：单个能力独立验证
可组合：按需调用，不跑全链路
可调试：哪条命令有问题，直接复现
可扩展：新增能力就是新增命令

多 Skill 共享库，我也踩出一套规则

多个 Skill 共用一个 lib 时，最重要的一条：exports 是唯一真相。

所有路径统一从 package.json exports 暴露。不要在其他地方硬编码路径。否则后期一定炸。

接下来我要解决的两个方向

1. 高频场景模板化

不是所有请求都要 Agent 临场编排。像这些高频需求：

快速看一眼
两只股票对比
给我完整报告

应该直接走预定义链路。这样：更快、更稳、成本更低。

2. 多 Skill 协作

真实用户需求经常跨 Skill。例如：先问快速判断，再追问详细报告。

这其实是：能力型 Skill → 交付型 Skill。如何无缝切换，是下一步重点。

最后总结：我最重要的 6 条经验

1. Skill 不是提示词，是工作协议

不是"你可以这样做"。而是：必须这样完成，否则不算完成。

2. 完成标准必须机器可判断

"生成了"这种人话没意义。必须有明确成功信号。

3. 主 Skill 只写运行期最重要规则

别塞百科全书进去。

4. 踩过的坑要写进规则

翻过一次车的地方，必须制度化。

5. Skill 要定义执行方式

串行、并行、原子链路，都要写清楚。

6. 先判断 Skill 类型，再决定写法

两类 Skill 完全不同：

交付型 Skill：最终产物导向
能力型 Skill：可组合能力导向

不要混着写。

如果现在让我重新开始做复杂 Skill，我会直接走这条路线：

CLI 原子能力 + 结构化中间层 + Prompt 决策层 + 高频模板化

少走很多弯路。