“skills”这个概念最近在我关注的 AI 工程化圈子里越来越热。说白了它就是把过去散落在提示词里、文档里、甚至老师傅脑子里的经验整理成一套结构化的、能让大模型直接照着执行的方法论资产。我前阵子花了两个周末把自己手头几个重复度高的任务比如代码审查、周报生成、SQL 写数分别封装成了独立的 skill跑通之后有个很明显的感受过去是每次跟模型对话都要重新调教一遍现在是把经验沉淀下来一次封装到处复用输出质量还稳得一批。这篇文章就把我这段时间折腾“skills”的完整心得写出来包括它到底解决了什么问题、一个高质量的 skill 该怎么设计、完整实操案例以及我踩过的一堆坑。适合正在做 AI 应用开发、提示词工程或者想把自己的工作流标准化的朋友参考不管你是用 Claude、Cursor 这类现成工具还是自己在封装 Agent这套思路都通用。1. 先搞明白“skills”到底解决了什么问题1.1 模型什么都知道但就是不按你的规矩干活我一开始跟大模型协作最大的痛点就是“飘”。你问它“什么是代码审查”它给你列得头头是道什么可读性、性能、安全八股文一套一套的。但当你让它真正去审查你团队的一段代码时问题就出来了它总是凭“常识”在审而不是按你们团队的规范在审。比如你们团队明确要求所有错误处理必须用自定义异常禁止裸抛 Exception模型偏偏每次都能给你挑出几个别的毛病但对这种硬性规范视而不见。这就是一个很核心的矛盾大模型的知识是通用的而你要它干的活是高度个性化的。通用知识它管够但“你们这里该怎么做事”这种隐性知识它没有。过去我们怎么解决靠提示词把规范写进去。但提示词的毛病也很明显写短了不够用写长了每次对话都要占用大量上下文而且改一版规范就要改所有相关提示词维护成本极高。Skills 这套机制本质上是把“该怎么做”这件事从对话上下文里抽离出来变成一个独立的能力单元。模型在执行任务时会根据任务描述动态加载匹配的 skill然后把技能里的流程、规则、示例当作执行依据。这就好比你请了一个知识渊博的顾问但你不会每次都把公司规章制度从头到尾背给他听而是直接甩给他一本《员工手册》告诉他按这个来。Skills 就是那本《员工手册》。1.2 Prompt、RAG、Fine-tuning、Skill到底该怎么选很多朋友一听这个第一个反应是这跟 RAG 有什么区别跟 Fine-tuning 又是什么关系这里我直接给一张对比表是我自己整理用的看完基本就清楚了。技术方案实现成本维护成本解决的核心问题适用场景Prompt 模板低高临时的指令约束一次性或低频任务简单对话RAG中中让模型“知道”外部知识知识问答、文档摘要、信息检索Fine-tuning极高极高改变模型的“能力”和“行为习惯”特定风格生成、专业领域深度定制Skills中低低让模型“会按流程做事”高频复用的工作流、标准化操作、专家经验固化我个人理解是RAG 解决的是“知识”问题它回答的是“是什么”Skills 解决的是“方法”问题它回答的是“怎么做”。Fine-tuning 太重了改一次业务规则就要重新训练一次对绝大多数团队来说完全没必要。而 Skills 恰好站在一个中间位置比 Prompt 更结构化比 RAG 更偏执行流程比 Fine-tuning 轻量得多而且改起来极快改完立即生效。1.3 Skills 的本质不是堆规则而是把专家经验结构化这是我最想强调的一点。很多人以为写 Skill 就是写一堆“你必须怎样怎样”的规则清单大错特错。一个真正好用的 Skill它的核心是“决策逻辑”而不是“命令列表”。举个例子写代码审查的 Skill不是简单地写“遇到命名不规范要指出”而是要让模型理解什么情况下命名不规范是必须指出的比如对外 API 的命名、什么情况下只是建议比如内部临时变量的命名、什么情况下可以不提比如第三方库兼容代码。这种带条件的、分优先级的判断逻辑才是专家经验。否则写出来的 Skill 就是一本死板的说明书模型照着执行反而会把代码吹毛求疵地审一遍产出全是噪音。所以构建 Skill 的过程本质上就是把你脑子里的“隐性经验”外化成“显性逻辑”的过程。你被迫去思考我处理这个任务时第一步看什么什么情况必须拦下来什么情况可以放行什么情况下我自己的判断也会出错把这些想清楚写出来的 Skill 才真正有用。2. 拆解一个高质量 Skill核心要素与结构设计2.1 先定目录结构别一个 Markdown 文件打天下我见过很多朋友写 skill就写一个巨大的 SKILL.md里面什么都有结果模型加载起来上下文爆掉输出质量反而下降。我自己通常采用这样的目录组织方式skills/ code-review/ # 技能名全小写加连字符 SKILL.md # 主文件模型优先加载 examples/ # 示例目录按需引用 bad-sample.py # 反例有明显问题 good-sample.py # 正例合规写法 review-report.md # 输出格式示例 references/ # 参考资料目录 team-style-guide.md # 团队规范原文 checklist.md # 快速检查清单这么设计的考虑有三点。第一SKILL.md 保持精简只放执行流程、判断标准、边界条件控制在 200 行以内。大模型对上下文的注意力是有限的你塞了太多噪音它就会忽略真正的重点。第二把大段参考资料放进 references 目录让模型按需加载。现在不少 Agent 框架支持 skill 内部的文件引用模型觉得需要查具体规范时会自己去 references 里找。这就避免了每次执行都把一大堆文档塞进上下文。第三examples 目录单独放是为了让模型在不确定的时候有个对照模板。示例的作用不是给模型“背诵”而是给它一个“参照物”帮助它理解抽象规则的具体表现。2.2 SKILL.md 里最重要的不是正文是 Frontmatter一个合格的 SKILL.md开头应该有 YAML 格式的元信息Frontmatter这部分是给模型看的不是给人看的。它决定了模型在什么场景下会调用这个技能。--- name: code-review description: 用于 Python 代码审查。当需要检查代码质量、发现潜在 Bug、评估代码是否符合团队规范时使用。不适用于架构设计评审、性能压测分析。 when_to_use: 用户提交代码变更、Pull Request、或要求“帮我看看这段代码”的场景。 version: 1.2.0 tags: [python, code-quality, review, backend] ---这里有个血泪教训description千万别写得太大而全。我最初写的是“用于代码质量分析和审查”结果模型动不动就调用它连用户问“这段代码的时间复杂度是多少”都去加载这个技能反而把简单问题复杂化了。正确做法是既要说清楚“什么时候用”也要明确“什么时候不用”比如不适用于架构评审这样模型才能精准匹配。这几个字段的真实作用是“技能路由”。大模型看到用户请求后会先根据所有可用技能的 description选一个最匹配的来执行。如果你 description 写得不清楚要么模型不该用的乱用要么该用的不调用所以这块值得仔细打磨。2.3 正文结构目标、步骤、标准、边界、示例一个都不能少我推荐的 SKILL.md 正文结构是五段式清晰地告诉模型“为什么要做、怎么做、做到什么程度、别做什么、做成什么样”。第一段是“技能目标”用两三句话说清楚这个技能服务的最终业务目标。代码审查的目标不只是“找 Bug”而是“在不阻塞业务迭代的前提下守住代码质量底线”这个认知会影响模型后续的所有判断。你写目标时想清楚模型执行时才不会跑偏。第二段是“执行步骤”分步骤描述处理任务的标准流程。代码审查我会拆成四步先看整体结构和变更范围再查核心逻辑正确性然后对照团队风格规范最后输出结构化结论。每步都要写清楚“做什么、关注什么”。第三段是“判断标准与优先级”这是最核心的部分。必须明确哪些问题必须改、哪些建议改、哪些只是可选优化。我习惯用三级标签[BLOCKER]必须修改、[MAJOR]强烈建议、[MINOR]可选。没有优先级体系的 skill模型就会把所有发现的问题一视同仁地抛出产出价值就很低。第四段是“边界与禁忌”写得越清楚模型越不会越界。比如明确说本技能只审查代码实现层面不讨论产品需求合理性不重写代码只提供修改建议不审查第三方库内部实现。边界的意义是限制模型“自由发挥”的空间。第五段是“输出格式”明确告诉模型最终产出的报告长什么样。输出格式不稳定是 AI 应用里最烦人的问题之一解决办法就是给出模板并要求严格套用。2.4 写示例的核心心法成对出现并说清楚“为什么”不管什么类型的 skill示例都极其重要。但我发现一个通病大家给的示例只有正例没有反例。这是不够的。正例告诉模型“对的什么样”但模型可能不知道怎么从错的状态迁移到对的状态。反例的价值在于让模型知道“识别出问题”是什么样的。我把示例成对放每个反例旁边都标注清楚问题再把对应的正例和修改说明放一起模型的模仿效果会好很多。另外示例最好用真实场景中的代码或文本片段不要用虚构的、刻意构造的例子。因为虚构例子往往过于典型、过于简单模型学了反而会变得教条。用真实世界里那些“模棱两可”的案例模型才能学到那种微妙的判断力。3. 从 0 到 1 实操构建一个“代码审查”Skill 全流程3.1 第一步需求梳理与目标定义我拿自己团队的真实需求来做示范。我们团队后端以 Python 为主日常有大量 Pull Request 需要人工审查代码风格不统一、基础错误反复出现审查效率低。我想做一个 Skill让模型先做第一轮自动化审查把低级问题全部过滤掉人工只关注模型筛出来的重点。动手前我先回答了三个问题。一是“业务目标”减少人工审查负担把重复性、机械性问题自动化。这决定了技能的设计导向——宁可漏报也尽量不要误报因为误报会让人不再相信这个系统。二是“处理对象”Python 后端的业务代码不包含架构评审。三是“成功标准”模型能找出 80% 以上的基础问题比如未处理的异常、明显的命名不规范、明显的逻辑错误且误报率控制在 20% 以下。这个前置思考非常重要。很多 skill 做出来不好用就是因为目标定义模糊连设计者自己都不清楚要达到什么效果。你先想清楚“做成什么样算成功”后面所有编写工作才有参照。3.2 第二步编写完整 SKILL.md直接看我最终版本的 SKILL.md 主体内容你可以照着他改自己的。--- name: python-code-review description: 审查 Python 后端代码质量。当用户提交代码片段、Pull Request 或要求进行代码走查时使用。重点关注异常处理、数据校验、日志规范、性能隐患。不适用于架构设计评审。 when_to_use: 用户要求“帮我 review 代码”“看看这段有什么问题”“这个 PR 能合吗” version: 1.3.0 tags: [python, code-review, backend] --- # 角色 你是一位有 10 年经验的 Python 后端代码审查专家。你的任务是帮助团队在代码合入前发现潜在问题。 # 审查流程 严格按照以下步骤进行审查 1. **先看整体**阅读全部代码理解核心逻辑确认代码的职责边界。 2. **找致命问题**优先级最高 - 是否有未捕获的异常可能导致程序崩溃 - 是否有明显的逻辑错误导致功能不符合预期 - 是否有严重的安全隐患SQL 注入、命令注入等 3. **查规范问题** - 命名是否符合 PEP8 及团队规范蛇形命名法 - 是否有未使用的导入、明显的冗余代码 - 错误处理是否使用了自定义异常体系 4. **给出改进建议** - 对于非阻塞问题给出具体的优化方向。 # 问题分级 所有发现的问题必须分级 - [BLOCKER]必须修复才能合入。如致命逻辑错误、安全隐患。 - [MAJOR]强烈建议修复。如异常处理缺失、资源未释放、明显性能问题。 - [MINOR]可选优化。如命名建议、代码简化。 # 边界与禁忌 - 不要重写代码只提供修改建议。 - 不讨论产品需求是否合理。 - 不审查第三方库内部实现。 - 不确定的问题标注“需人工确认”不要强行下结论。 # 输出要求 使用以下 Markdown 格式输出 ## 审查结论 通过 / 需修改 ## 问题列表 - [级别] 文件/位置问题描述 - 修改建议具体方案 ## 改进建议 可选补充非阻塞性的优化建议你注意一下这个文件里我没有放具体代码示例只放了流程和标准。示例放在 examples 目录里等模型看完主文件后如果对某些抽象描述不确认再去翻具体例子。这样设计主文件加载起来轻量执行效率更高。3.3 第三步构造反例与正例并用真实历史代码验证写完 SKILL.md还不能直接用。我花了大半天时间构造示例集。先说反例我特意从历史代码里找那些被 review 出来过问题的真实代码而不是自己编。比如下面这个典型的坏味道# bad-sample.py import os from datetime import datetime def save_user(user_data): data get_db() user_id user_data[id] user_name user_data[name] if os.path.exists(f/tmp/{user_id}): return user_data[create_time] datetime.now() data.insert(user_data, users) return user_data这段代码的问题非常典型存在路径拼接安全隐患user_id未经过校验直接拼进文件系统、裸抛Exception风险get_db()和data.insert()都没有异常处理、变量命名没有体现业务含义、没有日志记录。关键是它不是一眼就烂得离谱的代码而是那种“看起来能跑但问题一抓一大把”的代码这才贴近真实工作。模型通过一个这样的完整反例比我写一百条“要处理异常”的规则都管用。正例则是在此基础上一一修复后的版本每个修改点都对应反例里的一个问题。构造这种“同场景正反对”的示例能让模型建立清晰的映射什么样的坏味对应什么样的好改法。然后我用团队过去两个月的 10 个真实 Pull Request 做了测试。第一版跑完发现问题集中在两点一是对业务逻辑里的“空值保护”判断过严很多本来可以靠上一层逻辑保证的地方模型也报成[MAJOR]形成了噪音二是对团队自定义异常体系不敏感总是建议用内置Exception反而违反了团队规范。我针对这两个问题调整了边界描述和参考文档第二版明显好很多。这种基于真实反馈的迭代过程是打磨 skill 质量的必经之路。一次写到位的 skill 是不存在的。3.4 第四步持续用失败案例“喂”给技能Skill 上线之后不是一劳永逸。我会把日常人工审查中发现的问题分为两类一类是模型能稳定发现的不用管另一类是模型连续漏掉的我会把漏掉的典型代码片段加入 references/checklist.md并在 SKILL.md 中补充对应的判断逻辑。比如有段时间模型总是漏掉“数据库查询结果未判空直接取下标”的情况。我就在 checklist 里加了一条并在主文件的第 2 步强调“访问列表或字典前是否确认存在对应索引或 Key”同时提供了一个小示例。下次模型执行时就会覆盖到这一点。这个迭代节奏让 Skill 像滚雪球一样越来越懂你们团队的代码风格。你用一次它强一次三个月之后它基本就变成了你们的“团队专属审查官”。4. 常见问题与排查思路技能封装避坑指南4.1 模型就是不调用我的 Skill问题多半出在描述上这是新手最高频的困惑。我排查过的案例里90% 是description写得不到位。模型在做技能匹配时是拿用户请求和每个技能的description做相似度匹配如果你描述得太笼统比如“用于代码质量分析”模型就很难把它和“帮我看看这段代码”关联起来。解决办法是在 description 里明确写出触发场景和典型用户提问方式。比如写成“当用户提交代码片段、Pull Request或要求‘review 一下代码’‘帮我看看这段有什么问题’时使用”。把触发词直接写进去命中率会大幅提高。另一个排查点是技能目录的加载位置。有的工具框架要求必须把 skill 放在指定目录路径不对的话你的技能根本不会进入候选列表。仔细对照你所用框架的文档确认目录命名和放置位置是否正确。4.2 Skill 内容太长Token 成本高加载慢一开始我图省事把团队规范、检查清单、示例代码全塞进 SKILL.md结果一次执行消耗巨量上下文响应也变慢。后来我调整了策略主文件只保留核心流程和高频规则低频参考内容全部放进 references 目录由模型按需加载示例文件每个控制在 50 行以内只放典型场景。这里有个经验数据供参考一个 skill 的主文件我建议控制在 150 到 250 行之间。超过这个量模型对后面内容的注意力会明显下降你后面写的规则基本属于白写。如果必须有很多内容那就拆分成多个小 skill而不是一个巨型技能。4.3 输出格式总是变来变去模型有自己的想法模型不按格式输出这是 Agent 应用里的经典难题。我的排查顺序是先看 SKILL.md 里的输出模板是否足够具体是否给了完整的 Markdown 示例再看问题分级标签是否明确模型不确定怎么分级时它就会自由发挥最后看示例里是否有输出报告的例子给模型一个“填空”的参照物。我的经验是输出模板这一段既要给结构又要给示例。光给结构比如“## 审查结论”模型不知道结论该写多详细光给示例不给结构模型又可能模仿示例的措辞导致生硬。两个都给了稳定性会大幅提升。有些框架还支持在 SKILL.md 里指定输出风格比如“始终以 Markdown 表格输出”“必须列出前三项最重要问题”这类强化约束也值得用上相当于给技能装了一个“输出侧护栏”。4.4 多个技能之间互相冲突模型不知道选哪个当你的技能库越来越大这个问题就必然出现。我一开始有code-review和python-review两个技能描述高度重叠模型经常随机加载一个导致输出风格不统一。解决办法有三招第一技能命名时避免泛化比如统一用python-code-review、javascript-code-review按语言拆开第二在 description 中明确写出“本技能用于 XX不用于 YY”强化边界第三如果两个技能边界确实重合严重就合并成一个内部按条件分支处理。我在技能库里设立了一条铁律同一个领域只保留一个主动技能其他全部归入参考资料。宁可让一个技能处理多类任务通过分支逻辑也不要让多个技能看起来都能处理同一类任务这能从根上避免调用混乱。5. 从 Skills 到个人与团队的能力沉淀5.1 Skills 是一份“可执行的团队文化手册”我在把几个核心工作流都封装成 skill 之后发现了一个很有价值的副产品它把团队里很多“口口相传”的做法变成了“可执行、可追溯”的规范。新同学入职不用再追着老同事问“代码规范都在哪看”“周报怎么汇报项目进度”“线上告警处理流程是什么”直接把这些技能装进工具里照着执行就行。相较于传统文档skill 的核心优势是它不只是给人看的更是给 AI 执行的。传统文档写“提交 PR 前要自查”人看到了不知道具体查什么但 skill 会把自查拆成步骤、标准和示例AI 能直接帮人把自查做一遍。团队规范从此不再是一纸空文而是嵌入了日常工作流。5.2 技能库的长期维护像维护代码库一样维护技能我建议每个团队和个人都像维护代码仓库一样维护自己的技能库。用 Git 管理版本每个 skill 独立目录遵循统一命名规范提交信息写清楚“为什么改”。我自己还会维护一个CHANGELOG.md记录每个版本的变更原因这样三个月后回看还能想起来当初为什么加了这条规则。目录结构我推荐这样组织skills/ README.md # 技能库总览与索引 python-code-review/ weekly-report/ sql-query-optimization/ >