最近有个朋友找我帮忙看 skill说“我照着网上模板写了不少怎么关键时刻一个都用不上”这个问题我太熟了。大半年里我一直在折腾各类 Agent 工具里的 skill从最初把它当“高级提示词收藏夹”到后来慢慢沉淀出一套自己的 skill 方法论中间踩过的坑足够写满一页 A4 纸。今天不聊某个具体工具的配置细节就聊两件最值得聊的事第一大家天天挂在嘴边的“方法抽象”到底在抽象什么第二我现在创建和复查一个 skill 的完整流程以及一张可以直接拿去用的 Review 清单。先说一个基本判断大多数人写不好 skill不是因为不了解格式而是没想清楚 skill 到底是什么以及“抽象”这两个字到底意味着什么。1. Skill 究竟是什么先把它和 Prompt、Script、Agent 分清楚我看到太多人把 skill 理解成“一段写得特别详细、效果特别好的提示词”。这个理解方向是对的但不够精确。Prompt 的本质是“一次性把事情说清楚”而 Skill 的本质是“让 Agent 稳定地解决某一类问题的一套能力封装”。它和 Prompt 最核心的区别不在内容长度而在有没有“契约”。什么叫契约就是一个 skill 必须明确回答四件事什么情况下被调用、接收什么输入、按照什么步骤执行、产出什么形式的结果。我见过很多失败的 skill通病就是四个问题里只回答了第三个——“按什么步骤执行”其他三个全是模糊的。再把它和 Script、Agent 做个对比就更清楚了。这里我用一张表把常见概念一次性捋明白维度PromptSkillScriptAgent本质一次性指令可复用能力封装确定性程序自主决策主体可被调度性否靠手动是运行时动态匹配是由调用方触发是自我决策输⼊输出契约无有明确契约有接口定义有目标定义抽象程度低中高高高失败时表现重来一次按契约修正报错自主换策略Script 是确定性逻辑条件到了就会执行而言 Skill 更像是一份“给 Agent 的操作指导书”它可能包含脚本调用但骨架是解决问题的思路不是一段死代码。Agent 就更不同了Agent 是那个负责决定“要不要用这个 skill、怎么把多个 skill 组合起来”的调度者。Skill 只是 Agent 工具箱里的一把专用工具。拿现实里的角色打个比方Prompt 就像你跟一个实习生说“帮我把这份数据整理一下”Skill 则是你给实习生一本《数据整理作业指导书》里面有数据来源、字段规则、异常标记方法、输出模板、验收标准。实习生可以照着作业指导书做出稳定结果而不是每次靠临场发挥。这就是为什么很多刚上手的人觉得“我按格式写了但效果还是看运气”。因为如果只有指导步骤、没有契约边界Agent 每次执行时都会把“怎么理解输入”“什么算好结果”重新想一遍结果自然飘忽不定。搞清楚这个概念之后我们才能接着聊“如何设计”这个更关键的问题。2. 方法抽象你的 Skill 不好用缺的不是技术是这层思考“方法抽象”这四个字听起来玄其实就是一句话从一大堆具体做法里抽出那个无论输入怎么变都成立的处理骨架。专业选手和业余选手的差距往往就在这里。举一个看着很普遍、实际很典型的失败案例。有人想写一个翻译类 skill一上来就写“遇到法律合同用正式语气遇到技术文档用严谨表达遇到营销文案要生动活泼”越写越多十几个分支累到不行。但做完发现换一个稍微偏门的领域它立刻卡壳。为什么因为这个设计把抽象对象搞错了——翻译任务的骨架不是“按领域分类”而是“理解原文→识别文风与约束→转换语言→校验保真→输出”。领域只是其中一个可变点却被当成整个骨架来搭等于把楼盖在了沙地上。我当时做日志分析 skill 时也差点走这条路。刚准备动手脑子里蹦出来的想法是“nginx 日志怎么解析”“Java 异常堆栈怎么提取”“MySQL 慢查询怎么判断”每样本事都想来一个单独的 skill。后来我停下来逼自己先想一个问题这些日志虽然格式各异但共有的处理结构是什么答案是识别来源→截取有效段落→字段化→过滤噪音→聚合统计→输出结构化报告。我只要把这个骨架定住nginx、Java 异常其实都只是“识别来源”这一环的不同参数。这套东西拆开来看就是三个层次的抽象任务抽象。这一层解决的是“这是哪一类事”不是“这是哪一件事”。写日志分析 skill 时你的对象是“一切需要从原始文本日志中得到结论的任务”而不只是“nginx 日志”这一个子集。动作抽象。把完整过程拆成一组原子动作每个动作都有明确的输入和产出。比如“把日志字段化”和“按时间窗过滤噪音”是两个动作它们之间不能互相纠缠。反馈抽象。把“什么叫做好结果”从隐性感觉变成显性检查条件。很多老师傅做得好但带不出徒弟就是因为反馈标准只在他脑子里“这个看着就不对。”好的 skill 要把这种直觉翻译成可检查的语句比如“统计结果必须能追溯到原始日志条目”。判断抽象是否达标我有一个很实用的标准如果给 skill 增加一种新的输入类型你需要改动的是核心步骤那说明骨架搭错了如果你只需要在某个可变点上扩展一个选项那说明抽象到位了。拿日志分析来说接一种新日志格式你只需要新增一条“来源识别规则”核心聚合逻辑完全不用动——这就是抽象的价值。抽象没做对写得越多越脆弱抽象做好了skill 才有复用的底气。3. 高效创建 Skill 的六步流程从“我想做个 skill”到“能稳定用三个月”这一节讲流程。我现在的流程一共六步每一步都有明确产物不玩虚的。3.1 需求澄清动手之前先回答五个问题很多 skill 死在起点不是写的人不会写而是没搞懂自己要做什么。我给自己定了五个必答题答案写不清楚就不开工。这个任务是不是高频重复如果它只出现一次别做 skill直接解决就完了。输入长什么样哪种形态必须接受哪种形态要明确拒绝输出给谁用是给人看报告还是给另一个 Agent 继续处理还是要落成文件什么样的结果算“好”写得出可检查的指标吗这个 skill 会不会和已有效能冲突会不会抢同一个场景为什么这些问题是必要的因为 skill 是有边界的没有边界的 skill 就像没有围栏的停车场什么车都往里停最后谁都找不到自己的车。最典型的例子我见过有人写“代码审查 skill”结果别人拿它去生成代码生成结果当然一塌糊涂这不是 skill 烂是它压根没声明自己不是干这个的。3.2 经验还原把你脑子里的隐性能过程榨出来方法抽象的原料不是你坐在电脑前拍脑门编的而是从真实的操作过程里挤出来的。我发现最有用的做法是“过程访谈”找一个在这个任务上做得又快又稳的人多数时候就是你自己让他开着录屏做一次真实任务边做边说“我为什么在这里停顿”“我看到什么信号会拐弯”“哪些情况我会直接放弃”。录完之后不要急着写先整理一个“过程访谈表”把对方的隐性判断显性化任务目标是什么拿到的输入样例长什么样你在哪一步看到了什么关键信号对应做出什么操作你的判断标准是什么遇到过哪些意外情况这个表我用了很久实践下来效果很好。通常只需要访谈三五个真实任务处理骨架就会自己浮出来因为你会发现不同任务里反复出现的动作就是骨架偶尔变化的判断点就是可变点。3.3 步骤切片把动作拆到“一眼能看懂、一句能执行”访谈记录往往很乱因为人类做事不会按照清晰步骤来脑子里常常几个任务并行。这时候需要做切片把所有动作拆成原子步骤每个步骤满足两个条件——一个正常人能一眼看明白能用一句话说清楚输入和产出。举个例子。原始过程记录可能是“我拿到日志先大概扫一眼看是访问日志还是错误日志然后 filter 掉健康检查的噪音再看几个关键指标最后写个总结”。切片之后就变成读取全部输入日志文件。识别日志来源类型nginx / Java 异常 / 其他。按来源执行对应字段化解析。过滤健康检查等噪音条目。按时间窗和关注维度聚合统计。输出结构化报告。切片的目的是让每一步都能被 Agent 稳定执行。如果某一步还包含“大概”“差不多”这种词就说明它还没切到位。3.4 抽象建模确定稳定骨架、可变点和触发条件这是整个流程里的核心技术活。拿到切片后的步骤你要区分哪些是稳定骨架、哪些是可变点。稳定骨架是任何输入都必经的路径可变点是只影响少数情况的处理分支。回到日志分析的例子“识别来源→字段化→过滤→聚合→输出”就是稳定骨架“nginx 日志按 socket 聚合Java 异常按堆栈类型聚合”就是可变点。建模时骨架用写死的步骤描述可变点要在步骤里标注“可选”和判定条件。这一步的产物是一个清晰的结构化定义类似下面这样name: log-analysis-skill description: 对任意来源的日志文本执行聚合分析输出结构化报告 input: - log_paths: 日志文件路径列表必填 - time_range: 可选限定分析时间窗 - focus: 可选指定关注维度如错误率、耗时分布 steps: - 识别日志来源与格式 - 按来源规则字段化并统一 schema - 过滤噪音条目与敏感信息 - 按 focus 执行聚合统计 - 生成结构化报告并附原始日志溯源 success_criteria: - 覆盖所有输入日志文件 - 每个统计结果均可溯源到原始条目 - 输出格式符合消费方约定到这一步skill 的骨架才算真正定形。3.5 原型验证第一版只需要跑通“最典型的那个输入”很多人写完 skill 的第一版就想追求完美结果改了三天还在改。我的建议是第一版的目标只有一个——跑通最典型的那一个输入。把最常见的输入丢进去看输出的质量能不能打六十分。如果连典型输入都跑不通不要急着扩场景先修核心步骤。只有典型输入稳定了才开始加第二类输入、第三类输入每加一次都重新跑一遍老用例确保没有回退。这个阶段我习惯用“铁三角”方式验证固定一个测试输入集跑一次记录输出和上一次对比。凡是影响输出的改动都要说明为什么改、预期产生什么变化。没有这个过程skill 很容易变成“这次能用下次不知道行不行”的玄学状态。3.6 文档与验收skill 写出来只是开始能看懂才算完成最后一步最容易被忽略写文档。没有文档的 skill 是负债不是资产——半年后你自己都看不懂当初为什么这么写更别说让其他人接手了。我的文档模板固定包含六块适用场景、不适用场景、输入格式示例、输出格式示例、已知限制、变更记录。其中“不适用场景”这块特别重要它直接决定了 skill 不会被乱用。很多人写文档只写“我多厉害、我能做什么”却不说边界在哪结果 Agent 拿到一个不该它处理的任务时硬着头皮做出来一个垃圾结果反而拉低信任分。验收时我会再过一遍需求澄清的五个问题逐一确认当时的设想是否真的落实了。这步做完一个 skill 才算真正可以交付。4. 我实际在用的 Review 清单六个维度逐条过流程跑完不代表结束我每次创建或者大改一个 skill 之后都会用一张 Review 清单从头到尾过一遍。这张清单经过多次迭代现在稳定在六个维度。4.1 正确性输出真的对吗先不看花样只看结果。用三组不同类型的真实输入跑一遍逐条核对输出与预期是否一致。这里有个容易被忽略的细节要让不了解这个 skill 上下文的人帮忙看输出而不是自己看。设计者天然容易高估自己的输出质量旁观者一眼就能看出问题。4.2 抽象度是稳定骨架还是场景堆砌回到第二章的标准问自己新增一类输入时需要改核心步骤吗如果答案是“要”说明抽象度不足要回到建模环节重构。另外一个常见问题是过度抽象——把八竿子打不着的任务硬塞进一个 skill结果内存里有几十个用不到的分支。好的抽象应该像一把可调扳手而不是一套万能钥匙。4.3 鲁棒性异常输入是否被处理这个维度我最常被问到也最容易踩坑。检查三点空输入时skill 会不会明确报告“没东西可做”格式不符合预期的输入是会明确拒绝还是会硬解析出错误结果当输入里混着多种类型、但 skill 的契约只接受一种时会不会主动识别并提示沉默失败比报错更可怕。一个优秀的 skill遇到自己不擅长、不该处理的输入时应该大声说出来这不在我的能力范围内。4.4 可维护性两周后你自己还看得懂吗把自己代入两周后、项目全忘光的状态打开 skill 文件重新读一遍。读的过程中记录所有“这里为什么要这样写”的疑问如果疑问过多说明文档和结构还不够清晰。可维护性的金标准是一个不了解背景的新手只看你的文档就能正确使用、修改、扩展这个 skill不需要发消息问你。4.5 复用性换个上下文还能用吗同一个 skill从“项目 A 的日志分析”换到“项目 B 的日志分析”需要改多少东西如果只是改两个参数复用性合格如果需要改核心步骤那说明它太绑定了具体项目。很多人的 skill 其实只是一段“半成品项目代码”换个场景就废就是因为当初没有做方法抽象直接拿具体项目当通用能力用了。4.6 安全与成本会不会让 Agent 干出危险事或者烧太多资源这一条也是我后来才补上的。skill 里如果有执行 shell 命令、写文件、调用外部 API 的动作要想清楚这个动作是否有权限边界是否可能被恶意输入诱导执行前是否需要二次确认成本方面如果 skill 的逻辑链太长、步骤太多每次调用都消耗大量 token 和时间那它再准确也不实用。我个人的习惯是一个 skill 的完整执行路径里必须至少留一个“轻量版本”的选项能快速给出低精度结果。下面是我笔记软件里长期置顶的那份 Review 清单原文你需要的话可以直接复制三组真实输入测试输出找不了解上下文的人帮忙评审。新增一类输入核心步骤是否需要改动需要则重构。空输入、格式错误输入、混合输入三种异常是否都被明确处理假装自己两周没碰过这个 skill按文档能否顺利使用、修改、扩展换到另一个同类项目改动成本是“改参数”还是“改步骤”所有执行动作是否有权限边界是否需要二次确认是否有低成本运行选项这六条看起来简单但我可以负责任地说我见到的九成以上问题 skill都能在这六个维度里找到病根而且往往是 2 和 6 这两个维度出的问题。5. 踩过的三个坑和一个我坚持到今天的小习惯最后分享一点相对私人的东西都是我真实踩出来的教训。第一个坑是贪大求全。我最早写 skill 总想一步到位希望一个 skill 能解决所有相关场景。结果就是步骤里塞满各种判断分支骨架被压得七零八落改一处牵扯一堆。后来我学乖了每个 skill 只解决一类问题哪怕场景窄一点先把正确率做到九十分再谈扩展。第二个坑是只测 happy path。早期写代码审查类 skill我用理想输入测了几遍感觉完美结果一到真实场景就崩。原因是真实输入几乎都带着杂质有的是噪音信息有的是格式不规范有的是内容本身有问题。后来我把“异常输入怎么处理”提到最前面先设计好拒绝和降级路径再填主路径整个 skill 的稳定性上了一个台阶。第三个坑是写完就忘。早先没有文档意识写完之后过一个月自己都看不懂那个断言条件为什么要那样设。后来我养成了记录习惯每个 skill 必须留下变更记录哪怕只写一行“为什么这次要改”也能在下次排查时省下大量时间。至于那个我坚持到今天的小习惯其实很简单每次使用 skill 之后顺手记一句话。记“它在什么输入下表现好、什么输入下表现差、我当时怎么改的、结果如何”。这句话不在文档系统里而是在我的灵感速记里但每次迭代 skill 时它都是我最重要的输入源。好的 skill 不是一次写出来的而是靠一次次真实反馈磨出来的——这大概就是“方法抽象”落到实处后最朴素也最可靠的样子。