最近这段在折腾 Agent 和 AI 编码流程我最大的感触是光有一堆工具不够。MCP 服务装了一堆编辑器插件拉满模型也换成了最新版但每次处理同类任务还是要从零开始把背景、要求、输出格式重新讲一遍。直到我把重复三次以上的高频动作一个个沉淀成 Skill情况才真正开始改变。Skill 不是什么玄乎概念。你翻开源社区Claude Skills、Codex Skills、各种 Agent Skill 叫法不同核心思路几乎一致用一份SKILL.md、几个脚本、几组真实示例把“零散的动作”固化成“可复用的业务能力”。这篇文章我不打算讲一堆空概念直接从一个我自己打磨过的日志诊断 Skill 出发拆开聊聊为什么要做 Skill、怎么写才不翻车、以及怎么让 Skill 真正在团队里长出生产力。适合正在用 AI 工具解决实际问题、又不想每次手动喂上下文的人。1. Skill到底是什么为什么工具堆满还是不够1.1 你缺的不是工具是“动作序列”现实里的绝大多数工作都是长链条的。问题来了先取数据再过滤噪声然后做判断最后形成结论和下一步动作。这个链条上每个环节都有现成工具日志平台能查数据jq 能过滤 JSONgrep 能捞关键字大模型能帮你分析原因连 PPT 都能靠插件生成。但问题在于工具本身是“原子能力”而业务交付的是“分子级动作串”。举个例子线上服务报错日志里堆满了异常。给我一整套行业里最全的工具链我依然要做的是先把日志复制出来定位时间窗口再看 ERROR 级别行的上下文接着判断是超时、依赖挂了还是代码逻辑问题最后写一段给开发看的建议。中间每一步都可以靠工具加速但这整串动作本身没有固化成任何可以被 AI 直接调用的东西。于是每次告警来了我都要重新复制背景、重新告诉模型“先看什么、后看什么、结论写成什么格式”。这不叫效率这叫反复造轮子。1.2 Skill的本质可执行的“手法说明”那 Skill 到底长什么样如果你拆开一个 Claude Skill 或 Codex Skill大概率会看到类似结构my-skill/ ├── SKILL.md ├── scripts/ │ ├── preprocess.py │ └── report.py ├── examples/ │ ├── case_01_input.log │ ├── case_01_output.md │ └── ... └── references/ ├── error_codes.md └── changelog.mdSKILL.md是模型要读的第一份资料用来告诉它“什么时候用这个能力、按什么步骤执行、输出格式是什么”。scripts/放真正能跑的脚本承担日志过滤、数据提取、格式转换这些脏活累活。examples/放几组真实的输入输出案例给模型当“模仿样本”。references/放错误码表、业务术语、历史复盘等补充知识。SKILL.md不是把一个长 Prompt 改个名字那么简单。普通 Prompt 是一次性的文本指令用完就没了Skill 则是能被 Agent 平台加载在指定场景里稳定生效的“操作手册”。它既有“怎么说”也有“怎么执行”还有“怎么验收”。1.3 没有Skill团队经验只能靠人肉传承我见过不少团队工具买了、模型也接入了但生产力还是卡在几个关键人身上。原因很简单个人经验都藏在聊天记录里藏在某个人的脑子里没有变成组织能读到的文件。Skill 的价值恰好在这里。当一段处理经验被写成目录、放进 Git、配上示例它就从一个“这次处理得不错”变成了“下次遇到同类问题可以稳定复现”。这也是为什么 Skill 能比工具更进一步工具提供能力Skill 沉淀方法。方法才是业务能力的真正载体。1.4 不是所有事都值得做成Skill开始动手前最好先有个判断标准。以我自己的经验值得做成 Skill 的任务通常满足三条高频一周至少重复两三次甚至每天都要做。流程相对固定步骤可以拆出来输入输出边界比较清楚。输出有结构结论可以被复用比如写成报告、表格或后续动作清单。用一张表来区分会更直观类型适合做成 Skill不适合做成 Skill典型场景错误日志初步定位、周报复盘生成、代码变更检查、固定格式的文本抽取头脑风暴、短视频选题创意、个人审美风格设计原因动作可拆、标准可定、结果要复用过于开放、主观判断强、每次差异大例子“拿到一份服务日志快速告诉我可能原因和下一步排查点”“帮我想一个六月营销活动主题”2. 如何写一个能落地的Skill五步拆出一个完整案例2.1 第一步锁定一个一周至少重复三次的场景很多人学 Skill 做 Skill一上来就想搞一个“万能助手”结果做出来的东西什么都想管什么场景都触发最后在任何一个场景下都不可用。我建议反过来先找一个扎到疼的场景。我当时选的是“线上服务日志异常初诊”。判断依据就三条次数多告警基本每天都有每条都要人工先看一遍日志。重复度高每次做一样的事——捞日志、过滤关键字、找堆栈、匹配错误码。翻车成本高漏掉关键上下文很容易把一次误报当成故障或者把真正根因掩盖过去。这个场景价值感极强做完之后立刻能看到效果也就有动力持续迭代。2.2 第二步把自己当成“被观察的熟练工”这个阶段先别写文档先老老实实走一遍人工处理过程。我对着真实日志完整跑了一次记录了自己大脑里的决策路径先把整个日志文件拉出来但不会直接看先用 grep 找出所有包含ERROR和Exception的行。再看这些错误在时间轴上是否集中如果集中在几十秒内大概率是外部依赖或流量冲击如果分散出现可能是偶发故障。找到第一个能定位问题的栈顶行通常是业务代码入口。根据错误码去对照历史经验判断是超时、连接被拒、还是资源不足。最后输出结论最高概率原因、次要可能、建议看哪段代码或哪个监控面板。这个动作清单看起来朴素但它就是 Skill 的原型。所谓固化就是先把自己脑子里的流程“翻译”成别人也能照做的步骤。2.3 第三步把能脚本化的事情尽量放进脚本很多 Skill 新手会犯一个错误SKILL.md 里写满了“你要仔细分析日志”“你需要结合上下文”然后就没有然后了。更稳的做法是能用代码确定性完成的事就不依赖模型临场发挥。我当时写了一个preprocess_log.py它会自动做这些事情过滤出 ERROR、WARN、Exception 等关键行提取每行的时间戳、日志级别、服务名、错误码截取异常堆栈的第一段去掉无意义的内部框架输出一份统一格式的 JSON 给模型。这样做的好处是模型拿到的不是一份几千行的大日志而是一张经过结构化处理的“问题摘要表”。模型只需要在有限的候选集里做推理判断不需要从零开始大海捞针。脚本负责确定性模型负责判断性两者配合才稳定。2.4 第四步写SKILL.md把流程和触发条件同时钉死SKILL.md是整个 Skill 的驾驶舱。它不能只讲“你要怎么分析”还必须在开头写清楚“什么时候调用这个 Skill、什么时候不调用”。我常用的开头格式是这样的--- name: triage-server-log description: 当用户提供服务器错误日志或日志文件路径要求定位线上故障原因时使用。适合排查超时、依赖异常、空指针等常见问题。不适合做日志格式整理或代码生成。 --- # 日志异常诊断 ## 执行步骤 1. 运行 python scripts/preprocess_log.py log_file得到结构化摘要。 2. 判断错误的时间分布区分集中爆发和偶发问题。 3. 选取栈顶中首次出现业务代码的位置。 4. 根据错误码查 references/error_codes.md给出候选根因。 5. 按下列格式输出结论。 ## 输出要求 - summary一句话概括问题类型。 - candidates按置信度排序写 23 个可能原因。 - next_actions给出可以立即执行的排查动作或观察建议。你可能已经注意到了第 4 步我让模型去查 references 里的错误码表而不是让它凭记忆“想当然”。这是 Skill 和纯 Prompt 的重要差异之一Skill 可以把知识库、脚本、示例当成自己的外挂不必把所有知识都塞进对话上下文。2.5 第五步用真实案例回填Examplesexamples/不是装饰品而是模型最直接的模仿对象。AI 学 Skill 不完全靠读规则更会从输入输出对里推导“原来用户要的是这种感觉”。我从真实故障里选了三个案例放进去超时型错误某个接口调用外部服务超时栈顶都指向同一个依赖 SDK数据库连接池耗尽日志里大量connection timeout且时间点高度集中误报型问题虽然报 ERROR但实际是探测请求导致的正常异常日志影响面为零。这三个案例覆盖了“最常见”、“最紧急”、“最容易看走眼”三种情况。模型在这个 Skill 里看到的不是抽象道理而是“原来遇到这种 ERROR 不要慌先去匹配错误码表”。有案例的 Skill 和没案例的 Skill效果差异非常大。3. 实操记录日志诊断Skill从草稿到可用的完整过程3.1 目录结构随手放出来最终这个 Skill 的目录长这样triage-server-log/ ├── SKILL.md ├── scripts/ │ ├── preprocess_log.py │ └── summary_schema.json ├── examples/ │ ├── timeout_error.log │ ├── timeout_error.output.md │ ├── db_connection_error.log │ ├── db_connection_error.output.md │ ├── probe_warning.log │ └── probe_warning.output.md └── references/ ├── error_codes.md └── changelog.md不要小看这个结构它的每个部分都对应一类问题。SKILL.md管流程scripts/管确定性执行examples/管输出风格references/管历史经验。少了任何一个部分Skill 都会变成“一次性 Prompt”。3.2 脚本输出格式是模型判断的地基preprocess_log.py的输出不能太复杂不然模型读起来也费劲。我用一个 JSON 数组作为中间结果每个对象大概长这样[ { timestamp: 2025-06-11T14:03:22, level: ERROR, service: order-service, error_code: TIMEOUT, stack_head: /app/src/service/order.go:121 GetOrderInfo } ]脚本会把几千行日志压缩成这样的几条或几十条结构化记录。模型后续要做的事就变成了“看这些结构化记录里有什么规律”而不是“在一堆无关日志里翻来翻去”。选择 JSON 而不是纯文本还有一个原因它方便后续被其他 Skill 消费。日志诊断完毕如果要生成本周线上稳定性周报周报 Skill 可以直接读取这份 JSON不需要再解析一遍原始日志。这就是 Skill 之间形成“业务能力网络”的基础。3.3 第一次使用就踩了两个坑Skill 写完后我立刻用它做了一个真实告警结果并不顺利。第一个问题是模型执行脚本时空跑了一遍找不到scripts/preprocess_log.py。原因是很多模型会在当前工作目录下执行命令如果不先切换到 Skill 所在目录路径就是错的。后来我在SKILL.md的执行步骤里加了一句话运行前先确认当前目录是否为 Skill 根目录如果不安先切过去再执行。这个问题立刻解决了。第二个问题是输出太长。模型把原始日志片段整段贴到结论里看得人头大。我后来在输出要求里加了硬约束不要在next_actions里粘贴超过三行日志所有结论必须引用结构化 JSON 里的字段。加上示例后输出风格明显收敛了。3.4 效果变化人工5分钟缩短到20秒迭代了两周之后这个 Skill 基本稳定了。之前一个不复杂的报错日志从拿到日志到给人一个初步判断我大概要花三到五分钟现在把日志路径丢给 AI选择对应的 Skill二十秒左右就能拿到一版思路清晰的初步诊断。要说明的是这不代表 AI 完全替代了人它只是把“找信息、筛信息、套历史经验”这部分事情加速了。真正做最终判断、决定要不要通知业务方、要不要紧急回滚的时候还是需要人在场。但少花三分钟去大海捞针留出时间做更复杂的事情这个杠杆已经足够大了。3.5 Skill是一次次喂出来的不是一次写成的我见过很多人想一次性把 Skill 写到完美结果憋了一天也写不出来。我的习惯是先写一个 80 分版本能跑通一个人工 case 就好然后每次失败就补一条错误原因到SKILL.md或者改一个脚本细节。比如有一次遇到了大量 WARN 级别但业务无感的日志模型一开始当成高优问题处理。后来我在脚本里加了一个avg_latency_ms字段同时在 references 里补充了“探测请求会导致少量 4xx/5xx不影响业务”。这类错犯过一次之后就被固化成了 Skill 里的一条规则而不是每次都要人在对话里提醒。4. Skill跟Prompt、Agent、插件有什么不同一张对照表4.1 为什么总有人把它们混在一起这四个词都出现在同一段 AI 对话里功能上天然有交叉。工具插件可以在对话里被调用Prompt 可以告诉模型怎么做Agent 看起来也在“自动执行”Skill 又和 Prompt 有几分相似。但实际分工差异很大。我习惯用一个厨房比喻Prompt你直接告诉厨师“做一道辣子鸡不要太辣”工具/插件菜刀、炒锅、调料架提供做菜的原子能力Skill是一本“辣子鸡标准做法手册”里面包括选料、刀工、火候、摆盘步骤还有两张成品图对比Agent是后厨里的主厨。它不亲自切菜但它判断现在该做哪道菜、需要调用哪个 Skill、火候不对时怎么调度人处理。4.2 一个表格直接看懂区别维度Prompt工具/插件SkillAgent本质一次性指令原子功能可复用的流程知识包自主决策的交互系统存储形式对话文本服务/脚本/插件目录 文件 示例应用或服务使用方式用户发给模型模型或用户调用场景触发后按步骤执行发起动作并持续控制复用性低每次重写高但不管流程高连流程一起复用中通常需要配置典型例子“帮我分析这段日志”grep、API 插件日志诊断 Skill告警处理 AgentSkill 的特殊之处在于它把“指令”和“工具调用”揉成了一个整体。Prompt 负责“说”工具负责“做”Skill 负责“会做且知道什么时候做”。4.3 Skill 和 Agent 的协作边界很多人问我有了 Agent 还要 Skill 干什么Agent 自己会拆解任务。这句话只说对了一半。Agent 确实会拆解任务但拆解完以后某个子任务具体怎么做如果没有 Skill它就会靠模型临场发挥。比如“看一下日志找原因”Agent 能理解这句话但它不知道要用 grep 先过滤、不知道去查错误码表、不知道输出要分 summary/candidates/next_actions。Skill 给 Agent 提供了“熟手的肌肉记忆”。Agent 是大脑Skill 是已经固化的条件反射。一个成熟的业务 Agent通常是若干个高质量 Skill 的组合调度器它判断现在需要先做日志诊断调用日志 Skill拿到结论后需要写复盘再调用复盘生成 Skill。这样整个链路的质量是可以控的。4.4 不要为了Skill而Skill有一点要泼冷水不是所有任务都适合封装成 Skill。如果一件事用一句话提示词两分钟就能搞定且不需要跑脚本、不需要固定格式、不需要多次复用那就别折腾目录和示例了。Skill 适合的是“重复性 流程性 输出可结构化的三维交叉点”。过度封装 Skill和过度封装函数一样会让维护成本高过收益。5. 落地Skill最容易踩的五个坑5.1 模型根本不读你的长篇大论第一个坑最隐蔽。你辛辛苦苦写了一个 3000 字的 SKILL.md结果模型只读了前面三分之一就开始执行后面的规则一条没遵守。原因是很多平台在加载 Skill 时会用“文件摘要”或“前若干行内容”来决定是否触发。如果 SKILL.md 写太长、启动太慢模型可能截断或遗漏。我的经验是SKILL.md的核心控制部分控制在 6080 行以内把高频的步骤、关键输出规则放前面额外的错误码表、复杂案例放到references/目录下让模型需要时再查。文件不是越长越好而是越“能被模型有效消费”越好。5.2 脚本路径和运行环境不一致第二个坑在命令行派 Skill 里很常见。本地跑得好好的脚本同一个 Skill 换一台电脑或换一个 Agent 客户端跑就直接找不到路径。在SKILL.md里要明确规定运行脚本的目录基准。我在开头的description之外加了一行固定动作- 执行脚本之前先确认当前目录是否为 Skill 根目录不是先切换再运行。同时脚本里的可执行依赖尽量做检查。例如在 python 脚本开头用import sys判断依赖缺失时给出提示而不是让模型看到一屏 traceback 后自己瞎猜。Skill 既然是代码就应该用代码工程的眼光来控制不确定性。5.3 examples里只放了成功案例很多人在做 Skill 示例时只放“完美输入 完美输出”好像这个 Skill 永远不会遇到脏数据。但现实恰恰相反线上日志经常没有 ERROR、错误码不存在、异常堆栈被截断。只给成功案例会让模型在遇到异常输入时硬套成功路径把“没有 ERROR”解读成“一切正常”或者把误报当严重故障。我在examples/里专门放了两个“边界案例”一个是没有 ERROR 但延迟异常一个是探活日志导致的误报。模型看到这些例子后才知道不能只按字面 ERROR 报火警。5.4 Skill 的边界定义太模糊多个Skill互相打架当你的 Skill 数量越来越多触发描述就成了关键。如果每个 Skill 的描述里都有“分析日志”这几个字模型很容易不知道调哪个。后来我给每个 Skill 都设了专属动作词比如日志诊断就叫triage-server-log周报生成就叫weekly-review-generator代码变更检查就叫review-code-diff。description字段里明确写“当用户要求定位线上服务异常原因时使用”同时也写“不要用它来做代码编写”。边界越清晰模型触发越准。5.5 一上来就搞全家桶最后维护不过来还有一个常见心态今天看到日志 Skill 好用明天又想给市场部做一个后天再给财务做一个。一星期写了十几个 Skill但每个都用了一两次就再也没打开。Skill 是需要持续用真实案例喂的。没有案例回填没有失败复盘Skill 很快会变成一堆过时脚本。建议先选两三个最高频、最痛苦的点打透用出感觉后再向其他场景扩展。你想解决的是业务问题不是 Skill 数量 KPI。6. 从几个Skill到可复用业务能力最后落地建议6.1 先选能“打透”的三个场景个人经验最先做 Skill 的三个场景可以这样选技术团队可以选“错误日志初诊”因为它的反馈周期短出了问题立刻能发现管理者或者需要写材料的人可以选“周报/复盘生成”因为输出结构统一能明显减少每周的重复劳动开发流程里可以选“代码变更检查”把常见 bug 模式和团队规范写进 Skill比让每个人逐个提醒更稳定。这三个场景有一个共同特点一旦用起来你很快能发现哪些规则写得不好并快速迭代。6.2 让Skill之间开始“对话”Skill 真正转变为业务能力发生在它开始被另一个 Skill 消费的时候。我现在的日志诊断 Skill 会把结果输出为结构化 JSON这份 JSON 又会被周报生成 Skill 读取。于是“日志分析”不再是一个孤立的动作而是“线上稳定性归因与周报生成”业务链路里的一个环节。不要为每个 Skill 设计完全不同的输出格式。统一 JSON 结构或基础 Markdown 目录格式会让后续的 Skill 组合变得容易得多。数据契约是 Skill 协作的地基。6.3 每次使用后留一条修正记录维护 Skill 最容易忽略的是“历史经验”。我会在references/changelog.md里随手记录“某月某日因为模型总把 WARN 当成 ERROR在 references 里补充了探测请求说明。”这听起来特别朴素但恰恰是这样一条一条补进去Skill 才会越来越像一个真正的“老师傅”。Git 里也能清晰看到这个能力是如何长出来的。如果某个 Skill 改了十几个版本后开始臃肿不要心疼直接把过时规则删掉把新的 case 整理进 examples。Skill 不是越厚越好能稳定命中场景的 Skill才是可复用业务能力的最小完整形态。6.4 我自己的一点体会写了这么多其实最想表达的就一句话别囤工具去封装你一周至少重复三次的那件事。工具再多如果动作没有固化下来每次都是临时演员Skill 就是给这些动作写了一份可维护的剧本它是让 AI 从“会聊天”变成“会干活”的那层关键连接。我现在的使用习惯已经变成看到某个流程重复出现第一反应不是马上问模型怎么处理而是先把流程拆出来做成一个 Skill再让 Skill 去处理。这两者的差别大概就是“让 AI 帮你临时想一想”和“让 AI 按你验证过的方法帮你干活”之间的差别。
最近这段在折腾 Agent 和 AI 编码流程我最大的感触是光有一堆工具不够。MCP 服务装了一堆编辑器插件拉满模型也换成了最新版但每次处理同类任务还是要从零开始把背景、要求、输出格式重新讲一遍。直到我把重复三次以上的高频动作一个个沉淀成 Skill情况才真正开始改变。Skill 不是什么玄乎概念。你翻开源社区Claude Skills、Codex Skills、各种 Agent Skill 叫法不同核心思路几乎一致用一份SKILL.md、几个脚本、几组真实示例把“零散的动作”固化成“可复用的业务能力”。这篇文章我不打算讲一堆空概念直接从一个我自己打磨过的日志诊断 Skill 出发拆开聊聊为什么要做 Skill、怎么写才不翻车、以及怎么让 Skill 真正在团队里长出生产力。适合正在用 AI 工具解决实际问题、又不想每次手动喂上下文的人。1. Skill到底是什么为什么工具堆满还是不够1.1 你缺的不是工具是“动作序列”现实里的绝大多数工作都是长链条的。问题来了先取数据再过滤噪声然后做判断最后形成结论和下一步动作。这个链条上每个环节都有现成工具日志平台能查数据jq 能过滤 JSONgrep 能捞关键字大模型能帮你分析原因连 PPT 都能靠插件生成。但问题在于工具本身是“原子能力”而业务交付的是“分子级动作串”。举个例子线上服务报错日志里堆满了异常。给我一整套行业里最全的工具链我依然要做的是先把日志复制出来定位时间窗口再看 ERROR 级别行的上下文接着判断是超时、依赖挂了还是代码逻辑问题最后写一段给开发看的建议。中间每一步都可以靠工具加速但这整串动作本身没有固化成任何可以被 AI 直接调用的东西。于是每次告警来了我都要重新复制背景、重新告诉模型“先看什么、后看什么、结论写成什么格式”。这不叫效率这叫反复造轮子。1.2 Skill的本质可执行的“手法说明”那 Skill 到底长什么样如果你拆开一个 Claude Skill 或 Codex Skill大概率会看到类似结构my-skill/ ├── SKILL.md ├── scripts/ │ ├── preprocess.py │ └── report.py ├── examples/ │ ├── case_01_input.log │ ├── case_01_output.md │ └── ... └── references/ ├── error_codes.md └── changelog.mdSKILL.md是模型要读的第一份资料用来告诉它“什么时候用这个能力、按什么步骤执行、输出格式是什么”。scripts/放真正能跑的脚本承担日志过滤、数据提取、格式转换这些脏活累活。examples/放几组真实的输入输出案例给模型当“模仿样本”。references/放错误码表、业务术语、历史复盘等补充知识。SKILL.md不是把一个长 Prompt 改个名字那么简单。普通 Prompt 是一次性的文本指令用完就没了Skill 则是能被 Agent 平台加载在指定场景里稳定生效的“操作手册”。它既有“怎么说”也有“怎么执行”还有“怎么验收”。1.3 没有Skill团队经验只能靠人肉传承我见过不少团队工具买了、模型也接入了但生产力还是卡在几个关键人身上。原因很简单个人经验都藏在聊天记录里藏在某个人的脑子里没有变成组织能读到的文件。Skill 的价值恰好在这里。当一段处理经验被写成目录、放进 Git、配上示例它就从一个“这次处理得不错”变成了“下次遇到同类问题可以稳定复现”。这也是为什么 Skill 能比工具更进一步工具提供能力Skill 沉淀方法。方法才是业务能力的真正载体。1.4 不是所有事都值得做成Skill开始动手前最好先有个判断标准。以我自己的经验值得做成 Skill 的任务通常满足三条高频一周至少重复两三次甚至每天都要做。流程相对固定步骤可以拆出来输入输出边界比较清楚。输出有结构结论可以被复用比如写成报告、表格或后续动作清单。用一张表来区分会更直观类型适合做成 Skill不适合做成 Skill典型场景错误日志初步定位、周报复盘生成、代码变更检查、固定格式的文本抽取头脑风暴、短视频选题创意、个人审美风格设计原因动作可拆、标准可定、结果要复用过于开放、主观判断强、每次差异大例子“拿到一份服务日志快速告诉我可能原因和下一步排查点”“帮我想一个六月营销活动主题”2. 如何写一个能落地的Skill五步拆出一个完整案例2.1 第一步锁定一个一周至少重复三次的场景很多人学 Skill 做 Skill一上来就想搞一个“万能助手”结果做出来的东西什么都想管什么场景都触发最后在任何一个场景下都不可用。我建议反过来先找一个扎到疼的场景。我当时选的是“线上服务日志异常初诊”。判断依据就三条次数多告警基本每天都有每条都要人工先看一遍日志。重复度高每次做一样的事——捞日志、过滤关键字、找堆栈、匹配错误码。翻车成本高漏掉关键上下文很容易把一次误报当成故障或者把真正根因掩盖过去。这个场景价值感极强做完之后立刻能看到效果也就有动力持续迭代。2.2 第二步把自己当成“被观察的熟练工”这个阶段先别写文档先老老实实走一遍人工处理过程。我对着真实日志完整跑了一次记录了自己大脑里的决策路径先把整个日志文件拉出来但不会直接看先用 grep 找出所有包含ERROR和Exception的行。再看这些错误在时间轴上是否集中如果集中在几十秒内大概率是外部依赖或流量冲击如果分散出现可能是偶发故障。找到第一个能定位问题的栈顶行通常是业务代码入口。根据错误码去对照历史经验判断是超时、连接被拒、还是资源不足。最后输出结论最高概率原因、次要可能、建议看哪段代码或哪个监控面板。这个动作清单看起来朴素但它就是 Skill 的原型。所谓固化就是先把自己脑子里的流程“翻译”成别人也能照做的步骤。2.3 第三步把能脚本化的事情尽量放进脚本很多 Skill 新手会犯一个错误SKILL.md 里写满了“你要仔细分析日志”“你需要结合上下文”然后就没有然后了。更稳的做法是能用代码确定性完成的事就不依赖模型临场发挥。我当时写了一个preprocess_log.py它会自动做这些事情过滤出 ERROR、WARN、Exception 等关键行提取每行的时间戳、日志级别、服务名、错误码截取异常堆栈的第一段去掉无意义的内部框架输出一份统一格式的 JSON 给模型。这样做的好处是模型拿到的不是一份几千行的大日志而是一张经过结构化处理的“问题摘要表”。模型只需要在有限的候选集里做推理判断不需要从零开始大海捞针。脚本负责确定性模型负责判断性两者配合才稳定。2.4 第四步写SKILL.md把流程和触发条件同时钉死SKILL.md是整个 Skill 的驾驶舱。它不能只讲“你要怎么分析”还必须在开头写清楚“什么时候调用这个 Skill、什么时候不调用”。我常用的开头格式是这样的--- name: triage-server-log description: 当用户提供服务器错误日志或日志文件路径要求定位线上故障原因时使用。适合排查超时、依赖异常、空指针等常见问题。不适合做日志格式整理或代码生成。 --- # 日志异常诊断 ## 执行步骤 1. 运行 python scripts/preprocess_log.py log_file得到结构化摘要。 2. 判断错误的时间分布区分集中爆发和偶发问题。 3. 选取栈顶中首次出现业务代码的位置。 4. 根据错误码查 references/error_codes.md给出候选根因。 5. 按下列格式输出结论。 ## 输出要求 - summary一句话概括问题类型。 - candidates按置信度排序写 23 个可能原因。 - next_actions给出可以立即执行的排查动作或观察建议。你可能已经注意到了第 4 步我让模型去查 references 里的错误码表而不是让它凭记忆“想当然”。这是 Skill 和纯 Prompt 的重要差异之一Skill 可以把知识库、脚本、示例当成自己的外挂不必把所有知识都塞进对话上下文。2.5 第五步用真实案例回填Examplesexamples/不是装饰品而是模型最直接的模仿对象。AI 学 Skill 不完全靠读规则更会从输入输出对里推导“原来用户要的是这种感觉”。我从真实故障里选了三个案例放进去超时型错误某个接口调用外部服务超时栈顶都指向同一个依赖 SDK数据库连接池耗尽日志里大量connection timeout且时间点高度集中误报型问题虽然报 ERROR但实际是探测请求导致的正常异常日志影响面为零。这三个案例覆盖了“最常见”、“最紧急”、“最容易看走眼”三种情况。模型在这个 Skill 里看到的不是抽象道理而是“原来遇到这种 ERROR 不要慌先去匹配错误码表”。有案例的 Skill 和没案例的 Skill效果差异非常大。3. 实操记录日志诊断Skill从草稿到可用的完整过程3.1 目录结构随手放出来最终这个 Skill 的目录长这样triage-server-log/ ├── SKILL.md ├── scripts/ │ ├── preprocess_log.py │ └── summary_schema.json ├── examples/ │ ├── timeout_error.log │ ├── timeout_error.output.md │ ├── db_connection_error.log │ ├── db_connection_error.output.md │ ├── probe_warning.log │ └── probe_warning.output.md └── references/ ├── error_codes.md └── changelog.md不要小看这个结构它的每个部分都对应一类问题。SKILL.md管流程scripts/管确定性执行examples/管输出风格references/管历史经验。少了任何一个部分Skill 都会变成“一次性 Prompt”。3.2 脚本输出格式是模型判断的地基preprocess_log.py的输出不能太复杂不然模型读起来也费劲。我用一个 JSON 数组作为中间结果每个对象大概长这样[ { timestamp: 2025-06-11T14:03:22, level: ERROR, service: order-service, error_code: TIMEOUT, stack_head: /app/src/service/order.go:121 GetOrderInfo } ]脚本会把几千行日志压缩成这样的几条或几十条结构化记录。模型后续要做的事就变成了“看这些结构化记录里有什么规律”而不是“在一堆无关日志里翻来翻去”。选择 JSON 而不是纯文本还有一个原因它方便后续被其他 Skill 消费。日志诊断完毕如果要生成本周线上稳定性周报周报 Skill 可以直接读取这份 JSON不需要再解析一遍原始日志。这就是 Skill 之间形成“业务能力网络”的基础。3.3 第一次使用就踩了两个坑Skill 写完后我立刻用它做了一个真实告警结果并不顺利。第一个问题是模型执行脚本时空跑了一遍找不到scripts/preprocess_log.py。原因是很多模型会在当前工作目录下执行命令如果不先切换到 Skill 所在目录路径就是错的。后来我在SKILL.md的执行步骤里加了一句话运行前先确认当前目录是否为 Skill 根目录如果不安先切过去再执行。这个问题立刻解决了。第二个问题是输出太长。模型把原始日志片段整段贴到结论里看得人头大。我后来在输出要求里加了硬约束不要在next_actions里粘贴超过三行日志所有结论必须引用结构化 JSON 里的字段。加上示例后输出风格明显收敛了。3.4 效果变化人工5分钟缩短到20秒迭代了两周之后这个 Skill 基本稳定了。之前一个不复杂的报错日志从拿到日志到给人一个初步判断我大概要花三到五分钟现在把日志路径丢给 AI选择对应的 Skill二十秒左右就能拿到一版思路清晰的初步诊断。要说明的是这不代表 AI 完全替代了人它只是把“找信息、筛信息、套历史经验”这部分事情加速了。真正做最终判断、决定要不要通知业务方、要不要紧急回滚的时候还是需要人在场。但少花三分钟去大海捞针留出时间做更复杂的事情这个杠杆已经足够大了。3.5 Skill是一次次喂出来的不是一次写成的我见过很多人想一次性把 Skill 写到完美结果憋了一天也写不出来。我的习惯是先写一个 80 分版本能跑通一个人工 case 就好然后每次失败就补一条错误原因到SKILL.md或者改一个脚本细节。比如有一次遇到了大量 WARN 级别但业务无感的日志模型一开始当成高优问题处理。后来我在脚本里加了一个avg_latency_ms字段同时在 references 里补充了“探测请求会导致少量 4xx/5xx不影响业务”。这类错犯过一次之后就被固化成了 Skill 里的一条规则而不是每次都要人在对话里提醒。4. Skill跟Prompt、Agent、插件有什么不同一张对照表4.1 为什么总有人把它们混在一起这四个词都出现在同一段 AI 对话里功能上天然有交叉。工具插件可以在对话里被调用Prompt 可以告诉模型怎么做Agent 看起来也在“自动执行”Skill 又和 Prompt 有几分相似。但实际分工差异很大。我习惯用一个厨房比喻Prompt你直接告诉厨师“做一道辣子鸡不要太辣”工具/插件菜刀、炒锅、调料架提供做菜的原子能力Skill是一本“辣子鸡标准做法手册”里面包括选料、刀工、火候、摆盘步骤还有两张成品图对比Agent是后厨里的主厨。它不亲自切菜但它判断现在该做哪道菜、需要调用哪个 Skill、火候不对时怎么调度人处理。4.2 一个表格直接看懂区别维度Prompt工具/插件SkillAgent本质一次性指令原子功能可复用的流程知识包自主决策的交互系统存储形式对话文本服务/脚本/插件目录 文件 示例应用或服务使用方式用户发给模型模型或用户调用场景触发后按步骤执行发起动作并持续控制复用性低每次重写高但不管流程高连流程一起复用中通常需要配置典型例子“帮我分析这段日志”grep、API 插件日志诊断 Skill告警处理 AgentSkill 的特殊之处在于它把“指令”和“工具调用”揉成了一个整体。Prompt 负责“说”工具负责“做”Skill 负责“会做且知道什么时候做”。4.3 Skill 和 Agent 的协作边界很多人问我有了 Agent 还要 Skill 干什么Agent 自己会拆解任务。这句话只说对了一半。Agent 确实会拆解任务但拆解完以后某个子任务具体怎么做如果没有 Skill它就会靠模型临场发挥。比如“看一下日志找原因”Agent 能理解这句话但它不知道要用 grep 先过滤、不知道去查错误码表、不知道输出要分 summary/candidates/next_actions。Skill 给 Agent 提供了“熟手的肌肉记忆”。Agent 是大脑Skill 是已经固化的条件反射。一个成熟的业务 Agent通常是若干个高质量 Skill 的组合调度器它判断现在需要先做日志诊断调用日志 Skill拿到结论后需要写复盘再调用复盘生成 Skill。这样整个链路的质量是可以控的。4.4 不要为了Skill而Skill有一点要泼冷水不是所有任务都适合封装成 Skill。如果一件事用一句话提示词两分钟就能搞定且不需要跑脚本、不需要固定格式、不需要多次复用那就别折腾目录和示例了。Skill 适合的是“重复性 流程性 输出可结构化的三维交叉点”。过度封装 Skill和过度封装函数一样会让维护成本高过收益。5. 落地Skill最容易踩的五个坑5.1 模型根本不读你的长篇大论第一个坑最隐蔽。你辛辛苦苦写了一个 3000 字的 SKILL.md结果模型只读了前面三分之一就开始执行后面的规则一条没遵守。原因是很多平台在加载 Skill 时会用“文件摘要”或“前若干行内容”来决定是否触发。如果 SKILL.md 写太长、启动太慢模型可能截断或遗漏。我的经验是SKILL.md的核心控制部分控制在 6080 行以内把高频的步骤、关键输出规则放前面额外的错误码表、复杂案例放到references/目录下让模型需要时再查。文件不是越长越好而是越“能被模型有效消费”越好。5.2 脚本路径和运行环境不一致第二个坑在命令行派 Skill 里很常见。本地跑得好好的脚本同一个 Skill 换一台电脑或换一个 Agent 客户端跑就直接找不到路径。在SKILL.md里要明确规定运行脚本的目录基准。我在开头的description之外加了一行固定动作- 执行脚本之前先确认当前目录是否为 Skill 根目录不是先切换再运行。同时脚本里的可执行依赖尽量做检查。例如在 python 脚本开头用import sys判断依赖缺失时给出提示而不是让模型看到一屏 traceback 后自己瞎猜。Skill 既然是代码就应该用代码工程的眼光来控制不确定性。5.3 examples里只放了成功案例很多人在做 Skill 示例时只放“完美输入 完美输出”好像这个 Skill 永远不会遇到脏数据。但现实恰恰相反线上日志经常没有 ERROR、错误码不存在、异常堆栈被截断。只给成功案例会让模型在遇到异常输入时硬套成功路径把“没有 ERROR”解读成“一切正常”或者把误报当严重故障。我在examples/里专门放了两个“边界案例”一个是没有 ERROR 但延迟异常一个是探活日志导致的误报。模型看到这些例子后才知道不能只按字面 ERROR 报火警。5.4 Skill 的边界定义太模糊多个Skill互相打架当你的 Skill 数量越来越多触发描述就成了关键。如果每个 Skill 的描述里都有“分析日志”这几个字模型很容易不知道调哪个。后来我给每个 Skill 都设了专属动作词比如日志诊断就叫triage-server-log周报生成就叫weekly-review-generator代码变更检查就叫review-code-diff。description字段里明确写“当用户要求定位线上服务异常原因时使用”同时也写“不要用它来做代码编写”。边界越清晰模型触发越准。5.5 一上来就搞全家桶最后维护不过来还有一个常见心态今天看到日志 Skill 好用明天又想给市场部做一个后天再给财务做一个。一星期写了十几个 Skill但每个都用了一两次就再也没打开。Skill 是需要持续用真实案例喂的。没有案例回填没有失败复盘Skill 很快会变成一堆过时脚本。建议先选两三个最高频、最痛苦的点打透用出感觉后再向其他场景扩展。你想解决的是业务问题不是 Skill 数量 KPI。6. 从几个Skill到可复用业务能力最后落地建议6.1 先选能“打透”的三个场景个人经验最先做 Skill 的三个场景可以这样选技术团队可以选“错误日志初诊”因为它的反馈周期短出了问题立刻能发现管理者或者需要写材料的人可以选“周报/复盘生成”因为输出结构统一能明显减少每周的重复劳动开发流程里可以选“代码变更检查”把常见 bug 模式和团队规范写进 Skill比让每个人逐个提醒更稳定。这三个场景有一个共同特点一旦用起来你很快能发现哪些规则写得不好并快速迭代。6.2 让Skill之间开始“对话”Skill 真正转变为业务能力发生在它开始被另一个 Skill 消费的时候。我现在的日志诊断 Skill 会把结果输出为结构化 JSON这份 JSON 又会被周报生成 Skill 读取。于是“日志分析”不再是一个孤立的动作而是“线上稳定性归因与周报生成”业务链路里的一个环节。不要为每个 Skill 设计完全不同的输出格式。统一 JSON 结构或基础 Markdown 目录格式会让后续的 Skill 组合变得容易得多。数据契约是 Skill 协作的地基。6.3 每次使用后留一条修正记录维护 Skill 最容易忽略的是“历史经验”。我会在references/changelog.md里随手记录“某月某日因为模型总把 WARN 当成 ERROR在 references 里补充了探测请求说明。”这听起来特别朴素但恰恰是这样一条一条补进去Skill 才会越来越像一个真正的“老师傅”。Git 里也能清晰看到这个能力是如何长出来的。如果某个 Skill 改了十几个版本后开始臃肿不要心疼直接把过时规则删掉把新的 case 整理进 examples。Skill 不是越厚越好能稳定命中场景的 Skill才是可复用业务能力的最小完整形态。6.4 我自己的一点体会写了这么多其实最想表达的就一句话别囤工具去封装你一周至少重复三次的那件事。工具再多如果动作没有固化下来每次都是临时演员Skill 就是给这些动作写了一份可维护的剧本它是让 AI 从“会聊天”变成“会干活”的那层关键连接。我现在的使用习惯已经变成看到某个流程重复出现第一反应不是马上问模型怎么处理而是先把流程拆出来做成一个 Skill再让 Skill 去处理。这两者的差别大概就是“让 AI 帮你临时想一想”和“让 AI 按你验证过的方法帮你干活”之间的差别。
