真正把skills用明白的人从来不是收藏了多少现成技能包而是懂得自己动手拆解、打磨、沉淀一套属于自己工作流的技能体系。这篇就聊聊我从零搭建Agent Skills下面统一叫skills的完整过程从原理到实操、从踩坑到优化把我验证过的路径和教训都摊开讲。我最早接触skills这个概念是在用AI编程助手的时候——你反复让它做代码审查、写单元测试、整理提交信息每次都要重新描述一遍需求偶尔它还会给出不稳定的结果。后来我意识到问题不在模型能力而在于我没有给它一套“可复用的能力定义”。于是我开始研究skills机制自己动手把高频任务固化成技能包实测下来效率提升非常明显而且输出质量稳定得多。如果你也遇到“AI助手时聪明时糊涂”“同类型任务反复折腾”“团队协作时大家的AI表现参差不齐”这些问题这篇内容就是为你准备的。我会从底层原理讲到目录结构、从配置语法讲到调试技巧最后附上我攒出来的问题排查速查表。不管你是写代码的程序员还是做内容、做数据分析、做运营的从业者只要你在用AI辅助日常工作这套方法论都适用。1. Skills到底是什么从“每次描述”到“一次沉淀”1.1 不是魔法是一套被AI“记住”的操作手册很多人第一次看到skills这个词以为是某种黑科技插件。其实它的本质非常朴素把一段高质量的系统提示词System Prompt固化成文件让AI在特定任务启动时自动加载这段指令从而稳定地按照你预设的方式工作。如果把AI助手比作一位新来的实习生平时你每次都要告诉它“按这个格式整理”“这些规则别违反”“这个步骤要先做”。skills做的事情就是把这些口头交代写成一本图文并茂的岗位手册放进它的工位抽屉。下次你说“按老规矩来”它自己就知道翻开哪本手册照着执行。在主流AI编程工具里比如Claude Codeskills通常存放在项目根目录的.claude/skills下也有全局配置目录用于跨项目共享。每个skill是一个独立文件夹内部必须有一份SKILL.md作为技能定义文件还可以附带参考文档、模板脚本、示例代码等资源。工具会在后台自动识别与当前任务匹配的skill并把它的核心内容注入到上下文窗口中。1.2 它解决的三个真实痛点第一个痛点是不可控。裸用AI时同样的需求在不同时间、不同对话里可能得到完全不同的结果。今天让它写代码审查意见它给你列了10条明天再让它做同样的事可能只给5条而且格式全变。skills通过固定指令模板把输出格式、审查维度、评判标准全部锁定结果自然就稳定了。第二个痛点是效率损耗。高频任务如果每次都要重新描述需求、贴规则、给例子大量时间浪费在“对齐上下文”上。我用skill之后启动一个代码审查任务只需要一句话AI会自动从我沉淀的skill里加载审查规范、检查清单、输出模板省掉至少5到10分钟的重复沟通。第三个痛点是经验无法沉淀。你会写代码、会做分析、会写文案但这些方法论只存在你脑子里。一旦换工具、换团队、换设备所有积累清零。skills把个人经验文本化、结构化、可迁移化换台电脑同步一下配置目录工作方法就全带过来了。对团队而言一份统一的skill文件就是团队AI协作的SOP。1.3 适用场景和真正适合用它的人skills最适合的场景有三类。一是规则明确、步骤固定的任务比如代码审查、单元测试生成、SQL查询编写、报告格式化二是需要强制遵守规范的工作流比如提交信息按Conventional Commits格式编写、文档必须包含特定章节三是需要调用外部工具或脚本的复合任务比如“读取日志文件→分析错误模式→生成排查报告”。如果你只是偶尔让AI写几句文案、做一次翻译skills对你来说可能有点大材小用。但如果你发现自己经常在同一个类型的任务上跟AI反复拉扯或者你希望AI的输出能稳定达到某个质量线那这个东西绝对值得投入时间去搭建。2. 从零搭建一个Skill目录结构和SKILL.md的核心语法2.1 一个标准skill目录长什么样先上一份我在实际项目中使用的目录结构你可以直接对照参考.claude/ └── skills/ └── code-review/ ├── SKILL.md # 技能定义文件主入口必填 ├── review-rules.md # 审查规则详细说明作为参考文档 ├── checklist.md # 逐项检查清单AI会逐项核对 ├── templates/ │ ├── review-output.md # 审查报告输出模板 │ └── severity-guide.md # 严重级别判定标准 └── scripts/ └── extract_changes.py # 可选辅助脚本生成变更摘要这里最核心的文件只有SKILL.md其他所有文件都是可选的辅助资源。技能名称就是文件夹名code-review这个名字在后续触发时非常关键。2.2 SKILL.md的YAML前置配置metadata决定了技能“长什么样”SKILL.md的开头必须有一段YAML格式的前置元数据frontmatter这段配置就是技能对外展示的“身份信息”。我用一个实际案例说明每个字段的作用--- name: code-review description: 对代码变更进行系统性审查识别Bug风险、安全问题、性能隐患和可维护性问题并输出结构化审查报告。仅在用户要求审查代码变更或提交记录时使用。 allowed-tools: bash, grep, read, glob disable-model-invoked-usage: false version: 1.2.0 ---name字段是技能的唯一标识最好全小写、用连字符分隔。description是这个技能最重要的字段——在Claude Code这样支持自动识别技能的工具里系统正是通过把用户请求与每个skill的description做语义匹配来决定触发哪个技能。所以description要写清楚“这个技能处理什么任务”也要写清“什么情况下不要用”避免误触发。allowed-tools限制这个技能可以调用哪些工具权限不声明的一律不能用。这是安全边界能防止技能以过高权限执行危险操作。disable-model-invoked-usage设为false表示允许模型根据任务描述自动调用这个技能如果设为true则只能由用户手动指定适合不想让AI擅自触发技能的场景。2.3 SKILL.md正文的写作逻辑为什么比普通提示词更有效前置配置写完正文才是重头戏。一份有效的SKILL.md需要包含三个关键层次目标定义、执行步骤、质量验收标准。目标定义部分要明确“为什么做这个任务、最终的产出是什么形态”。执行步骤部分把任务拆解成可操作的行动序列每一步最好都有验收标志。质量验收标准则回答“做成什么样才算合格”的问题这能有效减少AI自由发挥的空间。我写正文时习惯遵循一个“四段式”结构Role角色定义、Context背景说明、Steps执行流程、Output Format输出格式。下面是一个精简但完整的示例# 代码审查技能 ## 角色 你是一名资深软件工程师负责对代码变更进行系统性审查。你的目标是发现缺陷并给出可执行的修改建议而不是泛泛夸奖代码写得好。 ## 背景 用户会提供一段代码变更可能是git diff、单个文件或完整函数。审查范围仅限于变更涉及的部分不扩展到无关代码。 ## 执行步骤 1. 理解变更先阅读完整diff梳理修改涉及的文件、函数和调用链。 2. 逐项核查对每个变更点运行以下维度的检查详见checklist.md。 3. 按严重级别归类问题Critical(阻断合并)、Warning(建议修改)、Suggestion(可选优化)。 4. 对每个问题给出修复建议说明为什么这样改以及可能的风险。 ## 输出格式 - 按“严重级别 文件路径 问题描述”三级排序。 - 每个问题包含定位信息、问题说明、为什么这是问题、修复建议、参考代码片段。关键点在于这套正文跟我平时直接粘贴给AI的提示词最大的区别是它被拆成了可维护的模块任何一个维度单独更新都不会影响其他部分。比如我想把审查维度从5条扩展到7条只要改一下checklist.md引用不需要重写整个skill。2.4 用辅助文件承载大段规则为什么不要全塞在SKILL.md里很多新手会把所有规则一股脑写进SKILL.md结果文件膨胀到几百行模型加载和解析都变慢而且因为上下文被大量无关细节占用注意力反而会被稀释。我的做法是SKILL.md只保留核心流程和关键约束大段规则、参考模板、示例代码全部放进辅助文件在正文中通过“详见xxx文件”来引用。这样做的另一个好处是同一个SKILL.md可以用在不同工具Claude Code、Cursor等之间迁移辅助文件的相对路径引用也都能保持有效。3. 实操记录我如何打造一个“靠谱的”代码审查Skill3.1 起步先明确我要它解决什么问题代码审查是我日常最高频也最需要稳定质量的场景。直接让AI审查代码问题很明显它会漏掉逻辑边界、给出的建议泛泛而谈、严重级别分不清、报告格式每次都不一样。所以我决定打造一个以“严格、实用、可落地”为核心的code-review技能。定位想清楚之后我先梳理了几个关键参数审查范围仅限于用户提供的diff/文件审查维度正确性、安全性、性能、可维护性、测试覆盖严重级别分三档输出格式按文件聚合、每项含修复代码示例。这些参数后来直接成为SKILL.md的骨架。3.2 第一次落地最小可行版本的三个组成部分第一个版本我没有贪大求全只写了三样东西简化版SKILL.md约70行、一个checklist.md覆盖5个维度的检查项、一个输出模板。checklist.md在这里起到了至关重要的作用——它把AI的“自由发挥”框死在了可控范围内。比如“正确性”维度下我要求它必须检查空值处理、边界条件、并发安全、异常路径在“安全性”维度下要求检查注入风险、敏感信息泄露、权限校验缺失。每一类检查项都配了一个示例代码片段和对应的提问方式。输出模板长这样## 审查报告 ### 变更概览 - 文件数{n} - 新增行数{n} - 删除行数{n} ### 严重问题Critical {none/列表} - [文件:行号] 问题描述 - 为什么{说明} - 修复建议{代码或步骤} ### 建议修改Warning {none/列表} ... ### 可选优化Suggestion {none/列表} ...这个模板让AI的输出结构固定下来无论它审查哪个项目、哪种语言的代码报告的骨架都一样我扫起来特别快。3.3 迭代打磨把“我认为重要但AI总忽略”的东西沉淀进技能第一版用了大约一周效果已经比裸用AI稳定很多但我积累了一堆新的改进想法。比如AI总是忽略对“变更影响范围”的分析只盯着diff本身看导致经常漏掉“改了一个公共函数签名所有调用方都受影响”这类问题。于是我在SKILL.md里加了一步专门的影响分析。另一个高频问题是AI给出的修复建议有时跟项目既有代码风格冲突。这本质上是因为技能文件里没有项目的编码规范。我后来在主目录的.claude/rules.md里写了项目级编码规范并且在SKILL.md执行步骤里加了一条“修复建议必须符合项目编码规范详见rules.md”。多文件协作的效果立竿见影建议的采纳率明显提升。迭代到第三四版之后这个skill已经跟我手动作业时的审查质量持平甚至超出而且时间成本低得多。下面是我在打磨过程中总结的几个具体心得给AI“看什么”明确说明只审查变更部分避免它滔滔不绝讲全局优化建议。给AI“怎么判”严重级别必须跟具体标准绑定不能让它自己凭感觉定级。给AI“怎么输出”模板里的占位符、排序规则、段落结构全部固定连标题层级都写死。3.4 在Claude Code里调试skill的真实流程调试skill是迭代过程中最频繁的操作。我用的流程是这样的先做一次单次运行让它在当前对话里启用code-review技能随便找一段diff测试观察输出。每次测试时我都会特别记录三件事输出是否符合模板结构、是否遗漏了checklist里提到的检查项、修复建议是否与项目实际代码风格匹配。发现问题后直接编辑SKILL.md或辅助文档然后重新开启一个会话再测。为什么要开新会话因为技能内容在对话进行中被多次注入后模型可能已经“记住”并遵循了旧版本不重开会话的话无法准确判断新改动是否生效。频繁调试过程中有一个小技巧我用Claude Code的“--debug”模式观察它到底有没有加载我的技能文件、加载了哪一份、在哪个顺序加载。如果技能文件没被识别这个模式下能看到明确的error记录节省大量猜谜时间。4. 技能设计中的关键方法论命名、描述、步骤拆解与经验沉淀4.1 命名和描述决定AI“能不能找到”你的技能在支持自动技能识别的工具里AI是根据description字段来判断何时加载哪个技能的。所以描述写得好不好直接决定了技能能否被正确触发。我总结了一个“两要两不要”原则。要写清楚技能的适用输入“当用户提供代码diff时”和典型输出“生成结构化审查报告”不要写模糊的使命宣言“帮助用户提升代码质量”也不要把多个任务的职责混在一个描述里“审查代码并生成测试并更新文档”。命名方面如果技能内部使用场景单一就用一个最贴切的词组比如code-review如果同一个技能需要覆盖多种相似任务命名可以用领域前缀比如frontend-accessibility-check。关键是一致性别在命名上玩花活让AI和你的队友都能一眼看懂。4.2 步骤拆解高质量技能的核心秘密是“决策树”我观察到一个规律粗粒度的步骤“审查代码”“分析风险”对AI的帮助远远不如细粒度的决策路径。比如## 执行流程 1. 读取变更文件 2. 判断变更类型 - 如果是逻辑修改检查边界条件、空值、并发安全 - 如果是接口定义变更检查所有调用方是否兼容 - 如果是依赖更新检查版本兼容性和弃用API 3. 根据变更类型从checklist中选择对应维度做深度检查 4. 汇总输出报告这种“条件分支”式的写法本质上是把资深工程师的思维方式外化成了AI可以执行的指令。它远比“全面检查所有维度”更高效因为模型不用在每一步都做价值判断直接沿着我们在技能里定义的路径往下走就行。4.3 经验沉淀把“我的主观标准”变成“AI可执行的标准”经验沉淀是技能设计中最有价值也最容易被忽略的部分。每个人的工作流里都有一套“只可意会不可言传”的标准你觉得什么样的测试才叫有效什么样的代码是“可以接受”而非“完美”什么样的报告才算“逻辑清晰”我写skill的一个固定动作是每次跟AI协作后发现“它的输出虽然符合我给的模板但没有抓到我真正想抓的点”就回去把那个“点”写成可执行的规则加进SKILL.md或checklist。这个过程有点像我维护一份“思维转译文档”——把我的直觉、品味、经验一点点翻译成AI能理解和执行的文本。比如我做内容大纲技能时一开始只写了“生成文章大纲”结果它常给出四平八稳的展开。后来我在技能里加入了我的判断标准“开头要有冲突或好奇心钩子”“每节必须有一个具体案例支撑”“结尾不允许用‘总之’这类空泛总结”。加了这几条之后输出立刻有了灵魂因为那些原本只在我脑子里的“文感”被转译成了可执行规则。4.4 版本管理和迁移让技能成为可持续资产技能文件本质上也是代码值得享受版本管理。我对每个skill都维护了version字段每次行为变化都会递增版本号并更新CHANGELOG。跨工具迁移时SKILL.md的兼容性取决于YAML字段是否被目标工具支持。比如有些工具不识别allowed-tools那这个字段就会被忽略不影响其他部分的运行。如果你有迁移需求最稳妥的做法是保持SKILL.md主体为纯Markdown内容让工具专属的配置都放在YAML和辅助文件中。5. 常见问题与排查技巧实录5.1 速查表学到就是省下的排查时间我在实践中遇到过不少问题有些花了我半天才定位到原因。这里直接给你一份速查表现象可能原因排查方向解决方案AI完全没提到skilldescription与用户请求语义不匹配测试description里的关键词是否能命中触发场景改写description明确任务的输入输出、触发条件和排除条件skill加载了但输出混乱SKILL.md正文层级不清晰检查执行步骤是否足够具体、顺序是否明确用“决策树”式分支重写步骤固定输出模板AI不遵守checklist规则checklist太长上下文被稀释观察模型是否引用了checklist内容精简checklist到5~10个核心维度多余内容拆成参考文档跨会话行为不一致技能文件在长对话中被新上下文覆盖新开会话测试避免同会话内反复调试维护好版本号确保修改后在新会话中验证技能不生效但无报错文件名/目录结构不规范检查SKILL.md文件名是否准确YAML是否有语法错误严格按模板结构创建用YAML校验工具快速检查多技能被同时激活description范围重叠检查多个技能的description是否存在语义冲突给每个技能加排除条件明确“什么情况不使用”5.2 AI“有选择地”遵守规则如何对抗提示注入和注意力漂移我遇到过很典型的一类问题SKILL.md里写了十几条规则AI执行前几条执行得特别好越往后越敷衍。这是注意力漂移——规则列表越长模型对尾部内容的遵循度越差。我的对抗策略有三个第一条是把最关键的、不可妥协的规则放在最前面第二条是把“数量多、内容细”的规则转移到辅助文件中SKILL.md只引用而不是内嵌全部第三条是在执行步骤里强制设置“检查所有checklist项”的确认动作命令它每一行逐条标注“通过/不通过/不适用”不给它“意译”的空间。5.3 日志和调试如何确认技能真的被加载了很多时候你觉得技能没生效其实它生效了只是被对话中更后面出现的指令覆盖了。或者它压根没被加载因为你写的目录名不对。快速区分这两种情况的办法就是看日志。用Claude Code的话启动时加--debug标志然后在日志里搜索你的技能名称。能看到“Loading skill”之类的记录说明文件路径和识别都正常如果找不到就去检查目录是否在正确的位置、文件名是否严格是SKILL.md、YAML是否合法。如果你用的是Cursor或者其他支持自定义Agent的工具一般也都有类似“查看Agent上下文/会话日志”的入口逻辑是相通的。5.4 从单个技能到技能库组织和维护的进阶建议当技能数量超过5个之后零散维护会很痛苦。我建议你把它们按“领域/任务类型”分目录管理比如写作类、代码类、分析类、运维类。同时在你平时放个人笔记/文档的地方维护一份总索引记录每个技能的用途、版本、最近修改时间。还有一个特别重要的进阶经验技能之间也可以“引用”彼此。比如我写code-review技能时引用了project-rules技能里的一部分规范实现方式就是在SKILL.md里写“关于编码风格请参考project-rules技能的checklist”。这种父子结构能有效减少重复编写也让技能体系越来越像一个真正的“团队知识库”。我的最终心得这批技能我陆陆续续迭代了差不多两个月前后写了十几个最后真正高频在用的其实不到一半。但这个过程给我的最大收获不是那几个能用的技能文件而是我彻底理解了“如何把自己的经验转译成AI能执行的语言”这件事。有些技能一开始写得又长又全以为AI知道的指令越多输出越准结果反而拖慢了响应、稀释了重点。后来我把它们删掉一半精炼成几行核心规则效果反而更好。这跟我带人的经验很像新人手册不用写一百页把关键的决策点和判断标准写清楚比堆砌信息有用得多。还有一点心得是技能维护要跟着实际任务走。我每次在真实任务里发现某个输出不对劲回去改掉的那一笔往往都是整个技能里最值钱的部分。因为那是实际经验对技能的一次校准——你的主观标准就这样一点点变成了AI的肌肉记忆。如果你也想为自己的工作流沉淀一套skills别想着一步到位。先挑一个你每周都会遇到的高频任务用一个周末搭出最小可用版本然后放到真实场景里去接受毒打每被坑一次就回去改一版。不出一个月你会拥有一份比任何现成模板都适合你自己的技能资产——而且这个过程本身就是一次对个人工作方法的极好复盘。