很多人在用 AI 编程助手的时候都有类似的体验同一个需求场景每次都要把上下文、约束条件、输出格式重新交代一遍稍微说漏一点生成结果就跑偏。时间一长人就开始烦躁心里清楚这些重复性的沟通完全可以沉淀下来但是又不知道怎么沉淀。这一两年各家 AI 编程工具陆续支持了“skills”这种机制我一开始也没当回事直到在一次实际项目里把每个月都要复用的一套代码审查流程写成了 skill 文件后来整整半年都是 AI 自动识别场景、自动执行检查、自动给我输出规范化建议才意识到这东西的威力被严重低估了。简单说skills 就是把你对 AI 的“调教”文档化、文件化、可复用化。它不是一串简单的提示词而是一套包含规则、示例、边界条件和工作流的“岗位说明书”。你既可以在 Cursor 这种图形化的编辑器里用也可以在 Claude Code、Codex 这类命令行工具里用甚至在一些支持 Agent 模式的笔记工具和自动化工具里也有类似的概念。这篇文章我不打算堆概念而是站在实操角度从文件结构、编写逻辑、踩坑记录到完整案例一条线讲清楚算是给那些想用 skills 但还没找到门道的朋友一份可以直接抄作业的参考。1. 为什么需要 Skills 文件把重复劳动变成一次性投资1.1 从“每次重新解释需求”说起先还原一个非常典型的场景。你负责一个 Java 后端项目每周都要做一次依赖安全审查需要 AI 帮你分析 pom.xml 里哪些依赖存在已知漏洞输出格式要包含依赖名、版本、风险等级、修复建议。没有 skills 的时候你每次都得复制 pom.xml 内容粘贴到对话框然后再写一大段说明请帮我分析漏洞、格式要包含什么、风险等级怎么定义、如果存在争议要先提示。这些动作至少花掉五分钟而且每次 AI 理解的风格都可能不一样有时候给你表格有时候给你大段文字有时候把无关紧要的依赖也报出来。使用 skills 之后你只需要写一个文件把上述所有规则写进去AI 会在你有需要时自动加载。比如你输入“帮我审查依赖”AI 就会根据 skill 文件里的规则自动索要项目文件、自动按预定格式输出、自动按风险等级排序甚至会自动去查 CVE 库。整个过程从“人指导 AI”变成了“AI 按标准执行”。这就是 skills 的第一层价值减少重复沟通成本。1.2 Skills 文件能装下什么三个层面解构我理解 skills 文件有三个层面的能力缺一不可。最底层是“指令层”告诉 AI 面对什么场景该做什么事这相当于给 AI 画了一幅行为地图。中间层是“约束层”明确告诉 AI 哪些事情不能做哪些输出必须遵守格式规范这相当于给 AI 装了护栏。最上层是“知识层”把项目背景、历史决策、最佳实践固化进去让 AI 的输出具备团队或个人长期积累的经验底色。很多人的 skills 文件写得不好根本原因是把三层内容混在一起只知道写口号式的“你要帮我做安全检查”却没有约束输出格式也没有沉淀项目历史结果 AI 做出来的东西还是泛泛而谈。拿我自己的一个实践来举例。我给前端团队写过一个 code-review skill指令层就一句话“对本项目前端变更执行代码评审”。约束层写了四条不允许忽略类型定义不允许提出无法落地的重构建议每条建议必须标注文件路径和行号风险等级只能有 high、medium、low 三档。知识层则放了两段团队历史决策的说明比如为什么项目里统一用 dayjs 而不是 moment、为什么禁止使用 index 作为列表 key。这三层一配合AI 输出的评审意见一下子就“懂行”了不再是一堆正确的废话。1.3 哪些人最受益三类典型用户画像我自己前后在三种角色上测试过 skills 的收益感受差别挺大的。第一类是“高频重复型”个人开发者典型特征是同时维护三四个项目每个项目都有自己的代码规范、文档格式、部署脚本经常需要在不同项目语境之间切换为他们定制每个项目的 skill相当于把项目上下文直接搬到 AI 脑子里效率提升最明显。第二类是“技术团队骨干”需要频繁给新人做代码审查、环境配置指导、知识库整理把团队的经验沉淀成 skill 文件新人遇到问题时由 AI 先按照成熟流程回答一遍解决不了再找真人团队重复答疑压力下降显著。第三类是“提示词工程重度用户”以前有大量精心调试过的 prompt 片段散落在各个地方通过 skills 把这些片段结构化、版本化管理起来清爽很多。这三类用户有一个共同痛点AI 工具的默认表现充其量只是一个“无所不知但不知道你的上下文”的聪明人而 skills 文件的作用就是把这个聪明人“培训成你团队里的一员”。从投入产出比看一个 skill 文件通常只需要集中精力写一两个小时但之后每天都在持续产生价值。特别是那些维护型项目一次配置、长期受益这种投资的回报率远高于每天重复粘贴提示词的时间成本。2. Skills 的核心工作机制与文件结构2.1 触发方式AI 如何知道该用哪个 Skill第一次了解 skills 的时候我最大的疑问是这个文件放在那里AI 凭什么自动找到它。直到我拆解了几个工具的加载机制才明白各种实现底层大差不差。主流方案有两种一种是基于目录约定比如把 SKILLS.md 放在项目根目录的 .cursor/rules 下、或 .claude/skills 下AI 在启动会话时自动扫描这些目录把文件内容作为系统提示词的一部分加载进上下文另一种是基于关键词触发你为 skill 定义一组 trigger keywords当用户消息中出现这些关键词时AI 动态加载该文件。不同触发方式对 skill 设计影响很大。基于目录全局加载的方式优点是稳定、不必担心漏触发缺点是会持续占用上下文长度因此这种技能文件必须写得精简否则反而会干扰 AI 抓取真正相关的信息。基于关键词触发的方式好处是针对性强、上下文利用率高坏处是触发条件写得不好就容易漏触发。我自己用得比较顺手的是“目录 关键词混合”把通用的项目规范写成全局加载的短文件把特定任务的详细流程写成关键词触发的长文件两条线并行既保证基础行为稳定又保证专项能力按需就位。2.2 一份 SKILLS.md 的标准解剖不同工具的 skill 文件名可以不一样但核心结构几乎都包含五块技能声明头YAML front matter、技能描述与触发条件、技能主体规则、技能参考示例、技能边界与升级说明。前端格式的 front matter 通常以三个短横线开始和结束里面用 YAML 定义 name、description、triggers、version 等元信息。YAML 部分的 description 字段非常关键很多工具靠这段描述做语义匹配和触发判断必须写清楚“这个技能解决什么问题、在什么条件下使用”。有一类大坑是 description 写得太虚AI 无法把用户的实际问题映射到这个技能上。比如你写“本技能用于代码审查”就不如写“当需要对 TypeScript/React 前端代码进行变更审查时使用尤其适用于 pull request 场景”。区别就在于后者描述了具体适用场景命中率完全不一样。主体规则部分要遵循“少而硬”原则。所谓“硬”就是可以客观校验的要求比如“每条安全问题必须标注 CWE 编号”“禁止使用 console.log 提交到生产分支”。而“软”的期望诸如“请提供高质量的分析”“请认真思考后再回答”AI 其实不知道怎么执行写了也白写。参考示例部分则是重中之重很多 skill 效果不佳就是没给例子。给 AI 一个“输入输出”的对照样本相当于人类入职培训时的老员工带教实际上一个精心设计的例子可以帮助压缩 AI 从理解到执行的路径。2.3 辅助文件体系为什么一个 Markdown 文件往往不够我最初理解的 skill 就是一个 Markdown 文件直到做了一个数据清洗技能发现要传入的参考文件越来越多模板越来越长一个文件变得臃肿不堪。这时才认真研究辅助文件体系其实一个 skill 可以是一个目录里面除了技能主体还能带脚本文件、模板文件、参考数据文件。比如代码迁移场景下可以把迁移规则文档拆成 RULES.md把典型迁移前后的代码对比放在 examples/ 目录下技能主体只保留流程编排逻辑这样一来主体文件内容短、加载快AI 需要用深度知识时再按路径去读取特定辅助文件。这种结构对上下文的利用效率提升是惊人的。我的经验是主体文件尽量控制在四五十行以内剩下所有墨水分流到对应辅助文件里。AI 工具现在普遍具备引用外部文件的读取能力你可以给技能文件配置一个 expected_files 列表要求 AI 在特定步骤去读取 projects/backend/pom.xml 或 docs/legacy-architecture.md。把“主干规则”和“枝叶知识”分离才是生产级技能文件的正确做法。3. 从零开始构建自己的第一个 Skill3.1 需求拆解先判断什么值得“技能化”不是所有任务都适合技能化。我发现最适合固化进 skill 的任务有三个特征频率高、规则清晰、容错要求严格。“频率高”保证了投入产出比“规则清晰”保证了 AI 容易理解你的期望“容错要求严格”指的是人工反复检查太累交给 AI 按流程执行可以让验收变成清单式检查。反过来如果一个任务本身探索性很强每次需求都不一样或者连你自己都没想清楚怎么做就不要急着写成 skill先把它当作普通对话去试。一个很好的切入点是找到你工作中“重复但不快乐”的任务。我自己就有个很典型的例子每次发布版本前都要整理 changelog涉及 git log 解析、commit message 分类、issue 关联、版本号规范。这个任务发生在每个迭代周期、规则相对明确、出错代价中等完全适合技能化。我把这个流程写成一个 20 行的 skill 文件从此每次发布前只要让 AI 去跑一遍技能流程五分钟拿到一份可以直接贴到仓管的 changelog效率提升立竿见影。3.2 编写核心指令把经验固化成规则写核心指令时最容易犯的错误是“把 AI 当人一样发号施令”。人和 AI 对语言的理解不同你需要的是规则性、可执行、无歧义的表达。建议每条指令都满足三个条件不依赖隐式背景、步骤顺序明确、每个动作有可验收标准。举个例子“分析代码中的安全风险”不是一条可执行指令“读取 src/ 目录下所有 .ts 文件识别 SQL 拼接、命令执行、路径遍历三类风险每发现一条输出对应文件和行号”才是一条合格指令。我会把核心指令分成三个区块工作流程区、约束规则区和输出格式区。工作流程区用数字列表表达先后顺序约束规则区用否定句为主例如“不要修改任何文件只输出分析结论”输出格式区给出一个结构模板。这种划分有实际工程依据AI 在处理复杂任务时会把最终输出组织成若干独立区块如果你不提前定义区块顺序和格式AI 很可能按自己的喜好组织结构最后结果看起来“信息很全”但“结构很乱”你还是要花时间整理。3.3 提供示例让 AI 有样可学我见过很多技术爱好者写的 skill 文件里面规则写了一大堆却一个参考例子都没有效果奇差。原因很简单规则描述得再精确AI 不一定能理解你在真实场景中的期望颗粒度。示例的作用是把文字规则翻译成实际形态。我强烈建议每个 skill 文件至少包含一个完整示例格式最好是“任务输入 技能输出”的对照而且输入输出都要尽量贴近真实场景不要用玩具级别的例子。以 changelog 技能为例我给出的示例输入不是简短的“生成 changelog”而是精心构造的一段 git log 片段和两条 release note 期望。示例输出则展示了版本号如何递增、commit 如何归入 feature/fix/refactor/docs/maintenance 分类、breaking change 如何置顶。当 AI 真正拿到完整示例之后它对规则的解读会精确很多。做多了你会发现示例不是说给 AI 听的而是说给未来的你自己听的下次你想改动行为时对照示例调整规则远比对着说明书重看一遍更直观。3.4 测试与迭代用三个问题验证一个技能写完技能文件不要直接宣布大功告成我建议用一套固定的验证流程第一把技能文件复制进项目对应目录开一个全新会话测试触发是否正常第二输入一个符合技能描述的任务检查输出是否符合格式要求第三故意输入一个边缘场景任务验证技能是否会不当触发或拒不触发。三次测试过了这个技能才算基本可用。我在实践里还发现一个规律技能质量提升最快的方式是“使用后复盘”。每次技能输出不太满意时不要直接去后台改先把“你希望是什么样”和“AI 实际给了什么”的差异原因找出来——是规则写得不清楚是示例引导有误还是触发匹配有问题大多数时候是规则描述存在歧义改一个词就能明显改善。把这个复盘习惯坚持下来技能文件会越来越像你本人的做事习惯。4. 真实场景案例让 AI 自动执行前端审查4.1 场景背景与技术选型考量用一个我实际维护过的项目来走一遍完整流程。这个项目是一个中型 React 管理后台代码规模大约 8 万行团队成员五人前后端联调频繁前端代码质量是团队长期关注的痛点。我们当时想做的事情很明确每次代码提交进入审查环节时AI 要自动检查 TypeScript 类型问题、未使用的引入、危险 API 调用、状态管理误用这四类问题并且按统一格式输出风险报告。在工具选型上我们起初在两个方案之间纠结方案 A 是把规则写成一个 git hook 脚本在提交时自动调用 AI 进行审查方案 B 是把审查流程做成 skill 文件由开发者在需要时手动触发或者由 IDE 在打开文件时自动提示。两种方案的取舍很有意思。方案 A 的优点是自动化程度高但每次提交都要等待 AI 响应几十秒在频繁提交的节奏里非常干扰心情方案 B 虽然需要多一步手动触发但胜在可控且不打断心流还能在合适时机获得完整报告。我们最终选择了方案 B实践下来正确决定——因为审查类任务本身就不是每秒钟都要执行的人主动触发更能保证注意力的集中。4.2 技能文件的完整配置示例下面是我们在前端项目中实际使用的 skill 文件简化版去掉了一些团队私有信息。先看 front matter 部分--- name: dep-audit description: 对 Java Maven 项目执行依赖安全审查评估已知 CVE 漏洞、许可证合规性和版本滞后情况适合在升级依赖、发布前巡检或收到安全告警时使用。 triggers: - 依赖审查 - 安全审计 - check-deps version: 1.2.0 ---关键字段说明description 用了“面向对象”描述而不是功能描述核心是“什么项目类型 什么场景触发 适合什么时机”这显著提升了语义匹配命中率。triggers 提供了三个显式触发词兜底这是防止描述语义匹配失败后的第二保险。为不同技能选择版本号可以让你今后升级时清楚知道现场环境用的哪套规则。主体部分的结构如下# 技能依赖安全审查 你是一名具备 OWASP 依赖检查经验的 Java 安全顾问。 ## 执行流程 1. 扫描项目中的 pom.xml 或 build.gradle提取所有直接依赖及其版本。 2. 比对已知 CVE 数据库识别存在已知漏洞的依赖记录漏洞编号、影响范围、修复版本。 3. 检查依赖许可证类型标记 GPL/AGPL 等可能引起合规风险的许可证。 4. 对比 Maven Central 最新版本计算版本滞后时间以月为单位。 5. 综合输出风险报告。 ## 输出格式 报告必须按以下顺序输出 - 风险条目列表每条使用风险等级前缀[CRITICAL] / [HIGH] / [MEDIUM] / [LOW] - 每条必须包含依赖名、当前版本、修复版本、风险原因 - 最后追加一段“处理建议”列出优先升级顺序。 ## 约束规则 - 只输出分析结果不修改任何项目文件 - 不报告传递依赖除非 CVE 影响级别为 CRITICAL - 不报告已停产但无已知漏洞的依赖 - 每条风险必须给出明确的修复动作描述执行流程部分的顺序设计是有讲究的。先让 AI 建立依赖全景图再围绕依赖网络做纵深分析最后输出结构化报告这是审查类任务最合理的工作流。如果不给顺序AI 有时候会先挑出一个高风险依赖就展开长篇大论把低风险但有合规问题的地方漏掉所以流程顺序就是质量保障。4.3 配套的模板文件与参考产物技能还需要一个 sample-output.md 文件作为参考示例我把一次真实审查的输出精简成了以下形式放进示例文件核心是让 AI 看到一个“已格式化”的最终产物长什么样## 依赖审查报告backend-service [CRITICAL] com.fasterxml.jackson.core:jackson-databind:2.13.4 - 2.15.3 原因CVE-2023-35116 反序列化远程代码执行 [HIGH] org.springframework:spring-web:5.3.29 - 5.3.31 原因CVE-2023-34034 拒绝服务涉及 HTTP 请求处理 [MEDIUM] commons-io:commons-io:2.11.0 - 2.14.0 原因CVE-2024-47554 路径遍历可能导致文件覆盖 ## 处理建议 1. 优先升级 jackson-databindCRITICAL 且影响全局数据解析 2. 其次升级 spring-web暴露面大 3. commons-io 可在下个迭代窗口处理加上参考示例后同一套规则下 AI 的输出质量明显稳定了很多。没有示例之前AI 有时会用自然语言把风险描述得很模糊有时只输出修复版本不说明原因。有了示例它就知道“长成这样才算合格”。另外我还强烈建议在技能目录中放一个 config.json 或 settings.json 来定义“本技能应该读取哪些文件、忽略哪些文件”这样 AI 在审查时会自动聚焦到真正的依赖声明文件上不会因为同时存在多个 pom.xml 或 gradle 文件而分心。4.4 实际运行效果与耗时分析这个技能上线后我统计了三周的使用数据。触发耗时平均在 8 到 15 秒之间运行结果基本都是可直接贴到 MR 描述里的完整报告。人工介入最多的地方是“处理建议”的优先级排序AI 对业务影响面的判断确实不如人比如两个 HIGH 都在修复版本列表里但哪个模块更重要需要结合当前业务规划决定。不过这个问题我也通过在第 5 步追加了“结合当前模块活跃度标注优先级”解决了大半。实际执行中还有个意外收获AI 在执行这个技能时由于流程第一步要扫描 pom.xml它会顺带发现一些依赖声明中的语法错误和无效版本比如引用了不存在的版本号。相当于每次审查不仅产出安全报告还顺带做了一遍依赖声明文件的健康检查。这也让我意识到一个设计良好的技能流程天然具备“一石二鸟”的能力因为流程规定了每一步的代理行为路径上的副产品自然就被发现了。5. 常见问题与排查技巧实录5.1 技能“偶尔生效、偶尔失效”怎么办这个问题是我在社区里看到最多人抱怨的我也踩过很大的坑。排查步骤如下先确认触发方式看你的技能是基于目录全局加载还是关键词触发如果是关键词触发检查触发词是否过于宽泛或过于具体。我曾经写过一个技能触发词设置为“审查”后果是聊到任何一个带“审查”的词都会触发它反而把正常的对话带偏了。后来又改成“依赖审查”“安全审计”这类复合词命中率立刻正常了。第二个排查方向是上下文过长截断。有些工具在会话上下文接近上限时会优先丢弃一些非关键系统提示一些未配置优先级偏低的技能内容就被挤出去了。解决办法是技能主体保持在精简状态让工具在加载时不会因体积过大成为被优先压缩的对象。此外确认工具版本也值得做有些工具升级后加载行为会有变化不是你的文件写得有问题是版本兼容的原因。5.2 AI 总是忽略我写的规则怎么办很多人在技能文件中写了“你务必遵守以下规则”但 AI 还是会违反。我慢慢发现原因通常不是 AI 不听话而是规则写得让 AI 无从精确执行。比如你写“不要使用过时的依赖”AI 不知道“过时”的判定标准是什么它认为 2.13.4 是安全的但你觉得 2.11.0 才是安全的。解决方案是把模糊概念转成可检测条件写明版本对比的基线库、判定阈值和例外清单。另外要善用“失分制”而不是“加分制”。AI 对“必须做到什么”的执行力度远低于“不要做什么”。与其写“确保每次输出都包含依赖名”不如写“缺少任何依赖名视为不合规输出请重新生成”。从我多次测试的经验看后者对 AI 行为的纠正力更强。本质上是因为 AI 在生成过程中更擅长规避风险列表而不太擅长逐一核对自己是否穷尽了加分项清单。5.3 技能文件越多越好吗不是而且这个问题我亲身验证过。早期我给团队一口气写了十几个技能以为都配齐了就很厉害结果真正常用的只有三四个。多余的技能文件不仅占用上下文窗口还会造成匹配歧义。有几个类似的技能描述互相重叠AI 有时候选错文档行为就会出现不可控的偏差。我现在采用“10/30 法则”技能文件总数不超过 10 个常用技能保持在 3 个以内。多出来的需求先判断是不是真的高频如果不是放到个人知识库中作为普通文档即可。技能不是越全越好而是越精准越好这和一个团队里各司其职的人搭配才是最有效的道理是一样的。有限的上下文留给真正可复用的核心技能比堆砌一堆“看起来有用”的技能重要得多。最后分享一点个人心得技能文件这个东西说到底就是把你在开发中积累的判断力结构化。它不神秘也不需要夸夸其谈的理论就是老老实实地把规则写清楚、把示例写完整、把边界写明白然后让 AI 照着执行。我自己最大的感受是花了一个下午把一个高频任务写成技能之后每天节省的时间会以指数级持续回馈。可能一开始写不好迭代几轮后就会明显感觉到 AI 越来越“懂你”。这个过程中最关键的一点是要持续复盘不是写完就完了而是每次看到不满意的输出都追根究底去改一版规则。坚持几个月你会有一种很奇妙的体验好像真的多了个极聪慧又极有章法的老同事虽然它看不见摸不着却扎实地改变着你干活的方式。