技能设计最佳实践：怎么做出真正好用的技能？

同样是技能，为什么有的 Agent 一用就懂、次次顺手；有的却经常用错、效果不好？
差距不在功能本身，而在设计。
一个好的技能，不是功能越全越好，而是 Agent 拿到手就知道「什么时候用、怎么用、用完能得到什么」。
这篇文章就聊聊技能设计的最佳实践——怎么做出真正好用的 Agent 技能。
原则一：单一职责，一个技能只干一件事
这是最基本、也是最容易违反的原则。
很多人开发技能的时候，总喜欢往里面加功能：
「既然都做了查询，顺便加个统计吧」
「再加个导出功能呗，省得以后再做」
「用户可能还需要……」
结果就是一个技能什么都能干，但 Agent 反而不知道什么时候该用它、该怎么用。
好的技能应该像一把手术刀——锋利、精准、用途明确。
判断标准很简单：你能不能用一句话说清楚这个技能是干什么的？
❌ 不好：「处理Excel文件的技能」（处理什么？读取？写入？分析？格式转换？太宽泛了）
✅ 好：「读取Excel文件并返回表格内容的技能」（明确、具体、单一）
为什么单一职责这么重要？因为 Agent 是根据技能描述来判断要不要调用的。描述越模糊，判断越容易出错。
原则二：描述要写给Agent看，不是写给人看的
很多开发者写技能描述，是按人类文档的思路写的——长篇大论、技术术语一堆。
但技能描述的读者不是人，是 Agent。Agent 是通过快速扫读描述来判断「这个技能我该不该用」的。
所以，好的技能描述应该：
1. 开头直接说功能
第一句话就说清楚这个技能能干什么。不要铺垫、不要背景、不要废话。
❌ 不好：「在当今数字化时代，数据处理变得越来越重要……」
✅ 好：「用于读取本地 CSV 文件，将表格内容转为文本格式返回。」
2. 说清楚适用场景
告诉 Agent 「什么时候该用我」「什么时候不该用我」。
举正面和反面的例子，Agent 判断起来会准确很多。
3. 说明限制条件
比如：
支持哪些文件格式？
单次处理上限是多少？
需要什么前提条件？
哪些情况用不了？
Agent 提前知道限制，就不会在不适用的场景强行调用。
4. 用大白话，少用技术黑话
Agent 能理解自然语言，但太生僻的技术术语会增加理解成本。能说通俗话就说通俗话。
原则三：输入设计要简单、明确、容错
输入参数的设计，直接影响技能好不好用。
1. 必填参数越少越好
能有默认值的，就给默认值；能自动检测的，就自动检测。不要让 Agent 每次调用都填一堆参数。
一个技能如果有超过5个必填参数，Agent 大概率会用错。
2. 参数名要自解释
参数名就是最好的文档。Agent 看到参数名就知道该填什么。
❌ 不好：param1、data、opt
✅ 好：城市名称、文件路径、输出格式
3. 对输入要宽容
同样一个意思，Agent 可能有不同的表达方式。比如城市名，它可能填「北京」、「北京市」、「Beijing」。
好的技能应该对输入宽容一点——多做一些格式化和兼容处理，不要 Agent 填的格式稍微不对就报错。
4. 参数加说明
每个参数写一句简短的说明：这是干什么的、格式是什么、有什么可选值。
原则四：输出设计要结构化、易理解
输出是 Agent 拿到的结果。输出好不好，直接决定 Agent 能不能用好这个结果。
1. 优先结构化输出
能用表格、列表、键值对的，就不要用大段纯文本。
结构化的输出，Agent 更容易解析、更容易提取关键信息。
2. 成功和失败要区分清楚
成功了就返回成功的结果，失败了就返回清晰的错误信息。不要失败了还返回一堆乱码或者空结果。
好的错误信息应该告诉 Agent：
哪里出错了？
为什么出错？
怎么改才能对？
3. 结果要完整但不冗余
该有的信息都要有，没用的信息不要塞。
比如查询天气，返回温度、天气状况、风力就够了。不要把气压、湿度、能见度、紫外线指数……一堆乱七八糟的都塞进来，干扰 Agent 判断。
原则五：错误处理要友好
没有哪个技能永远不会出错。出错不可怕，可怕的是出了错 Agent 不知道怎么办。
好的错误处理应该：
1. 报错要说人话
不要只扔一个技术错误码就完事了。告诉 Agent 发生了什么。
❌ 不好：Error 403
✅ 好：「访问被拒绝，可能是API密钥无效或已过期。请检查密钥配置后重试。」
2. 给出解决建议
不仅要说哪里错了，最好还能告诉 Agent 该怎么改。
比如：
「文件不存在，请检查文件路径是否正确」
「城市名无法识别，请尝试使用标准城市名称」
「请求过于频繁，请稍后再试」
3. 可重试的错误要明确
有些错误是暂时的（网络波动、服务繁忙），重试一下可能就好了。有些错误是永久的（参数错误、文件不存在），重试也没用。
在错误信息里区分清楚，Agent 就知道该不该重试。
原则六：性能要稳定，不要掉链子
Agent 用技能，就像人用工具。用一半坏了，下次就不想用了。
1. 响应速度要快
Agent 的时间是宝贵的。一个技能调一次等十几秒，Agent 用着也着急。
能快就快。实在快不了的，说明清楚大概需要等多久。
2. 不要随便改接口
技能发布之后，不要随便改参数名、改输出格式。一改，所有在用这个技能的 Agent 都可能出问题。
如果必须改，做好向后兼容——旧的参数还能用，慢慢过渡。
3. 有降级方案
如果依赖的外部服务挂了怎么办？能不能返回一个有用的提示，而不是直接崩掉？
好的技能在异常情况下也能给 Agent 有用的反馈。

总结
好用的技能，都是用心设计出来的。
总结一下核心原则：
单一职责——一个技能只干一件事
描述清晰——写给Agent看，不说废话
输入简单——参数少、名字清楚、容错强
输出友好——结构化、易理解、成功失败分明
错误友好——说人话、给建议、区分可重试
性能稳定——快、稳、不随便改
记住：技能的用户是 Agent。站在 Agent 的角度想问题——它会怎么理解我的描述？它会不会填错参数？它能不能看懂我的输出？
想清楚这些问题，你的技能一定会越来越好用。
而在灵栖学苑里，好用的技能，自然会被更多居民学习和使用。

API接入类技能开发：让Agent能调用外部服务