最近半年如果你常逛开发者社区肯定绕不开一个词skills。从各家大模型平台陆续放开自定义技能能力到开源社区里冒出一大批 skill 仓库这个原本平淡无奇的英文单词现在基本成了提示词工程的下一个形态。我自己的体感很明显上半年还在和同行讨论怎么把提示词写得结构更清晰下半年讨论的话题就变成了怎么把一套完整技能封装好让它能在不同场景下稳定复用。这篇文章我想聊聊我对 skills 的理解、实际拆解一个技能时的设计思路以及我在搭建技能库过程中踩过的坑和沉淀下来的经验。我要说的 skills不是个人能力提升那种泛泛而谈的软技能而是 AI 领域里那个具体的、可挂载到模型或智能体上的技能定义。它解决的是一个很实际的问题模型每次对话都从零开始但很多任务其实是有固定套路、固定输出格式、固定校验规则的。把这些套路固化成一份机器可读的技能说明书模型在遇到相关任务时就能直接调用而不是每次靠用户现场口述。适合谁看如果你正在用 AI 处理重复性较高的文本任务、数据分析、代码审查或者你想把自己常用的工作流沉淀成可复用的资产这篇内容应该能给你一些直接能落地的参考。1. 项目概述Skills 到底是什么为什么大家都在谈1.1 从提示词到 Skills 的演变逻辑先说概念。Skills 本质上是一套结构化的指令包它把完成某一类任务所需的背景知识、操作步骤、输出格式、边界条件和参考示例打包成一个目录放在模型能够读取的位置。当用户提出的问题命中技能描述的范围时模型会自动加载这个技能按里面的规则来执行任务。这和传统的提示词有什么区别我自己的理解是提示词是一次性处方每次都要开Skills 是常备药柜提前把常见病症对应的药都分好类模型在问诊时自动判断该开哪一盒。举个例子你可以在对话里写一句帮我以 JSON 格式输出字段包括姓名、电话、地址注意电话要脱敏这是一条提示词。但如果你经常要做用户信息清洗就把脱敏、格式转换、非法值过滤这套规则全部写进一个叫用户信息处理的 Skill 里以后只要说帮我处理一下这份名单模型自己就知道该去加载这个技能输出的格式、处理逻辑都是预设好的。从实际使用感受来说这种转变带来的最大好处是稳定。提示词写得再清楚每次对话的上下文长度不同、模型注意力分配不同结果多少会有波动。而 Skills 把关键规则固定下来相当于给模型发了一份标准作业指导书输出质量的下限被明显抬高了。1.2 一个 Skill 的标准长相目前业内比较通用的 Skills 目录结构是这样的my-skill/ ├── SKILL.md ├── scripts/ │ └── analyze.py └── references/ └── template.md入口文件统一叫SKILL.md里面用 YAML frontmatter 写元信息正文写具体的执行指令。scripts 目录放可执行的辅助脚本references 目录放参考文档或模板。模型在调用时首先读取SKILL.md的 frontmatter 来决定是否触发这个技能触发之后按正文指令逐步执行。SKILL.md的基本骨架长这样--- name: log_analyzer description: 用于分析应用日志并定位异常原因。当用户提供日志文本、日志文件路径或描述线上报错场景时使用。 --- # 日志分析技能 ## 执行步骤 1. 先读取用户提供的日志内容识别时间戳、日志级别、进程 ID。 2. 按时间线归并同一次请求的日志记录。 3. 定位异常级别以上的记录分析错误码和堆栈信息。 4. 输出原因分析、影响范围、修复建议三部分。 ## 输出格式 必须使用 Markdown 表格输出包含时间、请求ID、事件描述、严重程度。 ## 注意 - 不要修改用户原始日志内容。 - 分析结果区分确定事实和推测原因。这里有两个细节很关键。一是description字段的写法它直接决定模型什么时候会调用这个技能。描述要写得像触发器包含触发场景的关键词而不是泛泛的功能描述。二是正文步骤要按序编号模型是逐个执行指令的步骤顺序如果混乱输出质量直接受影响。2. 核心设计思路如何拆解并封装一个技能2.1 先定边界再写描述很多人第一次写 Skill 时容易犯的一个错是恨不得把一套技能写得无所不能。比如写数据分析技能结果什么数据都往里面塞最后模型面对一堆互相冲突的指令完全不知道从哪条开始执行。我的做法是先划边界这个技能只干什么不干什么哪些情况下必须拒绝执行。边界划清楚之后description字段才写得准。我常用的写法是这样description: 用于处理用户上传的 CSV 或 Excel 数据表格执行列名标准化、非法值标注和重复行去重。当用户明确提到清洗表格处理数据文件或提供表格文件路径时使用。不适用非表格类文本处理、数据可视化分析。你注意最后那句不适用这个非常重要。给模型明确负向信号能显著降低误调用概率。我在实测中发现没有负向约束的技能误触发率大约能到 20% 到 30%加了之后直接降到 5% 以下。2.2 目录结构与外部资源引用单个SKILL.md文件能承载的指令密度有限而且全塞在一个文件里模型检索到关键规则时可能已经被前面大段无关内容干扰了。所以目录拆分是必须的。scripts 目录的使用场景我解释一下。有些任务不是纯文本处理能搞定的比如计算大量数据的平均值、过滤不符合正则表达式的记录、把 JSON 转成 CSV这种操作最好让模型先写一个脚本执行脚本拿结果再基于结果做分析。这个流程比让模型在脑子里硬算可靠得多。在SKILL.md正文里引用脚本一般这样写## 脚本辅助 当需要统计数值列的基本统计量或过滤异常值时使用 scripts/analyze.py。运行方式 python3 scripts/analyze.py --input 文件路径 --operation stats而 references 目录的作用是放那些不一定每次都用得上但用的时候必须准确的资料。比如代码规范全文、数据库表结构文档、一份复杂的正则表达式手册。把这些塞进主文件会让指令长度失控放 references 里按需读取刚刚好。2.3 模板、工作流与检查逻辑技能设计最核心的部分是把任务拆成输入 - 处理 - 输出的工作流。我总结出的三段式结构是这么写的分析阶段读取输入识别关键要素必要时先提澄清问题。执行阶段按步骤处理中间可以调用脚本工具。校验阶段对照输出格式要求自查检查字段是否齐全、类型是否正确、有没有遗漏的内容。校验这一步很多人会忽略但恰恰是它决定了技能输出的可靠度。我通常会在SKILL.md里写死一条规则## 输出前自查 - 所有必填字段是否都有值 - 日期格式是否为 YYYY-MM-DD - 是否包含明显的占位文本 - 如有疑问应重新整理后再输出。这相当于给模型加了一道质检工序。模型在输出前过一遍自查出错率能降一半不止。这里面的原理其实和人做事一样如果不强制检查模型的生成是流式的一路写到完加了检查指令它会在生成完结果之后额外用一个推理步骤来校验自己的输出等于多了一层纠错机会。3. 实操过程从零构建一个可用的 Skill3.1 场景选择我为什么先做日志分析理论知识说再多不如动手做一个。我建议第一次写 Skill 的人选一个自己工作中重复频率最高、规则最明确的场景。我第一回练手选的是日志异常分析原因有三一是这个场景我自己几乎每周都要做有足够的真实素材二是日志分析的规则相对客观比如按级别过滤、按时间排序模型不容易自由发挥三是最终产出物非常标准化适合固化成模板。当时我手头有一个模拟项目 X 的生产环境日志几千行里混着 SQL 告警、接口超时、空指针异常几类问题。以前人工处理至少半小时而且每次分析完还得整理成日报给其他同事看。做 Skill 的目标就是丢日志进去直接出结构化分析结果。3.2 完整案例日志分析 Skill 的落地过程我按上面说的结构一步步搭。目录和文件log-analyze-skill/ ├── SKILL.md ├── scripts/ │ ├── parse_log.py │ └── extract_stacktrace.py └── references/ └── error_code_manual.mdSKILL.md的最终版本经过几轮迭代之后简化如下--- name: log_anomaly_analyzer description: 用于分析应用日志中的异常与错误适用于用户提供原始日志文本、日志文件路径或描述看下日志排查报错分析线上问题等场景。不适用于安全审计类日志分析。 --- # 日志异常分析 ## 角色 你是一名有多年在线系统维护经验的稳定性工程师。 ## 步骤一解析 - 如果用户提供的是文件路径先读取文件。 - 如果是日志文本直接接收。 - 用 scripts/parse_log.py 识别时间戳、级别、线程、错误码。 ## 步骤二归类 - 将异常记录按错误码归类。 - 对每类异常标记出现次数、首次发生时间、最后发生时间。 ## 步骤三分析 - 提取堆栈中的业务方法名。 - 结合 references/error_code_manual.md 判断错误码含义。 - 区分已明确根因的、需要进一步排查的、外部依赖导致的。 ## 输出格式 使用 Markdown 表格 | 错误码 | 出现次数 | 首次发生 | 最后发生 | 严重程度 | 初步判断 | 表格之后按严重程度从高到低列出 TOP 3 异常每条给出 - 现象描述 - 根因推断 - 修复建议 ## 硬性规则 - 禁止修改原始日志。 - 若信息不足直接列出需要补充的日志片段不得猜测。 - 不确定的结论必须标注存疑。然后是我写的辅助脚本parse_log.py的核心逻辑#!/usr/bin/env python3 import sys import re from collections import Counter, defaultdict log_pattern re.compile( r(?Ptimestamp\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}[,\d]*)\s r(?PlevelDEBUG|INFO|WARN|ERROR|FATAL)\s r\[(?Pthread.?)\]\s r(?Pmessage.*) ) def parse(path): records [] for line in open(path, encodingutf-8): m log_pattern.match(line.strip()) if m: records.append(m.groupdict()) else: # 多行堆栈信息单独保留 records.append({timestamp: None, level: STACK, thread: , message: line.strip()}) return records def summarize(records): errors [r for r in records if r[level] in (ERROR, FATAL)] counter Counter(r[message][:60] for r in errors) return { total_lines: len(records), error_count: len(errors), top_errors: counter.most_common(10) } if __name__ __main__: result parse(sys.argv[1]) summary summarize(result) print(summary)脚本不复杂但它把统计错误次数这种需要精确计算的事情从模型手里接过去了。模型只需要调用脚本拿到结果再做语义层面的根因分析两边各干各擅长的事。3.3 Skills 的测试与迭代方法写完第一版只是开始。我测试 Skill 时一般准备三批输入一批是典型的正常请求、一批是边界情况比如空日志、全是 DEBUG 级别的日志、格式完全乱的文本、一批是故意诱导误判的请求。测试方式就是真实对话里反复触发观察模型是否在正确时机加载技能、输出格式是否符合要求、内容有没有明显错误。第一版跑下来我的日志分析 Skill 存在的问题有两个。一是description写太窄了用户说看看这个日志怎么回事时模型不会触发必须说分析一下这些日志的异常才调起来。二是有一次模型把 DEBUG 级别的一条记录当成了异常来分析。解决方式是调整描述字段加宽触发条件同时给步骤二加了一条规则- ERROR / FATAL 级别记录必须覆盖分析。 - WARN 级别记录需要人工确认不直接归为异常。 - DEBUG 级别记录默认忽略除非用户明确要求分析。这么改过之后误判问题基本解决了。整个迭代过程我大概跑了两轮每次大约一小时效率比写传统提示词高很多因为规则是集中维护的改一处全局生效。4. 常见问题与排查技巧实录4.1 描述写不好技能永远不被调用这是我在自己搭建技能库过程中遇到频率最高的问题。反正你写完一个 Skill丢给模型测试发现它根本不加载那 90% 是description有问题。常见的毛病有三种一是太笼统比如用于分析数据模型遇到十个任务八个都能沾边但每个都感觉不完全匹配最后哪个都没触发二是太具体把触发场景限定死了用户换个说法模型就识别不出来三是没有负向排除模型把相似任务也归到这个技能头上。我后来总结出一个可复用的描述模板description: 用于完成什么类型任务。当用户具体描述场景或关键词时使用。不适用于负面排除场景。其中中间那句具体描述场景要写出至少三种常见说法覆盖用户可能的表达方式。像日志分析那条我就写了看下日志排查报错分析线上问题三种。经过验证覆盖这三种自然说法的技能比只写术语的技能触发率至少高出一倍。4.2 文件路径与上下文处理模型读取文件的能力在实际使用中并不稳定尤其当用户给出相对路径时。我的经验是在SKILL.md的执行步骤里明确要求模型在读取文件前先确认文件存在的当前工作目录如果找不到主动让用户提供绝对路径。这个不起眼的步骤能避开大量技能感觉没生效的假象。我还踩过坑用户给了 CSV 文件路径Skill 触发后模型直接说无法访问文件。后来发现是目录结构设计问题模型把当前工作目录理解错了。实际上在大多数平台里技能执行环境是固定的路径处理必须写成硬规则不能指望模型自己推导。我的处理方式是在 SKILL.md 里固定一段## 文件访问 - 优先处理用户直接粘贴的文本内容。 - 若用户提供路径先检查是否存在不存在则列出当前目录内容并请用户确认路径。 - 读取文件后提取前 20 行作为预览让用户确认是否为待处理文件。这段指令加上之后文件处理的成功率提升非常明显。4.3 技能冲突与调用优先级当技能库超过五个技能之后还会遇到互相干扰的问题。比如我有个数据清洗技能还有个日志分析技能如果用户说帮我清洗一下这份日志文件两个技能都会被触发模型就纠结了。踩过几次之后我加了优先级规则在SKILL.md描述字段中明确当与 XX 技能冲突时本技能优先级更高或者反过来。现在主流平台对多 Skill 的处理机制也在改进据我了解到的情况有的实现是并行加载所有候选技能再让模型决策选哪个有的是根据description相似度打分阈值高的先加载。不管哪种机制作为技能编写者我们能做的就是在描述里尽量场景化、差异化。如果两个技能允许的触发范围严重重叠说明技能边界设计就有问题应该合并或拆分而不是靠修描述硬扛。4.4 常用排错速查表现象可能原因排查动作技能完全不被触发description 与用户表达不匹配重写描述增加自然说法和负向排除技能触发了但输出不符合要求SKILL.md 正文指令模糊检查步骤是否按序编号输出格式是否用量例明确模型表现和没加技能时一样技能内容被模型忽略检查文件路径是否正确SKILL.md frontmatter 是否合法多个技能同时被触发边界重叠合并技能或在描述里声明优先级脚本报错环境依赖未注明SKILL.md 里写明依赖命令和安装方式5. 技能库的长期维护与复用5.1 版本管理与变更日志Skills 不是写完就能一劳永逸的因为它会随着模型能力迭代而逐渐失效或者变低效。我在使用中发现同一套技能在模型升级一个月之后可能因为新模型对指令的理解方式不同输出风格就开始偏了。所以技能也需要版本管理。我给自己的技能库建立了简单的变更记录每次改动在SKILL.md末尾加一段## Changelog记录日期和改动内容。定期回看这些记录能发现自己常改的是哪些规则这些地方就是技能设计的薄弱点。## Changelog - 2025-06-10将数据清洗脚本升级为 Python 3修复日期格式判断错误。 - 2025-05-22优化 description增加去重触发场景。这是个体量很小但回报很高的习惯尤其当你需要分享技能给其他人时没有变更记录协作基本靠猜。5.2 共享与协作技能库发展到一定规模后我尝试过把几个常用的技能打包分享给团队其他人用。这个过程中暴露了一个问题每个人对同一任务的表达方式差别很大我写技能时按自己的表达习惯来别人用起来触发率就低。后来我把团队里四五个人集中在一个在线文档里收集各自描述同类任务的说法合并成一份触发表达集写进description。从那以后团队里的技能调用率明显上来了。如果你准备做技能分享建议遵循三条原则。第一保持目录结构一致别每个技能都换一套组织方式。第二SKILL.md里所有自定义脚本都要带说明和依赖清单否则别人拿到技能根本跑不起来。第三输出格式尽量通用不要写死成只有你能用的表格样式。技能的价值在于复用而复用的前提是别人能看懂、能改、能不费劲地用起来。5.3 我和 Skills 目前的相处方式现在我的技能库里大概维护了六个左右比较活跃的技能覆盖日志分析、格式转换、代码审查、个人周报生成这几个场景。我没有故意把它扩充得很大因为技能维护是有成本的一个技能如果不常用它就会渐渐落后于模型能力变化反而拖累使用体验。我的判断标准很简单一个技能在真实使用中如果连续两周没被触发要么删掉要么先检查 description 是否写偏了。与其追求技能库里堆满几十个项目显得很专业不如抓住最常用的几个把它们打磨到足够稳定。这和我几年前整理代码工具库的思路一模一样——可乐不是靠数量取胜的。最后分享一个我实际操作中养成的小习惯每当我发现自己连续三次向 AI 提了非常相似的要求、每次都需要现场组织话术时我就会停下来把这个需求做成一个技能。这其实是识别值得封装场景的最好信号。长此以往你的 AI 使用体验会从每次碰运气变成越来越自动化这也是 skills 这个概念本身最迷人的地方。