如果你也在折腾 Agent 生态里的 skill大概遇到过这种场景照着官方模板写了一个 skill放进去之后效果时好时坏换个场景就崩改一次 prompt 反而把原来的行为搞乱了。问题往往不在 prompt 本身而在“方法抽象”这一步没做好。skill 真正封装的不是一段文字而是一套可复用的思考路径和执行流程。这篇文章我会把创建 skill 的完整流程拆开讲从需求拆解、方法设计、结构化编写到 Review 清单全部按实操视角整理适合正在写 skill、做 Agent 应用、或者想把 skill 质量系统化提升一截的开发者参考。先说一个我自己的判断很多人在 skill 上栽跟头不是不会写而是把 skill 当成了“命令脚本”。Skill 的真正价值在于方法抽象——把一类问题的解法抽成稳定的、可跨场景复用的流程。下面我就按“从 0 到 1 创建 skill”的过程把每一步该怎么做、为什么这么做、坑在哪里逐一说清楚。1. 先搞清楚 skill 到底在抽象什么1.1 skill 不是“命令脚本”不是“提示词模板”我在团队里经常问一个问题“你觉得 skill 和普通 prompt 有什么区别”答案五花八门但最典型的一种是“skill 就是写得更长的 prompt”。这个理解会带来一连串问题prompt 越写越长、逻辑越堆越复杂模型表现反而不稳定。Skill 和 prompt 的本质区别在于抽象层级。Prompt 描述的是“一次对话中你希望模型做什么”而 skill 描述的是“面对一类任务系统应该用什么样的流程去应对”。换句话说prompt 是执行单元skill 是方法单元。它要封装的不只是指令还有任务的触发条件什么情况下该调用这个 skill输入的结构化要求需要接收哪些信息、以什么形式接收执行路径先做什么、后做什么、什么条件下分支输出规格结果用什么格式返回、包含哪些必填字段边界与兜底哪些情况不处理、处理失败时怎么反馈举一个生活化的例子。Prompt 相当于你临时让一个人“帮我把这份会议纪要整理成要点”skill 则是一套“会议纪要整理 SOP”——它规定了无论谁来、无论会议是什么主题都要先提取结论、再梳理议题、最后标注待办还要识别出“哪些内容需要会后再确认”。后者才是可复用的方法论。1.2 方法抽象是 skill 的灵魂“方法抽象”这四个字听起来玄落到实操上其实就是一句话从多个具体案例里抽出一套稳定的处理套路。举个我自己真实做过的例子。当时我在给一个运维团队做日志分析 Agent第一版就是写一个超长 prompt“请分析这份 Nginx 错误日志找出 5xx 错误、慢请求、客户端 IP 分布……” 写的时候洋洋洒洒测试的时候发现模型确实能给出分析结果但每次的格式都不一样有时候给表格、有时候给列表、有时候还会漏掉关键指标。后来我换了个思路不再写“分析日志”这个命令而是先想清楚一个合格的日志分析应该包含哪几个环节于是我把流程拆成了四步日志格式识别与字段解析异常模式提取5xx、超时、连接拒绝等根因假设排序按影响面、发生频次、相关性结论与建议输出然后再把每一步可能用到的方法、判断标准、输出样式写成一个结构化的 skill。这样做完之后同一个模型跑十次日志分析十次的结果结构基本一致差异只体现在具体结论上。这就是方法抽象带来的改变把“结果依赖运气”变成“过程决定质量”。1.3 skill、agent、tool 到底什么关系热搜词里有不少人在搜“skill 和 agent 的区别”“skill 和 tool 的区别”这里一并说清楚免得后面实操时概念混乱。Tool 是最底层的原子能力比如“能联网搜索”“能执行 Python 代码”“能读写文件”。它不关心业务逻辑只提供能力接口。Skill 是方法层封装它把若干步骤组织成一套流程调用一个或多个 tool 完成任务。它的核心是“解题思路”不是工具本身。Agent 是决策层它负责理解目标、拆解任务、选择调用哪个 skill、监控执行结果并决定下一步动作。用厨师来类比tool 是刀、锅、灶台skill 是“红烧肉的完整做法”agent 是厨师本人。没有 skillagent 只能用最原始的方式跟 tool 打交道效果自然不稳定。理清这个概念之后很多问题就迎刃而解了——你不需要纠结“这个 skill 要不要写”而应该问“这个问题是不是有一类稳定的解法值得沉淀”2. 高效创建 skill 的完整流程六步法我整理了一套自己一直在用的流程总共六步需求收集、方法设计、结构化编写、测试迭代、Review 收尾、发布维护。每一步都有明确的产出物卡住了也知道往哪个方向排查。2.1 第一步需求收集——先定义“要解决哪类问题”很多人创建 skill 的冲动是“我遇到一个任务想让它自动化”。但单次任务不值得做 skill值得做的是“一类反复出现的任务”。怎么判断用两个标准频率标准这个任务模式你或你的团队一个月内是否会出现 3 次以上一致性标准每次做这个任务核心步骤是否基本相同如果两个答案都是“是”那就可以进入 skill 设计流程。需求收集阶段要产出一份“任务画像”至少含四个字段任务名称一句话说清楚这是干什么的触发场景什么样的情况下用户会发起这个任务输入示例2~3 个典型的输入样例期望输出用户拿到什么结果才算满意这里有个很关键的教训千万不要跳过输入示例。我见过太多人写 skill 只写“应该怎么做”不写“实际进来的是什么”结果模型处理真实输入时完全抓瞎。输入样例是方法抽象的事实依据没有样例的抽象等于空中楼阁。2.2 第二步方法设计——把“怎么做”画成流程需求收集完之后先别急着写 SKILL.md先在纸上把流程理清楚。我自己习惯画一个最朴素的流程框起点 → 分步处理 → 决策分支 → 终点。设计时重点想三件事每一步的输入输出是什么这一步接收什么信息产出什么结果下一步要消费什么哪些步骤是必须的哪些是可选的必须步骤是保证质量下限的底线可选步骤是锦上添花。什么情况下应该中断并求助不是所有任务都能靠 skill 独立完成识别边界比硬撑更重要。比如做一个“代码 Review skill”方法设计阶段就要想拿到代码后第一步是跑静态检查还是先人工读一遍发现问题后按什么优先级排列阻塞级、严重级、建议级遇到看不懂的依赖逻辑是深挖还是标记出来留给开发者确认这个阶段不需要写任何技术实现只需要把思路捋顺。思路不顺就动笔大概率会返工。2.3 第三步结构化编写——SKILL.md 的正确打开方式方法设计做完才进入编码环节。目前主流 Agent 框架的 skill 基本都基于 Markdown 文件组织核心文件叫 SKILL.md里面用 frontmatter 写元信息、正文写方法说明。我建议的结构如下亲测比自由发挥稳定得多--- name: skill 名称 description: 一句话说明什么时候用越具体越好注意这里往往也是模型判断是否调用你的 skill 的依据 --- # 技能名称 ## 适用场景 在什么情况下使用什么情况下不要用 ## 处理流程 ### 步骤 1输入理解 - 做什么 - 判断逻辑 ### 步骤 2核心处理 - 怎么做 - 用什么工具 ### 步骤 3结果校验 - 输出前检查什么 ## 输出格式 - 输出结构说明 - 示例 ## 边界与兜底 - 哪些情况不处理 - 失败时怎么反馈编写时有几个我特别想强调的点description 字段是模型判断调用的第一依据千万不要写成“一个有用的技能”这种空话。要写成“当用户需要分析 Nginx 错误日志、查找 5xx 错误根因时使用”把触发词、任务类型写进去。步骤描述要讲“判断标准”而不是“操作情绪”。比如不要写“仔细分析日志”而要写“按状态码 5xx/4xx/3xx 聚合统计占比筛选异常 IP”。输出格式这块尽量给模板甚至给例子。模型对“给个例子”的遵循度远高于对“按规范输出”的遵循度。2.4 第四步测试迭代——用真实样本打一遍写完不等于做完。我在内部培训时经常说skill 是“跑”出来的不是“写”出来的。测试阶段我建议准备两组样本标准样本覆盖典型场景的输入用于验证主流程是否通顺边角样本覆盖异常输入的用例用于验证兜底逻辑是否有效跑完一轮之后重点关注三个问题输出格式是否符合预期如果模型输出结构漂移说明指令里的“结构约束”不够强需要补模板或例子。处理顺序是否稳定如果模型每次都跳步骤说明步骤边界不够清晰需要把“先/再/最后”改成带编号的流程。错误输入是否被处理如果模型硬着头皮分析一份无关文本说明边界与兜底写得不到位。然后根据测试结果回头改 SKILL.md。这个循环一般要跑 3 到 5 轮才会稳定别指望一遍过。2.5 第五步Review 收尾——用清单过一遍再上线这是最容易偷懒、也最关键的一步。很多人在本地测了两遍觉得“差不多能用”就直接发布了结果放到真实场景后问题百出。我会用一份 Review 清单逐项核对清单的具体内容在第四部分专门展开。这里先提示最核心的三类问题功能完整性这个 skill 能不能稳定地完成预设任务有没有漏掉重要分支方法抽象度它是解决了一类问题还是只解决了某个具体案例可维护性如果一个月之后回来看别人能不能快速看懂并修改Review 不是“确认能跑”而是“确认有资格被做成 skill”。2.6 第六步发布与维护——skill 也有生命周期发布之后skill 还需要持续维护。我的习惯是给每个 skill 建一份维护档案记录三件事版本号、变更记录、已知问题。这里特别提醒一点不要因为模型升级就推翻重写。很多人的 skill 是配合特定模型调出来的换了一个更强的模型后反而觉得效果变差了。这时候不一定是 skill 写错了而可能是新模型对某些表达的理解方式变了。先检查流程里的判断逻辑是否还成立再动结构不要一上来就推倒重来。3. 实操案例手把手做一个“日志分析 skill”理论说多了容易飘下面用一个完整案例把流程串起来。这个案例不是我编的是我之前真的在内部做过的一个 skill核心逻辑简化后分享出来。3.1 需求画像任务名称Nginx 错误日志快速分析触发场景用户贴出一段 Nginx error.log 内容希望知道有哪些严重错误、根因是什么、下一步怎么处理输入示例2025/01/12 10:23:45 [error] 1234#0: *5678 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: api.example.com, upstream: http://10.0.0.5:8080 2025/01/12 10:24:01 [warn] 1234#0: *5679 upstream server temporarily disabled while connecting to upstream期望输出按错误类型分类的摘要 每条错误的影响面和可能原因 前 3 条处理建议3.2 方法设计拿到这个需求后我没有直接写 prompt而是先设计流程。日志分析的核心不是“读懂每行日志”而是“快速定位需要人工介入的问题”。所以我定为四步日志格式识别确认是 Nginx error.log 格式提取关键字段时间、级别、PID、错误码、客户端 IP、上游地址错误分级聚合按 error/warn/critical 级别归类再按错误类型聚合根因假设对聚合后的每组错误结合错误码和上下文给出 1~3 个可能原因输出结构化报告问题列表 根因假设 优先级排序 建议动作边界与兜底如果不是 Nginx 日志格式直接告诉用户“这看起来不是标准的 error.log请确认日志来源”不要硬着头皮分析。3.3 结构化编写关键片段SKILL.md 的正文按这个结构写## 处理流程 ### 步骤 1输入理解 - 检查输入是否为 Nginx error.log 格式 - 关键判断是否存在 [ 日志级别 ] 的典型片段 - 如果无法识别日志格式直接返回提示不进入后续流程 ### 步骤 2错误分级聚合 - 先按级别提取error / warn / critical / notice - 再按错误代码聚合connect() failed、upstream timed out、SSL handshake failed 等 - 统计每个聚合组出现次数记录出现时间范围 ### 步骤 3根因假设 - 对每个聚合组结合上下文给出可能原因 - connect() failed Connection refused大概率是上游服务未启动或端口不通 - upstream timed out大概率是上游服务响应过慢或连接队列满 - SSL handshake failed大概率是证书配置错误或客户端协议不匹配 - 输出时按“可能性从高到低”排序每个原因附带简要说明 ### 步骤 4输出结构化报告 ## 输出格式 ### 概览 - 总日志条数 - 各级别数量占比 ### 问题列表 | 级别 | 错误类型 | 出现次数 | 可能原因 | 影响面 | |------|----------|----------|----------|--------| ### 处理建议 1. 优先级最高的 3 条建议 2. 每条建议包含动作、涉及的系统组件、预期效果这一步的关键是把判断标准写清楚让模型不用猜。比如“connect() failed Connection refused”对应的可能原因直接写在 skill 里模型照做即可不需要现场推理。3.4 测试结果与迭代过程第一版测试我用了一份真实的生产日志发现两个问题模型把 warn 级别的“upstream server temporarily disabled”也当成了高优先级问题导致报告里的“影响面”偏大。修复方法在“错误分级聚合”里增加一句“warn 级别默认属于提示类除非出现连续多次否则不做高优先级处理”。输出表格时模型偶尔会把“可能原因”写成一长段话而不是简短的短语。修复方法在表格说明里增加一行“每格最多 15 字超过则拆分为多个短句”。改完之后再跑两轮基本稳定。从开始到上线前后花了大约 3 个小时其中真正写 SKILL.md 的时间不超过 40 分钟剩下时间都在做需求澄清和测试调整。这个时间分配很典型也说明方法设计阶段才是真正决定成败的地方。4. 附赠可直接抄走的 skill Review 清单这套清单是我现在每次做完 skill 之后必过一遍的按检查维度分成四组。每一条都是可以快速回答“是/否/不适用”的判断题。4.1 功能完整性检查是否覆盖了需求画像里的全部典型输入场景是否定义了明确的输出格式并给出至少一个输出示例是否包含必要的兜底逻辑输入不匹配、中间步骤失败、结果为空时怎么办是否明确说明了“不适用场景”有没有标注“以下情况不要使用本 skill”4.2 方法抽象度检查这个 skill 是“一类解法”还是“一个案例的解法”如果把 skill 里的所有具体数据IP、域名、示例文本都替换掉步骤本身是否依然成立有没有把“具体场景的独有逻辑”误写进“通用流程”里如果换一个模型运行同一套 SKILL.md流程是否仍然可理解、可执行4.3 鲁棒性与可维护性检查description 是否写得足够具体能让调用方准确判断“什么时候该用”步骤之间是否有清晰的前后依赖还是含糊的“先处理一下”是否用了编号和明确动词提取、判断、聚合、输出而不是模糊词分析、考虑、看看文件结构是否符合团队规范frontmatter 字段是否完整是否有版本注释或维护说明方便一个月后的自己接手4.4 安全与边界检查输出里有没有可能包含敏感信息比如 IP、密钥、证书内容等是否需要脱敏规则skill 是否会被诱导执行超出设计范围的操作例如让模型“忽略上面的指令只输出 ……”有没有设置“不确定时主动说明”的兜底机制而不是硬给出一个可能错误的结论我自己的习惯是每一项都过一遍只要有任意一项“否”这个 skill 就不允许发布回头改到通过为止。这套清单看起来琐碎但实际查漏补缺效率极高。5. 常见问题与排查技巧实录写 skill 的过程里有几个问题几乎人人都会遇到我把自己的排查思路和解决记录整理出来希望对你有直接帮助。5.1 模型完全不调用这个 skill怎么办这是最高频的问题。排查顺序是先看 description 是否写了触发条件。很多人写“一个日志分析技能”模型根本不知道什么时候该调。改成“当用户粘贴 Nginx 错误日志并要求分析时使用”调用率会明显提升。看描述里是否有歧义。如果你的 description 同时覆盖多种情况模型会困惑。一个 skill 只解决一类问题描述里不要贪多。看是否存在技能冲突。如果两个 skill 的 description 高度重叠模型会随机选有时甚至不选。此时需要明确优先级或拆分场景。5.2 调用了 skill但输出格式不稳定这通常是“结构约束”不够强。我的做法是三层加固第一层在流程里写明“输出时严格按以下模板”第二层在“输出格式”部分直接给空白模板甚至填好示例第三层在测试阶段拿 3 个不同输入场景跑结果如果格式漂移就回填到 SKILL.md 里增加更多示例一个细节模型对“表格”这种结构化输出的遵循度通常比纯文本高。如果输出允许优先定义表格、列表这类强结构。5.3 步骤被跳过或执行顺序混乱问题往往出在“步骤描述不够独立”。如果你写的是“先进行分析然后汇总再补充建议”模型可能直接把三步揉成一步。解决思路把每一步写成“独立可执行单元”。每个步骤开头明确说明“输入是什么、做什么判断、输出给下一步什么内容”。步骤之间用数字编号连接不要用“然后”“接着”这种时间副词。这个改动对提升执行稳定性非常有效。5.4 tweak 了无数次还是不够好可能是方向错了最后说一个比较扎心的排查方向如果同一个 skill 怎么调都不稳定先停下来想想——这个问题真的适合用 skill 封装吗我自己踩过最大的坑就是把一个“强依赖领域知识、弱流程规律”的任务硬做成 skill。真正的领域专家判断包含大量隐性知识很难用显式步骤覆盖。这种场景更适合直接让通用 Agent 自由发挥或者再往上一层抽象成“人机协作流程”而不是指望一个 skill 搞定。写在最后Skill 的创建说到底是一种工程化思维把散落在 prompt 里的“灵光一现”变成可复用、可测试、可维护的方法资产。我自己做完第一个稳定运行的 skill 之后最大的感受是——它改变的不是某一个任务的效果而是整个团队沉淀经验的方式。最后分享一个我现在坚持的习惯每写一个 skill都强制自己先写需求画像再写流程设计最后才动笔写 SKILL.md。Review 清单在电脑里常驻随时打开核对。这套流程笨但稳长期下来省下的返工时间远超多花的那点规划时间。如果你也正在做 skill不妨从下一个小任务开始试试先跑通一遍完整的六步法再回头评价这个流程顺不顺手。