最近几个月我一直在折腾给智能体写 skill前后写过用于日志分析、代码评审、数据分析、文档生成的几十个。最开始完全是脚踩西瓜皮想哪写哪结果写出来的 skill 要么触发不了要么答非所问要么换一个场景就碎成一地。后来我慢慢总结出一套相对稳定的创建流程才算是把这件事从“玄学”变成了“工程”。这篇文章就是想把这套流程沉淀下来。我不会只给一个模板而是会讲清楚每一步背后的思考方式也就是标题里说的“方法抽象”把创建 skill 这件事拆成可重复、可验收、可复盘的动作最后附上一份可以直接拿来用的 Review 清单。无论你是在给 Claude Code、Codex、Trae 还是其他智能体工具做 skill这套方法论基本都能套得上。1. 先把概念理清skill 到底是什么很多人一上来就查“如何写一个 skill”但我建议先停下来搞清楚一个更基础的问题在你用的这个智能体平台里skill 到底是以什么形态存在的。1.1 skill 和 agent 的区别别混为一谈从最近的讨论热度看“skill 和 agent 的区别”是被问得最多的一个点。我自己的理解很简单agent 是一个完整的决策和执行实体它有记忆、会规划、能调用工具而 skill 是挂在 agent 身上的一块“能力模块”本质上是把某一类任务的做法打包成轻量级的方案让智能体在遇到对应场景时可以直接调用。用做饭类比agent 是厨师本人skill 是他的菜谱。厨师可以没有菜谱也做菜但有了菜谱遇到不熟悉的菜系时也能照着做出稳定出品。反过来菜谱再好没有厨师去理解、执行、临场应变它也只是一张纸。所以写 skill 的第一原则是不要试图把它写得像一个 agent不要给它规划复杂的工作流、记忆机制、多轮对话管理。skill 的目标是“在给定输入的条件下按约定规则输出可预期结果”。1.2 skill 的常见形态不同平台的 skill 在形态上差异挺大但扒掉包装核心组成部分就三块定义文件声明这个 skill 的标题、描述、适用场景、触发关键词以及它依赖的脚本或资源。比如 Claude Code 里的 SKILL.md、Codex 的自定义指令集、部分平台要求的 skill.yaml。指令正文告诉智能体遇到这类任务时应当遵循的处理步骤、约束条件、输出格式。这是最核心的部分也是大多数 skill 翻车的地方。可选资源范例、模板、脚本、参考文档。可以是一个 Python 脚本、一份 CSV 字典、一段正则表达式集合也可以是几份标准输出样例。“skill 脚本”这类热词搜得很多说明很多人把 skill 等同于一段代码。实际上脚本只是资源的一部分。更常见的 skill 其实可以没有任何代码纯粹靠指令文本也能生效。代码的作用是补足智能体文本推理的盲区比如精确计算、文件批量处理、正则匹配。2. 高效创建 skill 的完整流程我踩过最大的坑是“一上来就写正文”。你以为自己很了解需求其实只是被一个灵感击中。高效的做法是把创建过程拆成五个阶段每阶段都有明确的出口标准。2.1 阶段一需求证据收集不要凭想象定义 skill 要做什么。先回答四个问题这个 skill 要服务的真实场景是什么请举出一个具体的输入例子而不是抽象描述。现在没有 skill 时智能体做得怎么样差在哪里是乱猜格式、漏掉关键步骤还是输出太长你希望它稳定复现的正确输出长什么样哪些属于应该无条件遵守的规则哪些属于可以根据情况调整的偏好这四个问题的答案就是你 skill 的验收标准。我通常会把它们写进一个“需求卡片”甚至直接粘贴到 skill 文件的注释里作为开发期的参照物。2.2 阶段二定义触发条件与描述很多人忽略这一步结果 skill 写得很好但智能体就是不调用它。触发设置的核心原则是用“场景描述 关键词 反例”来锁定触发边界。在描述里写“用于日志分析”就不合格。更好的写法是description: 当用户提供服务器/应用日志文本或日志文件路径 并且希望定位异常、统计错误分布、分析时间线时使用。 适用于 nginx、Java 后端、Python 等常见日志格式。 不适用于用户需要自定义采集规则或非日志类数据分析场景。注意这里的“不适用”部分。给 skill 的描述写反例能显著降低误触发率。我在给 Codex 写 skill 时尤其依赖这个技巧因为它的上下文窗口有限宁可让 skill 少触发也不能让它在错误场景里抢走上下文。2.3 阶段三正文指令的结构化设计正文是 skill 的大脑。根据我拆解过的大量案例结构合理的指令正文通常包含五块角色和目标一句话说清让智能体以什么身份、达成什么目标。输入解析要求智能体先对输入做分类判断日志格式、数据类型、代码语言等再做后续处理。这一步是防止“模板化瞎答”的关键。处理步骤用编号步骤列出处理流程。每一条都要用命令式语言清晰无歧义。输出格式规定必须返回的结构最好给出一个简短的示例。让智能体照着格式填内容而不是自由发挥。边界与兜底什么情况停止、什么情况向用户澄清、什么情况直接报错。我还强烈建议在正文里写一句“思考顺序要求”。比如先阅读完整输入列出你识别到的异常关键词和可疑时间点 再基于时间线组织结论。禁止在未读完输入时给出推断。这句话看起来简单但它能有效压制智能体“边看边答”的毛病。2.4 阶段四用最小数据集试跑写完第一版不要立刻铺开用。先准备 3 到 5 个最小测试输入它们应该覆盖正常场景、边界场景、干扰场景。以日志分析 skill 为例用例类型输入示例期望输出正常场景一段含 Error、WARN、INFO 的日志按级别统计并输出 Top 异常边界场景空日志或只有一行日志给出“日志量过少”提示而非硬分析干扰场景日志中包含已标记的测试数据跳过测试数据并说明原因失败场景输入是配置文件而非日志识别为不支持类型并请求澄清我习惯把这些用例写成一个测试文件和 skill 放一起。后续每次修改 skill都把测试文件重跑一遍。这叫回归测试不复杂但极其管用。2.5 阶段五抽象沉淀形成可复用的范式这是“方法抽象”这个词真正发挥作用的地方。前四个阶段做完你得到的是一个具体的 skill。但如果你再往前走一步把这次创建过程中的关键决策提炼成一套“范式”下次写别的 skill 时就能少走弯路。我自己的做法是维护一份“范式笔记”里面记录了几种典型的 skill 模板解析分析类、生成创作类、代码改写类、信息抽取类。每类模板都包含通用的指令骨架和我踩过的坑。下次再遇到同类任务先复制骨架再填领域细节效率至少翻一倍。3. 实操演示从零构建一个日志分析 skill前面讲得再玄不如直接看一个完整例子。我用目前主流智能体都支持的目录式 skill 结构演示一个“应用日志异常分析” skill。你可以在 Claude Code、Codex 或任何支持加载本地技能目录的智能体里直接使用。3.1 目录结构设计log-analyzer/ SKILL.md rules/ context.md scripts/ level_stat.py examples/ normal.txt edge.txt failure.txt这里我把指令、规则和脚本分开而不是全部塞进一个大文件。这样做的原因是SKILL.md 越短智能体越容易完整读取和遵循。像“日志级别定义”“常见异常词典”这种偏知识的规则单独放在 rules/context.md 里需要时才引用能有效降低上下文占用。3.2 主文件 SKILL.md--- name: log-analyzer version: 1.2.0 description: 当用户提供日志文本或日志文件路径并且希望定位异常、 统计错误分布、分析时间线时使用。 支持 nginx、Java 后端、Python 常见格式。 不适用于自定义日志格式分析、非日志类数据分析。 trigger: - 日志 - log - ERROR - exception --- # Log Analyzer 你是一名经验丰富的 SRE 工程师。请基于用户输入的日志 完成异常定位与概要分析。 ## 输入解析 1. 判断日志格式nginx / Java / Python / 混合/未知。 2. 如果日志来源不明先让用户确认再继续分析。 3. 如果输入内容明显不是日志如配置文件、代码直接拒绝并说明原因。 ## 处理步骤 1. 按时间顺序切割日志。若日志缺少时间戳按行顺序处理。 2. 统计 INFO / WARN / ERROR / 自定义级别占比。 3. 筛选 ERROR 及 WARN 行提取异常关键词Exception、Timeout、Connection refused 等。 4. 根据关键词做初步归因输出可能的模块或原因。 5. 基于整个时间线生成结论发生顺序、持续时间、最严重事件。 ## 输出格式 输出必须包含以下四个部分顺序固定 ### 1. 日志概要 - 总行数、平均每分钟行数、时间跨度、级别占比。 ### 2. 异常列表 | 时间 | 级别 | 来源 | 异常摘要 | ### 3. 时间线分析 按时间顺序列出 3-5 个关键节点。 ### 4. 处理建议 给出可执行的下一步动作不要只说“需要进一步排查”。 ## 边界与兜底 - 日志行数少于 5 行提示“日志量过少”不强行分析。 - 出现 50% 以上未知格式行停止分析请用户确认日志来源。 - 严禁编造不存在的异常信息。无法判断时明确写“未知”。这份主文件涵盖了前面讲的五段式结构。第 3 步的“异常关键词归因”属于我特意留下的泛化项我把它指向 rules/context.md 中的词典这样不同系统只需替换词典内容就能复用 skill。3.3 知识文件 rules/context.md# 常见日志异常关键词与归因 - Timeout / timed out - 可能原因网络超时、DB 连接池耗尽、下游服务慢 - Connection refused - 可能原因服务未启动、端口被占用、防火墙拦截 - OutOfMemoryError / MemoryError - 可能原因堆内存不足、内存泄漏 - Permission denied - 可能原因文件权限、目录权限、服务账号权限 - NullPointerException / TypeError - 可能原因上游传参异常、配置缺失 # 日志级别定义参考 - DEBUG调试信息一般不必关注 - INFO正常流程记录 - WARN潜在风险不影响主流程 - ERROR功能失败或异常 - FATAL / CRITICAL系统级崩溃必须立即处理这里不是让智能体死记硬背而是给它一份“查找表”。真正写结论时它仍然需要结合日志上下文判断而不是直接复述词典内容。3.4 脚本 scripts/level_stat.py文本推理可以完成大部分工作但统计数字建议用脚本算避免智能体心算出错。import sys import re from collections import Counter level_pat re.compile(r\b(DEBUG|INFO|WARN|ERROR|FATAL|CRITICAL)\b) def main(path): counter Counter() total 0 with open(path, r, encodingutf-8, errorsignore) as f: for line in f: total 1 match level_pat.findall(line.upper()) if match: counter.update(match) print(fTOTAL_LINES{total}) for level in [DEBUG, INFO, WARN, ERROR, FATAL, CRITICAL]: print(f{level}{counter.get(level, 0)}) if __name__ __main__: main(sys.argv[1])脚本只做一件最擅长的事精确统计。SKILL.md 里应当写明“调用此脚本获取统计结果然后将结果填入输出格式”。这样智能体的任务是“解释数字”而不是“猜数字”。3.5 第一次试跑与迭代实录我用一份真实场景的测试日志跑第一版反馈很快暴露问题。第一版输出的异常列表里出现了“未知”的原因但这其实是一条自定义业务异常日志里根本没打错误码。我复盘时发现问题出在 prompt 没有要求智能体在无法匹配词典时进行“模式归纳”。于是我在处理步骤里加了一条3.5 若异常关键词不在规则词典中尝试归纳统一模式 并在结论中标注“词典未收录已按模式归纳”。第二次跑它对自定义异常的处理明显更接近人类工程师的思路。这个案例说明任何 skill 都不可能第一次就完美运行重要的是有一个可重复迭代的测试回路。4. Review 清单上线前如何系统化自检写 skill 写到一定程度你会发现最大的瓶颈不是“写不出来”而是“写出来之后不知道行不行”。我的解决办法是建立一份 Review 清单每次创建或修改 skill 后逐项自查。下面这份清单是基于我几十次踩坑经验打磨出来的现在每次发版前我都会过一遍。4.1 完整 Review 清单类别检查项检查要点触发描述是否“场景化而非关键词化”关键词会误杀场景描述才能命中精准场景触发是否写清了反例何时不应该被触发减少抢占上下文的概率指令角色和目标是否一句话说清做不到就说明目标定义含糊指令处理步骤是否可执行、无歧义别用“分析一下”这种动词要写“按时间线切割”指令是否有处理输入的“先分类再处理”环节没有这一步skill 就是个 prompt不是 skill输出是否定义了强制输出结构自由发挥是失控的开始输出是否提供最小输出示例示例比描述更有效边界空输入、极小输入、错误输入是否有兜底3-5 行日志也要能给出合理响应边界是否禁止编造信息必须有“无法判断时写未知”这条资源涉及计算是否给了脚本让智能体口算统计就是冒险资源知识类资源是否单独拆文件拆分层级降低上下文占用测试是否有最小测试集正常、边界、干扰、失败四类都要有测试修改后是否回归测试不回归你根本不知道改坏了什么安全是否会执行危险操作涉及删除、写入、调用外部命令时强调需用户确认安全是否会泄露敏感信息输出日志分析时不要附带原始完整日志除非用户要求4.2 怎么用这份清单这不是用来“看一眼”的而是要在发布前真正逐项打勾。我常用的流程是写完 skill 初稿放下至少半小时再拿清单自查一遍。冷处理能让你发现自己写得有多自嗨。把清单和 skill 一起丢给另一个智能体审查让它扮演资深工程师逐项给出评分和改进建议。这就是“用 agent 审查 agent”实测能抓出大量盲区。完成后跑一遍测试集确保四项用例全部通过。如果是团队协作让第二个人只读 output 格式和边界兜底因为这两块是全局最容易崩的地方。4.3 一个被 Review 清单拯救的真实案例有一次我给数据报表场景写“数据质检 skill”初稿时觉得自己写得挺顺。清单跑到“输出格式”这一项我突然意识到根据不同数据源的类型我的输出结构居然是不固定的同一份 skill 在不同数据源下会给出不同版式的质检结果。这会让后端解析流程完全失效。后来我改成“先输出数据源类型再根据类型模板输出固定结构”又临时加了两个不同数据源的样例。没有清单这个问题大概率会被我带进生产环境等到下游程序解析失败时才回头修。5. 常见翻车现场与排查思路再好的流程也防不住一些老问题。这里我把几个月来遇到最多的高频故障整理成速查表附带我的排查经验。5.1 skill 没有被触发这是出现频率最高的问题。如果你确认描述写得没问题先查三件事检查该平台的 skill 目录是否在有效路径下。很多平台只扫描指定目录文件放错位置描述写得再好也没用。检查描述里的关键词是否与实际输入措辞匹配。用户说的如果是“日志好乱帮我理理”那“日志分析”这个 skill 就可能不触发因为描述太书面化。解决方案是在描述里并列多个同义表达。检查平台是否限制了同时加载的 skill 数量。如果一次加载 20 个 skill上下文可能放不下你的定义排在后面的 skill 就形同虚设。5.2 skill 触发了但行为像普通对话这说明 SKILL.md 里的指令约束力太弱。最常见的原因是“处理步骤”写得太宏观智能体读完觉得和普通对话没区别。解决方式是将步骤具体到“指令级动作”比如“用脚本统计”“按时间线排序”“将结果填入表格”。另一个增强约束的办法是明确禁止事项。只写“你要怎么做”不够还必须写“你禁止怎么做”。比如禁止只输出结论而不展示依据。 禁止忽略 WARN 级别日志。 禁止使用“可能”这种模棱两可的判断除非确实无法定位。这类否定句能明显提高指令的约束力。5.3 skill 在一次运行中“人格分裂”我遇到过一种情况智能体在处理长日志时前面还在遵守 skill中间开始自由发挥结尾又想起 skill 规则。这个问题通常出现在指令文本过长时。智能体的注意力分配会让它只在开头和结尾记得规则。三个改进方向把核心规则压缩到开头 200 字内关键约束前置。在步骤中要求“每完成一步在结果前标注当前步骤编号”用强制输出锚点把注意力拉回流程。将长知识拆到外部文件只保留精简版指令在主文件中。5.4 遇到“skill 写好了但感觉不如直接对话方便”如果你的 skill 生产的结果还不如直接对话那要敢于承认这个场景可能不适合做 skill。我自己的判断标准是一个技能只有同时满足“频繁使用、规则清晰、人工操作步骤多、容错率要求高”四个条件才值得做成 skill。偶尔用一次、场景差异极大、自由度要求高的任务硬做成 skill 只会让你的智能体变笨。6. 最后分享两个打磨 skill 的小技巧一个是“样板输出法”。你不需要在指令里写复杂的格式化描述只需要给两份完整样例一份是“优秀输出”一份是“不合格输出”。智能体对例子的理解能力远超对抽象规则的理解能力。我现在大部分 skill 里都会放这两个样例效果立竿见影。另一个是“改一次测一次”的节奏。很多朋友喜欢一次性写上几千字然后幻想一次落地。但 skill 开发本质上是试错工程节奏应该是写完核心骨架就试跑发现问题只改一处再跑。循环三到五次之后skill 的质量会比一次写长文稳定得多。我自己现在的习惯是每次新建 skill 之前先翻开这本方法论笔记花五分钟填一下需求卡片、明确四类测试用例再动笔写指令。看起来是慢了一点但由于减少了返工和调试时间整体效率反而高了。希望这套流程也能让你的 skill 从“偶尔灵光”变成“稳定交付”。