最近“skill”这个词在 AI 编程圈里越来越高频。我自己的体感是Claude Code、Codex、Trae 这类工具都开始把 skill 当作核心能力载体很多人也在问一个问题skill 不就是把一段很长很长的提示词存起来吗为什么我堆了几千字实际用起来还是不能打我前后写了小几十个 skill从最开始“把提示词换个壳”的自嗨到后来慢慢摸出一套能稳定复用的创建流程中间踩过的坑比写过的 skill 还多。这篇文章就是一次完整复盘重点聊两件事一是标题里反复强调的“方法抽象”也就是怎么从一次性的具体求助里提炼出一套能脱离场景存活的通用方法二是每次发布前我都会过的 Review 清单这份清单在很大程度上决定了一个 skill 是“真能用”还是“看起来能用”。如果你正准备把自己的经验沉淀成 skill或者写过几个 skill 但总觉得不稳可以照着这套流程走一遍。1. 先想清楚skill 不是答案库是可被执行的方法包我最早写 skill 的思路非常简单“把正确答案写进去”。比如做一个代码审查 skill就把我能想到的 Java 代码规范全部列进去什么命名、注释、设计模式能写多全写多全。结果跑起来之后非常尴尬——AI 确实能记住一堆规则但遇到真实 diff 的时候它不知道先看什么、后看什么也不知道什么情况下该升级为严重警告。这个教训让我意识到一个核心区别skill 不是“答案库”而是“方法包”。不要以为 skill 是给 AI 一本百科全书真正的 skill 应该是一份可以照着执行的操作手册里面包含触发条件、执行步骤、判断分支、输出格式以及必要的边界约束。就像厨房里的菜谱如果菜谱只写“盐少许、酱油适量、大火收汁”新手做出来跟老厨师完全不同如果菜谱写到“热锅冷油放入姜片翻炒 10 秒后下主料加生抽 15ml中火煮 3 分钟再转大火收汁”那基本上谁做都能复现个七七八八。Skill 要的是后者是把“怎么做”这件事拆成可执行动作。1.1 skill、prompt 和 agent到底差在哪里很多新手会把三样东西混为一谈prompt、skill、agent。我先用一个表格把这几个概念放一起对比再展开说。概念本质生命周期能否复用典型形态prompt一次性沟通文本用完即走差靠批改粘贴对话框里的指令skill可复用的方法资产长期维护、版本迭代强可被多个场景调用目录 SKILL.md 资源文件agent有自主决策能力的执行体持续运行、自主行动看任务而定感知 → 规划 → 调用工具 → 行动一句话总结prompt 是你跟 AI 说的一句话skill 是你沉淀下来的方法包agent 是拿着方法包去干活的执行者。一个 agent 可以挂载多个 skill遇到不同类型的任务就调用对应的 skill。你要是把技能写成了 prompt那么它就是一次性输入写成真正的 skill它就是一个可被检索、可被重复调用的独立模块。这个概念澄清非常关键因为后面要讲的“方法抽象”本质上就是让你把写 prompt 时的“怎么嘱咐 AI”升级成“怎么设计一个方法模块”。你不再需要每次对话都夹带一堆背景信息和操作规范只需要告诉 AI“用哪个 skill”就够了。1.2 方法抽象到底在抽什么“方法抽象”这四个字听上去很玄其实拆开看就三件事任务类型这个 skill 解决哪一类问题不是哪一次具体问题。处理流程遇到这类问题时应该按照什么顺序执行哪些动作决策规则流程走到分岔路口时根据什么信号做判断什么情况下该停下来向用户要更多信息举个例子。你发现最近一个月连续有同事问你“这段 Java 接口的异常处理规范吗”“这个 PR 有没有安全问题”“前端这次改动对性能有没有影响”。这三个问题看起来风马牛不相及但它们背后共用同一条流程拿到变更范围 → 列出审查项 → 逐项核对 → 输出分级结论。如果你要写一个“代码审查 skill”正确的抽象方向不是去背 Java 规范而是把这条公共流程提炼出来再把具体语言、具体业务规则作为“引用参数”放进 references 目录里。这样你写出来的 skill 可以审 Java、审前端、审接口文档因为你在抽象层面抓住的是“代码变更审查”这个任务类型而不是“某个系统的某次改动”。这也是判断抽象是否到位的标准把一个具体任务里的所有名词都抽掉之后剩下的流程还能不能指导操作能就是抽象完成了不能说明你还在写答案而不是在写方法。2. 三步方法抽象从 5 次答疑到一套通用处理流程很多朋友问我“怎么才能高效创建 skill”我都会反问一句你是不是已经遇到过至少三次同类问题了如果没有那你其实不需要写 skill直接对话解决就行。如果有那你的素材库已经足够了接下来只差一套把素材提炼成方法的手段。我形成了一套固定的三步抽象流程每一步都有明确产出不需要靠灵感。2.1 第一步建一个“候补池”专门收集被问了三次以上的问题我的习惯是准备一个专门的地方记录“人类经验碎片”不一定用多复杂的工具一个支持表格的云文档就够了。每次有人问我问题或者我自己在代码评审里反复纠正同类错误我都会花 30 秒登记一行原始问题是什么我当时是怎么解决的解决过程中踩了哪些坑有哪些信息是必须前置知道的为什么要以“三次”为门槛一次是偶发两次可能是巧合三次就是规律。当同一个问题出现第三次时就意味着它不值得你每次重复回答一遍应该让 skill 来回答。而且这个候补池本身就是最真实的“需求文档”。你在里面记下来的每一个“坑”都是未来 skill 里必须写进约束条件的素材比你自己拍脑袋想出来的边界条件可靠得多。2.2 第二步把答疑记录摊开只留下动作序列当你积累了 5 条同类答疑记录之后把它们全部摊开去掉人物、项目名、具体技术栈只看你在每轮答疑中的动作你会发现它们的骨架惊人地相似。以代码评审为例。假设候补池里有三条记录同事 A 问这个 Java 接口异常处理规范吗同事 B 问新写的订单服务会不会有安全漏洞同事 C 问这个 Vue 组件改动对性能有没有影响如果停留在“答案”层面这三条是完全独立的知识点。但你把解决过程抽象成动作抽出来的流程是一致的获取变更范围确认到底改了哪些文件、哪些函数按变更类型匹配不同的审查点逐项检查给每个问题打严重度标签汇总输出按照 P0/P1/P2 分级反馈修改建议。抽完骨架之后你再去填肉Java 要重点看异常是否被吞掉、NPE 风险前端要看是否有大列表无分页、循环内发请求接口看是否鉴权缺失、是否信任外部输入。这些具体的检查点不是方法层是资源层所以放进 references/checklist-java.md、checklist-frontend.md而不是全部塞进 SKILL.md 的主流程。这一步做完一个通用的“代码审查 skill”其实已经成型了。后面所有语言、框架相关的差异都只是不同配置下的参数而已。2.3 第三步明确边界能力再强也不能越界方法抽象最容易翻车的地方不是“没内容”而是“什么都想管”。一个 skill 如果既想做代码审查又想管需求评审还想兼职做代码生成那它大概率什么都做不精。在编写任何 skill 之前先把两个列表写出来In-scope这个 skill 在什么场景下生效。例如“只审查变更内容不审查历史存量代码”。Out-of-scope遇到什么情况应该主动拒绝或转由人工处理。例如“不替用户直接修改代码发现敏感信息泄露时必须中断并提醒”。边界还有一个作用防止 AI 在信息不足时“硬答”。我在 Review 清单里专门有一条要求 skill 必须定义“信息缺失”的处理方式——当用户没提供完整的 diff 或者没说明变更意图时skill 的第一步不是开始审查而是向用户索要清单里缺的信息。这一步不会让 skill 看起来更“能干”但会让它更“可信”。真实工程里一个知道什么时候该停下来问人的技能比一个永远自信满满给结论的技能可靠得多。3. 创建 skill 的完整实操流目录、主文件、脚本、测试抽象做完接下来是落地的部分。我见过很多开发者拿到了很好用的流程但最后败在实现细节上——目录结构乱、SKILL.md 里全是空话、测试用例就一个 happy path。下面是我现在创建 skill 的固定动作每一步都可以直接照抄。3.1 先搭目录骨架一个文件干一件事我推荐的 skill 目录结构长这样review-skill/ ├── SKILL.md ├── references/ │ ├── checklist-java.md │ ├── checklist-security.md │ └── output-template.md ├── scripts/ │ └── parse_diff.py ├── tests/ │ ├── case-001-standard.json │ ├── case-002-boundary.json │ └── case-003-missing-info.json └── CHANGELOG.md每个部分的分工很清晰SKILL.md整个 skill 的入口也是 AI 最先读取的文件。里面只写触发条件、主流程、决策规则和输出格式。references/按需加载的参考资料。SKILL.md 主文件不需要把所有规范一次读完AI 可以根据任务类型决定就读哪份文档避免一次性把上下文塞满。scripts/如果 skill 依赖脚本处理数据或调用工具放这里。脚本应该保持最小化不要做“全能处理”。tests/测试用例是 skill 迭代的地基后面会细说。CHANGELOG.md记录每个版本的改动尤其是因为什么 bug 做了调整。很多新手以为 skill 只要有一份 SKILL.md 就行。有当然也能跑但当技能的知识量变大之后单文件模式会让 AI 必须一次性读入巨大上下文效果会断崖式下降。分离目录的最大好处是给 AI 一个“按需取用”的路径主文件负责带路参考资料负责补充知识彼此互不干扰。3.2 编写 SKILL.md先写触发条件再写流程最后写约束我写 SKILL.md 通常会按下面模板来--- name: code-review description: 当用户要求审查代码变更、PR、diff 或代码质量时使用。 version: 1.0.0 tags: [review, code-quality] --- ## When to Use - 用户提交了一段 diff希望评估代码质量。 - 用户提交了 PR/MR希望判断是否可以合并。 - 用户希望从异常处理、安全性、性能等维度审查代码。 ## Workflow 1. 读取用户提供的变更内容或 diff确认变更范围。 2. 识别变更类型新增功能、修复 bug、重构、配置调整。 3. 根据类型从 references/ 中选择对应的检查清单。 4. 逐项检查每个问题标记严重度P0必须修复、P1建议修复、P2可选改进。 5. 按 references/output-template.md 输出结论。 ## Constraints - 只审查变更内容不对存量代码开具长期改进清单。 - 如果 diff 信息不完整先列明缺少信息不进入审查流程。 - 不直接修改代码只提供修改建议。 - 发现敏感信息密钥、内网地址、个人信息时中断审查并提醒用户。有几条是我反复强调的第一description 里必须写满触发场景别写“这个 skill 很强大”之类的废话。AI 工具在自动匹配 skill 时靠的就是 description 和当前任务的语义相似度触发条件写得越具体匹配准确率越高。第二Workflow 里的步骤全部用动词祈使句开头。你写“读取”“识别”“选择”“逐项检查”AI 就知道每一步该做什么你写“确保代码质量优秀”AI 就只能在原地打转。第三Constraints 要覆盖“之前真实犯过的错”。那些让你在使用 skill 时不满意的细节全是 Constraints 的素材来源。比如我发现 code-review skill 在信息缺失时会硬着头皮瞎审所以专门加了一条“信息不完整先列缺失信息”的约束效果立竿见影。3.3 三连测标准场景、边界场景、错误场景各一次写完之后别急着发布你的 skill 至少要过一次“三连测”。这是我把大量不合格 skill 挡在发布门外的关键步骤。测试一标准场景挑一个最典型的用例走通完整流程确认核心输出质量达标。测试二边界场景故意制造极端输入比如超长的 diff、一行代码的改动、混合多种语言的改动看 skill 会不会崩、会不会丢失关键信息。测试三错误场景故意不提供完整信息看 skill 是否会主动索要缺失内容还是会乱给结论。每跑完一个测试我都会把实际输出存档到 tests/ 目录下并在 CHANGELOG 里记录失败原因和修复方式。这里必须说一句大实话一套流程在标准场景跑通只能说明“功能可用”连边界和错误场景也稳得住才说明“方法可靠”。3.4 Skill 也要做版本管理很多开发者的代码仓库做 git 管理但 skill 目录反而是裸奔的很多人改了之后没记录下次想回溯只能靠记忆。Skill 本身也是一种代码资产依赖它运行的 AI 模型也会升级模型升级之后同一个 skill 的行为可能会变这时候没有版本管理连排查问题都无从下手。我的做法是每个 skill 独立成一个 git 仓库或者独立目录SKILL.md 头部标注版本号CHANGELOG 记录最近三次改动背后的问题。不要小看这个动作因为你写 skill 时做的每个决策大概率都源于一次真实的失败这些记录就是最珍贵的经验库。4. 写 skill 最容易翻车的五个隐蔽问题下面这几个坑我在审核过的很多 skill 里反复见到有些自己也踩过。每一个都导致过实际使用体验的严重下滑值得拿出来单独说。4.1 把“目标”当成了“步骤”最常见的失败模式是在 Workflow 里写“检查代码质量”“确保安全性”“优化性能”这种话。这些是目标不是步骤。建议拆解成动作检查是否有未捕获的空指针异常检查 SQL 语句是否使用拼接检查循环体内是否发起了外部请求检查是否有未关闭的资源连接。只有动作可以被 AI 稳定执行目标只会让输出质量充满随机性。怎么判断自己写的是目标还是步骤把这句话前头加上“执行”两个字如果能读通就是步骤读不通说明你还是给了一个目标。4.2 上下文塞得太满AI 反而抓不住重点我最早写“日志异常分析” skill 时把所有命令解释、正则写法、告警规则全部贴进 SKILL.md结果 AI 在处理长文本时经常逻辑错乱输出一段没头没尾的结论。后来我把主文件精简成“识别日志格式 → 统计状态码 → 按严重度聚合 → 调用参考正则解析关键行 → 输出报告”把 90% 的细节移入 references/效果立刻回来了。原因是当前 AI 模型的注意力是有限的一次读入的 token 越多对每段内容的敏感度就会降低。SKILL.md 的作用是带路不是装下整个世界。越厚的 skill越需要在入口处做好指引让 AI 知道什么时候去翻参考资料而不是一口气全部吞进去。4.3 环境假设不清换个机器就废Skill 里如果写“用 python3 执行 parse_diff.py”必须先确认运行环境。不同的 AI 工具运行环境有差异有的能直接执行命令有的需要配置白名单还有的根本没有 Python 环境。我的经验是把环境信息写进 references/environment.md内容包括依赖了哪些外部命令、是否有需要安装的包、脚本的输入输出格式、禁止执行哪些危险操作。同时在 SKILL.md 里加一条“执行脚本前先确认环境变量是否存在缺失则告诉用户”。看起来保守实际换环境时能救回很多失效场景。4.4 忽略不同模型之间的行为差异同一个 skill 在 Claude 下执行得很稳换到另一个模型上可能完全跑偏这事我遇到过不止一次。原因是一些模型的弱项有的模型对多级目录结构理解力不足有的模型在长步骤任务中容易丢掉中间结果有的对“如果/那么”分支处理不稳定。解决方案是尽量使用通用的 markdown 结构和简单的指令语言不依赖某个模型独有的能力同时在测试记录里标注“在哪个模型、哪个版本下通过验证”。你的 skill 在某个模型下验证过不代表在别的模型下也成立这一点写清楚是对使用者负责。4.5 不设退出条件永远硬着头皮给答案我在前面提到过信息缺失时的处理这背后其实是一个更大的问题你的 skill 必须允许 AI 承认“我现在不能继续”。很多 skill 作者为了追求成功率把流程设计成了一条不归路AI 一进来就必须走到底就算输入信息完全不够它也会自己脑补出一堆假设来填充。这在工程上是灾难。Skill 里一定要有显式的退出条件例如“当进入本流程后发现用户未提供必要条件停止后续动作列出缺失信息”“当任务属于 out-of-scope 范围时告知用户更换 skill”“当执行脚本失败超过三次时停止尝试并上报错误”。退出条件不是能力不足的表现恰恰是一个成熟技能对自己边界有清晰认知的证明。5. 附 Review 清单发布前像审代码一样审 skillSkill 写完了测试也跑了但发布前最后一道关卡是 Review。我自己以前经常跳过这一步后来吃过发布一个不成熟 skill 的亏从此坚持每次发布前都按清单逐项自检。这套清单我按七个维度整理可以打印出来也可以在 skill 目录里存一份 markdown作为提交模板类别检查项通过标准定位与边界description 是否完整描述触发场景用户扫一眼就知道“当前任务适不适合用这个 skill”定位与边界是否有明确的 out-of-scopeAI 遇到范围外任务会拒绝或转交不会硬答命名名字是否直观不使用堆满专业术语看不清用途的名字命名名称是否重复在已有技能集中没有同名或高度相似的 skill步骤质量Workflow 里的步骤是否都是动词开头没有“保证”“提升”“优化”这类目标型描述步骤质量关键分岔点是否有“如果/那么”分支真实失败场景中的修复点已经写入流程步骤质量每个步骤是否定义了明确的产出物AI 知道这个步骤完成后要输出什么资源与依赖references 里引用的文件是否真实存在所有链接和文件路径可访问不出现 404资源与依赖运行环境和依赖是否写清楚换到另一台机器或另一个工具也能复现资源与依赖scripts 脚本是否有测试过至少跑通一个成功场景和一个失败场景测试与验收是否准备至少 3 个测试用例标准、边界、错误三类各一个结果已存档测试与验收是否记录实际执行输出测试记录里有真实输出文本不只是“看起来没问题”测试与验收是否标注过测试模型及日期以后模型升级后可回查兼容性安全与合规是否禁止了危险操作或需要确认自动执行命令前有明确确认机制安全与合规是否不包含敏感信息无密钥、无内部地址、无个人隐私信息可维护性是否有版本号和最近更新时间version、created、updated 字段齐全可维护性是否有 CHANGELOG记录最近三次改动的原因和结果这条清单用下来最大的价值是倒逼你把“模糊”的东西变“具体”。比如“命名是否直观”这条会逼你想清楚 skill 到底解决什么问题而“是否记录实际执行输出”这条会逼你真的去跑一遍测试而不是看了一下文档就拍板“没问题”。我自己的习惯是把这张 Review 清单本身也放进 skill 目录里这样每次迭代到一半被打断再回来时不用重新回忆当时的思路打开清单照着过一遍就行。最后再说一个朴素但很有用的体会skill 写的不是结果是流程不是替你把某件事做完而是让 AI 每次遇到同类问题时都能按一套可靠的方式把事情做完。所以创建 skill 的效率不取决于你打字多快而取决于你对自己的经验是否做过真正彻底的方法抽象。我自己现在写 skill 有个习惯每写完一版都要先当一次使用者拿真实任务去跑一遍流程而不是站在创作者视角自我欣赏。很多问题只要你愿意切换到使用者的角度多问一句“如果我是刚接触这个任务的 AI我能看懂这一步吗”就能在发布前及时拦住一大半翻车现场。如果你也正在建自己的 skill 库可以试试把第一个 skill 做成纯方法抽象版——不要收集任何具体业务知识进去只保留任务类型、流程骨架和边界规则看看它能不能跑通。跑通了你就掌握到写 skill 的核心手感了。
从提示词到方法包：AI编程中skill创建与Review清单全复盘
最近“skill”这个词在 AI 编程圈里越来越高频。我自己的体感是Claude Code、Codex、Trae 这类工具都开始把 skill 当作核心能力载体很多人也在问一个问题skill 不就是把一段很长很长的提示词存起来吗为什么我堆了几千字实际用起来还是不能打我前后写了小几十个 skill从最开始“把提示词换个壳”的自嗨到后来慢慢摸出一套能稳定复用的创建流程中间踩过的坑比写过的 skill 还多。这篇文章就是一次完整复盘重点聊两件事一是标题里反复强调的“方法抽象”也就是怎么从一次性的具体求助里提炼出一套能脱离场景存活的通用方法二是每次发布前我都会过的 Review 清单这份清单在很大程度上决定了一个 skill 是“真能用”还是“看起来能用”。如果你正准备把自己的经验沉淀成 skill或者写过几个 skill 但总觉得不稳可以照着这套流程走一遍。1. 先想清楚skill 不是答案库是可被执行的方法包我最早写 skill 的思路非常简单“把正确答案写进去”。比如做一个代码审查 skill就把我能想到的 Java 代码规范全部列进去什么命名、注释、设计模式能写多全写多全。结果跑起来之后非常尴尬——AI 确实能记住一堆规则但遇到真实 diff 的时候它不知道先看什么、后看什么也不知道什么情况下该升级为严重警告。这个教训让我意识到一个核心区别skill 不是“答案库”而是“方法包”。不要以为 skill 是给 AI 一本百科全书真正的 skill 应该是一份可以照着执行的操作手册里面包含触发条件、执行步骤、判断分支、输出格式以及必要的边界约束。就像厨房里的菜谱如果菜谱只写“盐少许、酱油适量、大火收汁”新手做出来跟老厨师完全不同如果菜谱写到“热锅冷油放入姜片翻炒 10 秒后下主料加生抽 15ml中火煮 3 分钟再转大火收汁”那基本上谁做都能复现个七七八八。Skill 要的是后者是把“怎么做”这件事拆成可执行动作。1.1 skill、prompt 和 agent到底差在哪里很多新手会把三样东西混为一谈prompt、skill、agent。我先用一个表格把这几个概念放一起对比再展开说。概念本质生命周期能否复用典型形态prompt一次性沟通文本用完即走差靠批改粘贴对话框里的指令skill可复用的方法资产长期维护、版本迭代强可被多个场景调用目录 SKILL.md 资源文件agent有自主决策能力的执行体持续运行、自主行动看任务而定感知 → 规划 → 调用工具 → 行动一句话总结prompt 是你跟 AI 说的一句话skill 是你沉淀下来的方法包agent 是拿着方法包去干活的执行者。一个 agent 可以挂载多个 skill遇到不同类型的任务就调用对应的 skill。你要是把技能写成了 prompt那么它就是一次性输入写成真正的 skill它就是一个可被检索、可被重复调用的独立模块。这个概念澄清非常关键因为后面要讲的“方法抽象”本质上就是让你把写 prompt 时的“怎么嘱咐 AI”升级成“怎么设计一个方法模块”。你不再需要每次对话都夹带一堆背景信息和操作规范只需要告诉 AI“用哪个 skill”就够了。1.2 方法抽象到底在抽什么“方法抽象”这四个字听上去很玄其实拆开看就三件事任务类型这个 skill 解决哪一类问题不是哪一次具体问题。处理流程遇到这类问题时应该按照什么顺序执行哪些动作决策规则流程走到分岔路口时根据什么信号做判断什么情况下该停下来向用户要更多信息举个例子。你发现最近一个月连续有同事问你“这段 Java 接口的异常处理规范吗”“这个 PR 有没有安全问题”“前端这次改动对性能有没有影响”。这三个问题看起来风马牛不相及但它们背后共用同一条流程拿到变更范围 → 列出审查项 → 逐项核对 → 输出分级结论。如果你要写一个“代码审查 skill”正确的抽象方向不是去背 Java 规范而是把这条公共流程提炼出来再把具体语言、具体业务规则作为“引用参数”放进 references 目录里。这样你写出来的 skill 可以审 Java、审前端、审接口文档因为你在抽象层面抓住的是“代码变更审查”这个任务类型而不是“某个系统的某次改动”。这也是判断抽象是否到位的标准把一个具体任务里的所有名词都抽掉之后剩下的流程还能不能指导操作能就是抽象完成了不能说明你还在写答案而不是在写方法。2. 三步方法抽象从 5 次答疑到一套通用处理流程很多朋友问我“怎么才能高效创建 skill”我都会反问一句你是不是已经遇到过至少三次同类问题了如果没有那你其实不需要写 skill直接对话解决就行。如果有那你的素材库已经足够了接下来只差一套把素材提炼成方法的手段。我形成了一套固定的三步抽象流程每一步都有明确产出不需要靠灵感。2.1 第一步建一个“候补池”专门收集被问了三次以上的问题我的习惯是准备一个专门的地方记录“人类经验碎片”不一定用多复杂的工具一个支持表格的云文档就够了。每次有人问我问题或者我自己在代码评审里反复纠正同类错误我都会花 30 秒登记一行原始问题是什么我当时是怎么解决的解决过程中踩了哪些坑有哪些信息是必须前置知道的为什么要以“三次”为门槛一次是偶发两次可能是巧合三次就是规律。当同一个问题出现第三次时就意味着它不值得你每次重复回答一遍应该让 skill 来回答。而且这个候补池本身就是最真实的“需求文档”。你在里面记下来的每一个“坑”都是未来 skill 里必须写进约束条件的素材比你自己拍脑袋想出来的边界条件可靠得多。2.2 第二步把答疑记录摊开只留下动作序列当你积累了 5 条同类答疑记录之后把它们全部摊开去掉人物、项目名、具体技术栈只看你在每轮答疑中的动作你会发现它们的骨架惊人地相似。以代码评审为例。假设候补池里有三条记录同事 A 问这个 Java 接口异常处理规范吗同事 B 问新写的订单服务会不会有安全漏洞同事 C 问这个 Vue 组件改动对性能有没有影响如果停留在“答案”层面这三条是完全独立的知识点。但你把解决过程抽象成动作抽出来的流程是一致的获取变更范围确认到底改了哪些文件、哪些函数按变更类型匹配不同的审查点逐项检查给每个问题打严重度标签汇总输出按照 P0/P1/P2 分级反馈修改建议。抽完骨架之后你再去填肉Java 要重点看异常是否被吞掉、NPE 风险前端要看是否有大列表无分页、循环内发请求接口看是否鉴权缺失、是否信任外部输入。这些具体的检查点不是方法层是资源层所以放进 references/checklist-java.md、checklist-frontend.md而不是全部塞进 SKILL.md 的主流程。这一步做完一个通用的“代码审查 skill”其实已经成型了。后面所有语言、框架相关的差异都只是不同配置下的参数而已。2.3 第三步明确边界能力再强也不能越界方法抽象最容易翻车的地方不是“没内容”而是“什么都想管”。一个 skill 如果既想做代码审查又想管需求评审还想兼职做代码生成那它大概率什么都做不精。在编写任何 skill 之前先把两个列表写出来In-scope这个 skill 在什么场景下生效。例如“只审查变更内容不审查历史存量代码”。Out-of-scope遇到什么情况应该主动拒绝或转由人工处理。例如“不替用户直接修改代码发现敏感信息泄露时必须中断并提醒”。边界还有一个作用防止 AI 在信息不足时“硬答”。我在 Review 清单里专门有一条要求 skill 必须定义“信息缺失”的处理方式——当用户没提供完整的 diff 或者没说明变更意图时skill 的第一步不是开始审查而是向用户索要清单里缺的信息。这一步不会让 skill 看起来更“能干”但会让它更“可信”。真实工程里一个知道什么时候该停下来问人的技能比一个永远自信满满给结论的技能可靠得多。3. 创建 skill 的完整实操流目录、主文件、脚本、测试抽象做完接下来是落地的部分。我见过很多开发者拿到了很好用的流程但最后败在实现细节上——目录结构乱、SKILL.md 里全是空话、测试用例就一个 happy path。下面是我现在创建 skill 的固定动作每一步都可以直接照抄。3.1 先搭目录骨架一个文件干一件事我推荐的 skill 目录结构长这样review-skill/ ├── SKILL.md ├── references/ │ ├── checklist-java.md │ ├── checklist-security.md │ └── output-template.md ├── scripts/ │ └── parse_diff.py ├── tests/ │ ├── case-001-standard.json │ ├── case-002-boundary.json │ └── case-003-missing-info.json └── CHANGELOG.md每个部分的分工很清晰SKILL.md整个 skill 的入口也是 AI 最先读取的文件。里面只写触发条件、主流程、决策规则和输出格式。references/按需加载的参考资料。SKILL.md 主文件不需要把所有规范一次读完AI 可以根据任务类型决定就读哪份文档避免一次性把上下文塞满。scripts/如果 skill 依赖脚本处理数据或调用工具放这里。脚本应该保持最小化不要做“全能处理”。tests/测试用例是 skill 迭代的地基后面会细说。CHANGELOG.md记录每个版本的改动尤其是因为什么 bug 做了调整。很多新手以为 skill 只要有一份 SKILL.md 就行。有当然也能跑但当技能的知识量变大之后单文件模式会让 AI 必须一次性读入巨大上下文效果会断崖式下降。分离目录的最大好处是给 AI 一个“按需取用”的路径主文件负责带路参考资料负责补充知识彼此互不干扰。3.2 编写 SKILL.md先写触发条件再写流程最后写约束我写 SKILL.md 通常会按下面模板来--- name: code-review description: 当用户要求审查代码变更、PR、diff 或代码质量时使用。 version: 1.0.0 tags: [review, code-quality] --- ## When to Use - 用户提交了一段 diff希望评估代码质量。 - 用户提交了 PR/MR希望判断是否可以合并。 - 用户希望从异常处理、安全性、性能等维度审查代码。 ## Workflow 1. 读取用户提供的变更内容或 diff确认变更范围。 2. 识别变更类型新增功能、修复 bug、重构、配置调整。 3. 根据类型从 references/ 中选择对应的检查清单。 4. 逐项检查每个问题标记严重度P0必须修复、P1建议修复、P2可选改进。 5. 按 references/output-template.md 输出结论。 ## Constraints - 只审查变更内容不对存量代码开具长期改进清单。 - 如果 diff 信息不完整先列明缺少信息不进入审查流程。 - 不直接修改代码只提供修改建议。 - 发现敏感信息密钥、内网地址、个人信息时中断审查并提醒用户。有几条是我反复强调的第一description 里必须写满触发场景别写“这个 skill 很强大”之类的废话。AI 工具在自动匹配 skill 时靠的就是 description 和当前任务的语义相似度触发条件写得越具体匹配准确率越高。第二Workflow 里的步骤全部用动词祈使句开头。你写“读取”“识别”“选择”“逐项检查”AI 就知道每一步该做什么你写“确保代码质量优秀”AI 就只能在原地打转。第三Constraints 要覆盖“之前真实犯过的错”。那些让你在使用 skill 时不满意的细节全是 Constraints 的素材来源。比如我发现 code-review skill 在信息缺失时会硬着头皮瞎审所以专门加了一条“信息不完整先列缺失信息”的约束效果立竿见影。3.3 三连测标准场景、边界场景、错误场景各一次写完之后别急着发布你的 skill 至少要过一次“三连测”。这是我把大量不合格 skill 挡在发布门外的关键步骤。测试一标准场景挑一个最典型的用例走通完整流程确认核心输出质量达标。测试二边界场景故意制造极端输入比如超长的 diff、一行代码的改动、混合多种语言的改动看 skill 会不会崩、会不会丢失关键信息。测试三错误场景故意不提供完整信息看 skill 是否会主动索要缺失内容还是会乱给结论。每跑完一个测试我都会把实际输出存档到 tests/ 目录下并在 CHANGELOG 里记录失败原因和修复方式。这里必须说一句大实话一套流程在标准场景跑通只能说明“功能可用”连边界和错误场景也稳得住才说明“方法可靠”。3.4 Skill 也要做版本管理很多开发者的代码仓库做 git 管理但 skill 目录反而是裸奔的很多人改了之后没记录下次想回溯只能靠记忆。Skill 本身也是一种代码资产依赖它运行的 AI 模型也会升级模型升级之后同一个 skill 的行为可能会变这时候没有版本管理连排查问题都无从下手。我的做法是每个 skill 独立成一个 git 仓库或者独立目录SKILL.md 头部标注版本号CHANGELOG 记录最近三次改动背后的问题。不要小看这个动作因为你写 skill 时做的每个决策大概率都源于一次真实的失败这些记录就是最珍贵的经验库。4. 写 skill 最容易翻车的五个隐蔽问题下面这几个坑我在审核过的很多 skill 里反复见到有些自己也踩过。每一个都导致过实际使用体验的严重下滑值得拿出来单独说。4.1 把“目标”当成了“步骤”最常见的失败模式是在 Workflow 里写“检查代码质量”“确保安全性”“优化性能”这种话。这些是目标不是步骤。建议拆解成动作检查是否有未捕获的空指针异常检查 SQL 语句是否使用拼接检查循环体内是否发起了外部请求检查是否有未关闭的资源连接。只有动作可以被 AI 稳定执行目标只会让输出质量充满随机性。怎么判断自己写的是目标还是步骤把这句话前头加上“执行”两个字如果能读通就是步骤读不通说明你还是给了一个目标。4.2 上下文塞得太满AI 反而抓不住重点我最早写“日志异常分析” skill 时把所有命令解释、正则写法、告警规则全部贴进 SKILL.md结果 AI 在处理长文本时经常逻辑错乱输出一段没头没尾的结论。后来我把主文件精简成“识别日志格式 → 统计状态码 → 按严重度聚合 → 调用参考正则解析关键行 → 输出报告”把 90% 的细节移入 references/效果立刻回来了。原因是当前 AI 模型的注意力是有限的一次读入的 token 越多对每段内容的敏感度就会降低。SKILL.md 的作用是带路不是装下整个世界。越厚的 skill越需要在入口处做好指引让 AI 知道什么时候去翻参考资料而不是一口气全部吞进去。4.3 环境假设不清换个机器就废Skill 里如果写“用 python3 执行 parse_diff.py”必须先确认运行环境。不同的 AI 工具运行环境有差异有的能直接执行命令有的需要配置白名单还有的根本没有 Python 环境。我的经验是把环境信息写进 references/environment.md内容包括依赖了哪些外部命令、是否有需要安装的包、脚本的输入输出格式、禁止执行哪些危险操作。同时在 SKILL.md 里加一条“执行脚本前先确认环境变量是否存在缺失则告诉用户”。看起来保守实际换环境时能救回很多失效场景。4.4 忽略不同模型之间的行为差异同一个 skill 在 Claude 下执行得很稳换到另一个模型上可能完全跑偏这事我遇到过不止一次。原因是一些模型的弱项有的模型对多级目录结构理解力不足有的模型在长步骤任务中容易丢掉中间结果有的对“如果/那么”分支处理不稳定。解决方案是尽量使用通用的 markdown 结构和简单的指令语言不依赖某个模型独有的能力同时在测试记录里标注“在哪个模型、哪个版本下通过验证”。你的 skill 在某个模型下验证过不代表在别的模型下也成立这一点写清楚是对使用者负责。4.5 不设退出条件永远硬着头皮给答案我在前面提到过信息缺失时的处理这背后其实是一个更大的问题你的 skill 必须允许 AI 承认“我现在不能继续”。很多 skill 作者为了追求成功率把流程设计成了一条不归路AI 一进来就必须走到底就算输入信息完全不够它也会自己脑补出一堆假设来填充。这在工程上是灾难。Skill 里一定要有显式的退出条件例如“当进入本流程后发现用户未提供必要条件停止后续动作列出缺失信息”“当任务属于 out-of-scope 范围时告知用户更换 skill”“当执行脚本失败超过三次时停止尝试并上报错误”。退出条件不是能力不足的表现恰恰是一个成熟技能对自己边界有清晰认知的证明。5. 附 Review 清单发布前像审代码一样审 skillSkill 写完了测试也跑了但发布前最后一道关卡是 Review。我自己以前经常跳过这一步后来吃过发布一个不成熟 skill 的亏从此坚持每次发布前都按清单逐项自检。这套清单我按七个维度整理可以打印出来也可以在 skill 目录里存一份 markdown作为提交模板类别检查项通过标准定位与边界description 是否完整描述触发场景用户扫一眼就知道“当前任务适不适合用这个 skill”定位与边界是否有明确的 out-of-scopeAI 遇到范围外任务会拒绝或转交不会硬答命名名字是否直观不使用堆满专业术语看不清用途的名字命名名称是否重复在已有技能集中没有同名或高度相似的 skill步骤质量Workflow 里的步骤是否都是动词开头没有“保证”“提升”“优化”这类目标型描述步骤质量关键分岔点是否有“如果/那么”分支真实失败场景中的修复点已经写入流程步骤质量每个步骤是否定义了明确的产出物AI 知道这个步骤完成后要输出什么资源与依赖references 里引用的文件是否真实存在所有链接和文件路径可访问不出现 404资源与依赖运行环境和依赖是否写清楚换到另一台机器或另一个工具也能复现资源与依赖scripts 脚本是否有测试过至少跑通一个成功场景和一个失败场景测试与验收是否准备至少 3 个测试用例标准、边界、错误三类各一个结果已存档测试与验收是否记录实际执行输出测试记录里有真实输出文本不只是“看起来没问题”测试与验收是否标注过测试模型及日期以后模型升级后可回查兼容性安全与合规是否禁止了危险操作或需要确认自动执行命令前有明确确认机制安全与合规是否不包含敏感信息无密钥、无内部地址、无个人隐私信息可维护性是否有版本号和最近更新时间version、created、updated 字段齐全可维护性是否有 CHANGELOG记录最近三次改动的原因和结果这条清单用下来最大的价值是倒逼你把“模糊”的东西变“具体”。比如“命名是否直观”这条会逼你想清楚 skill 到底解决什么问题而“是否记录实际执行输出”这条会逼你真的去跑一遍测试而不是看了一下文档就拍板“没问题”。我自己的习惯是把这张 Review 清单本身也放进 skill 目录里这样每次迭代到一半被打断再回来时不用重新回忆当时的思路打开清单照着过一遍就行。最后再说一个朴素但很有用的体会skill 写的不是结果是流程不是替你把某件事做完而是让 AI 每次遇到同类问题时都能按一套可靠的方式把事情做完。所以创建 skill 的效率不取决于你打字多快而取决于你对自己的经验是否做过真正彻底的方法抽象。我自己现在写 skill 有个习惯每写完一版都要先当一次使用者拿真实任务去跑一遍流程而不是站在创作者视角自我欣赏。很多问题只要你愿意切换到使用者的角度多问一句“如果我是刚接触这个任务的 AI我能看懂这一步吗”就能在发布前及时拦住一大半翻车现场。如果你也正在建自己的 skill 库可以试试把第一个 skill 做成纯方法抽象版——不要收集任何具体业务知识进去只保留任务类型、流程骨架和边界规则看看它能不能跑通。跑通了你就掌握到写 skill 的核心手感了。