1. 从零理解Skill它到底是什么为什么值得花时间1.1 Skill的本质给AI装上一套可复用的“操作手册”很多人第一次听到“Skill”这个词脑子里浮现的可能是游戏里的技能树或者是某种需要长时间训练才能掌握的能力。但在AI工具链的语境下Skill的含义要具体得多——它本质上是一份结构化的指令文件通常以Markdown格式存在用来告诉AI模型在特定场景下应该怎么做、按什么步骤做、注意哪些细节。你可以把它理解成给一个新员工写的SOP。新员工能力再强如果不告诉他公司的流程、规范、常用工具他也要花大量时间试错。Skill就是这份SOP只不过服务对象从人变成了AI。一份好的Skill能让模型在特定任务上的表现从“勉强能用”提升到“稳定可靠”而且每次调用都保持一致不会因为对话上下文的微小变化就产生截然不同的结果。我最初接触Skill这个概念时觉得它跟Prompt Engineering差不多无非是写一段更长的提示词。但实际用下来发现两者有本质区别。Prompt更像是一次性的对话指令你问一句它答一句对话结束就散了。Skill则是持久化的、可版本管理的、能跨会话复用的资产。你写好一份Skill文件放在项目目录里下次打开编辑器或者AI工具时它还在那里随时可以调用。这个差异看起来不大但在实际工作中带来的效率提升是数量级的。1.2 为什么现在大家都在聊Skill最近几个月Skill相关的讨论明显多了起来。Claude Code有SkillCodex有Skill各种AI编程工具都在推自己的Skill体系。背后的原因其实不复杂大模型的裸能力已经足够强了但强不等于好用。一个模型能写代码不代表它知道你的项目用什么框架、遵循什么代码规范、部署流程是什么。Skill就是填补这个 gap 的东西。另一个推动因素是Agent的普及。Agent和Skill经常被放在一起讨论两者的关系可以这样理解Agent是执行者Skill是执行者手里的工具箱。Agent负责决策“要做什么”Skill负责告诉它“具体怎么做”。没有Skill的Agent就像一个聪明但没受过培训的实习生什么都敢干但什么都干不精。有了Skill之后Agent在特定领域的表现会稳定很多。从热搜词也能看出来大家关注的方向很分散有人搜“skill怎么编写”有人搜“claude code skill”有人搜“科研skill”还有人搜“ppt skill”。这说明Skill的应用场景已经远远超出了编程领域正在向科研、办公、设计等方向渗透。这是一个很自然的扩展过程因为任何有固定流程的工作都可以被Skill化。1.3 这篇文章适合谁看如果你属于以下几类人这篇文章应该能给你一些实用的参考已经在用AI编程工具比如Claude Code、Cursor、Codex等但觉得每次都要重复交代背景信息很烦的人想把自己或团队的工作流程固化下来让AI能稳定执行的人对Prompt Engineering有一定了解想进一步系统化管理提示词的人做科研、写论文、做PPT等非编程场景但想用AI提效的人纯粹好奇Skill是什么、怎么玩的人我会从Skill的创建讲起然后讲怎么修改和迭代最后聊一些认知层面的总结。中间会穿插具体的文件示例、操作步骤和踩坑经验。文章里提到的工具和方法都是我自己实际用过的不是从文档里抄来的。2. Skill的创建从一份空白的MD文件开始2.1 先想清楚这个Skill要解决什么问题动手写文件之前最重要的一步是想清楚这个Skill的边界。我见过太多人包括我自己早期一上来就开始写内容结果写着写着发现范围越扩越大最后变成一个什么都想管但什么都管不好的四不像。一个实用的方法是问自己三个问题第一这个Skill服务的具体任务是什么比如“帮我写单元测试”就是一个清晰的任务“帮我写代码”就太宽泛了。任务越具体Skill的内容就越有针对性效果也越好。第二这个任务的输入和输出分别是什么输入是代码文件、需求描述还是错误日志输出是测试文件、修改建议还是执行报告把输入输出定义清楚Skill的结构自然就出来了。第三这个任务有哪些容易出错的点比如写单元测试时容易漏掉边界条件、容易mock过度、容易把测试写得太脆弱。这些易错点就是Skill里需要重点强调的内容。我自己的习惯是在写Skill之前先用一段话把这三个问题的答案记下来放在文件最开头作为注释。这样后面修改的时候也有个参照不会跑偏。2.2 Skill文件的基本结构一份Skill文件通常包含以下几个部分我用一个实际的例子来说明。假设我要写一个“代码审查”的Skill文件大概长这样# Code Review Skill ## 用途 对指定的代码文件进行审查输出问题列表和改进建议。 ## 触发条件 当用户要求审查代码、检查代码质量、或者提交代码前需要review时使用。 ## 执行步骤 1. 读取目标文件理解代码的整体结构和用途 2. 检查以下维度 - 命名规范变量、函数、类名是否清晰且符合项目约定 - 错误处理是否有未捕获的异常、是否有静默失败 - 边界条件空值、越界、并发等情况是否处理 - 性能隐患是否有不必要的循环嵌套、重复计算 - 安全隐患是否有注入风险、敏感信息泄露 3. 对每个发现的问题给出严重程度高/中/低和具体修改建议 4. 输出格式按严重程度分组每条包含文件位置、问题描述、建议修改 ## 注意事项 - 不要过度挑剔风格问题除非项目有明确的lint规则 - 优先关注逻辑错误和安全问题 - 如果代码整体质量不错也要明确指出做得好的地方这个结构看起来简单但每一部分都有讲究。用途和触发条件帮助AI判断什么时候该用这个Skill执行步骤是核心内容注意事项则是经验沉淀。我建议刚开始写的时候不要追求完美先把框架搭起来后面再慢慢迭代。2.3 用VS Code编辑MD文件的实操要点写Skill文件最常用的工具就是VS Code因为它对Markdown的支持非常好而且有大量插件可以提升编辑体验。以下是我自己常用的几个配置必备插件Markdown All in One提供快捷键、目录生成、预览等功能。我常用的快捷键是CtrlShiftP然后输入“Markdown: Create Table of Contents”来自动生成目录。markdownlint检查Markdown格式问题比如标题层级跳跃、列表缩进不一致等。写Skill文件时格式规范很重要因为AI解析时对格式比较敏感。Prettier自动格式化Markdown文件保持一致的风格。编辑技巧用CtrlK V打开侧边预览左边写右边看实时检查渲染效果用CtrlShiftV打开全屏预览适合检查整体结构善用代码块折叠功能把长示例折叠起来保持文件可读性在文件开头加一个!-- 最后修改2025-01-15 --这样的注释方便追踪版本注意Skill文件的编码一定要用UTF-8否则中文字符可能乱码。VS Code默认就是UTF-8但如果你从其他地方复制内容过来最好检查一下右下角的编码显示。2.4 一个完整的Skill创建流程我把创建Skill的流程拆成五步每一步都有具体的产出物第一步需求梳理。用文字描述这个Skill要解决的问题、使用场景、预期效果。这一步不需要写代码或Markdown用最自然的方式写下来就行。产出物是一段需求描述。第二步结构设计。确定Skill文件包含哪些章节每个章节大概写什么内容。产出物是一个大纲。第三步内容填充。按照大纲把每个章节的内容写出来。这一步最耗时但也最重要。产出物是Skill文件的初稿。第四步测试验证。把Skill文件放到实际场景中测试看AI是否能正确理解和执行。产出物是测试记录和问题列表。第五步迭代优化。根据测试结果修改Skill文件补充遗漏的细节删除冗余的内容。产出物是Skill文件的稳定版本。这个流程看起来有点重但实际做下来一个中等复杂度的Skill从零到可用大概只需要一两个小时。而且一旦写好后面就是持续受益的过程。3. Skill的修改与迭代让文件越用越好用3.1 什么时候需要修改SkillSkill不是写完就完了它需要随着使用不断迭代。以下几种情况出现时说明你的Skill该更新了AI执行结果不稳定。同一个Skill有时候输出很好有时候输出很差。这通常说明Skill里的指令有歧义AI在不同上下文下理解不一样。解决办法是把模糊的表述改具体比如把“检查代码质量”改成“检查以下五个维度命名、错误处理、边界条件、性能、安全”。使用场景发生变化。比如你原来写的Skill是用于Python项目的现在开始写Go项目了那Skill里的示例和注意事项就需要调整。这种情况我建议不要直接改原文件而是复制一份出来改保留原来的版本以备后用。发现了新的易错点。在使用过程中如果发现AI反复犯同一个错误那就把这个错误和正确的做法写进Skill的注意事项里。这是Skill迭代中最有价值的部分因为它是从实战中来的。工具或模型升级了。比如Claude Code发布了新版本支持了新的Skill语法或能力那你的Skill文件可能也需要相应调整。这种情况不常见但遇到了就要及时跟进。3.2 修改Skill的具体操作方法修改Skill文件本身很简单用VS Code打开直接编辑就行。但有几个操作上的细节值得注意版本管理。我强烈建议用Git来管理Skill文件。每次修改前先commit一次这样如果改坏了可以随时回滚。而且通过git diff可以清楚地看到每次改了什么方便追溯。如果你还不太会用Git至少也要在修改前手动备份一份文件名加上日期后缀。修改记录。在Skill文件末尾加一个修改日志记录每次改了什么、为什么改。比如## 修改日志 - 2025-01-10初版创建 - 2025-01-12增加了对并发安全问题的检查项 - 2025-01-15把输出格式从自由文本改为表格提高可读性这个日志看起来不起眼但过几个月回头看的时候会非常有帮助。A/B测试。如果你不确定某个修改是否有效可以保留两个版本在不同场景下分别使用对比效果。比如把旧版本命名为code-review-v1.md新版本命名为code-review-v2.md用一段时间后再决定保留哪个。3.3 修改Skill时的常见误区误区一越改越长。很多人包括我在修改Skill时倾向于不断添加新内容结果文件越来越长AI解析时反而抓不住重点。我的经验是Skill文件控制在200-500行比较合适超过这个范围就要考虑拆分或者精简。误区二改完不测试。修改完Skill后直接投入使用结果发现新加的内容和原有内容冲突导致AI执行混乱。每次修改后至少要做一次完整的测试确认没有引入新问题。误区三只加不减。有些内容可能已经过时或者不再适用但因为“万一以后用得上”就一直留着。这种心态会导致Skill文件越来越臃肿。定期审查把不再需要的内容删掉保持文件精简。误区四忽略格式。Markdown格式看起来不重要但AI解析时对格式其实很敏感。标题层级混乱、列表缩进不一致、代码块没有标注语言类型这些都会影响AI的理解。用markdownlint这类工具定期检查格式能避免很多莫名其妙的问题。3.4 让Skill更“聪明”的几个技巧用示例代替描述。与其写“输出格式要清晰”不如直接给一个输出示例。AI对示例的理解能力远强于对抽象描述的理解能力。用条件分支处理复杂逻辑。如果Skill需要根据不同的输入走不同的流程用清晰的条件分支来写。比如## 执行步骤 1. 判断输入类型 - 如果是单个文件直接审查该文件 - 如果是目录先列出所有文件再逐个审查 - 如果是代码片段只审查片段内容不检查文件结构 2. 根据类型执行对应的审查流程把长流程拆成子Skill。如果一个任务包含多个独立的子任务可以考虑拆成多个Skill文件然后用一个主Skill来协调。这样每个子Skill可以独立修改和复用灵活性更高。加入“不确定时怎么办”的指令。AI在执行过程中遇到不确定的情况时如果没有明确指令可能会自行发挥。在Skill里加一条“如果遇到不确定的情况先向用户确认不要自行假设”能避免很多意外。4. Skill与Prompt、Agent的关系理清概念才能用好工具4.1 Skill和Prompt的区别与联系Prompt和Skill经常被混为一谈但它们在用法和定位上有明显区别。我用一个类比来说明Prompt像是你临时给同事发的一条消息“帮我把这个表格整理一下”。Skill像是你给同事写的一份操作手册“以后所有表格都按这个规范整理”。从技术层面看Prompt通常是一次性的存在于对话上下文中对话结束就消失了。Skill是持久化的文件存在于项目目录中可以跨会话、跨工具复用。Prompt更灵活适合处理临时性的、探索性的任务。Skill更稳定适合处理重复性的、有固定流程的任务。两者也有联系。Skill在执行时本质上也是通过Prompt来驱动AI的。你可以把Skill理解成一种结构化的、预定义的Prompt集合。写Skill的时候你其实就是在写一系列精心设计的Prompt只不过它们被组织在一个文件里有明确的触发条件和执行流程。实际使用中我通常是两者结合用Skill处理常规任务用Prompt处理Skill覆盖不到的边缘情况。比如我有一个“代码审查”的Skill日常的代码审查都用它。但如果遇到一个特别复杂的架构问题我会临时写一段Prompt来引导AI做更深入的分析。4.2 Skill和Agent的边界在哪里Agent和Skill的关系是另一个容易混淆的点。简单来说Agent是决策者Skill是执行者。Agent负责理解用户意图、规划任务步骤、决定调用哪个Skill。Skill负责在特定任务上提供具体的操作指导。举个例子你让AI帮你“把这个项目的测试覆盖率提升到80%”。Agent会先分析项目结构找出没有测试覆盖的模块然后决定先给哪个模块写测试。写测试这个具体动作就是通过调用“写单元测试”的Skill来完成的。从热搜词里也能看到很多人在搜“skill和agent的区别”。这说明大家在实际使用中确实遇到了概念上的困惑。我的建议是不要过于纠结定义而是从实际需求出发如果你需要AI自主决策和规划那就是Agent的范畴如果你需要AI在特定任务上稳定执行那就是Skill的范畴。两者不是互斥的而是互补的。4.3 不同工具中的Skill体系对比目前主流的AI编程工具都有自己的Skill体系虽然核心概念相似但在具体实现上有差异。以下是我用过的几个工具的对比工具Skill文件位置触发方式特点Claude Code项目根目录的.claude/skills/自动匹配或手动调用支持复杂的条件逻辑社区生态活跃Codex项目根目录的.codex/skills/手动调用为主与代码检索结合紧密适合科研场景Cursor项目根目录的.cursor/skills/自动匹配与编辑器集成度高使用门槛低OpenCode项目根目录的.opencode/skills/手动调用开源方案可定制性强这个对比不是绝对的因为各工具都在快速迭代。但有一个共同趋势Skill正在成为AI编程工具的标准配置就像当年的.gitignore一样逐渐成为项目目录中的标配文件。4.4 从Prompt Engineering到Skill EngineeringPrompt Engineering在过去两年经历了从“随便写写”到“系统化方法”的演变。现在Skill Engineering正在重复这个过程而且起点更高因为大家已经有了Prompt Engineering的经验积累。两者的核心差异在于Prompt Engineering关注的是“怎么问”Skill Engineering关注的是“怎么组织”。写Prompt时你考虑的是措辞、语气、示例。写Skill时你考虑的是结构、流程、触发条件、异常处理。后者更接近软件工程的思维方式。这个转变对从业者的能力要求也更高了。写好一个Prompt可能只需要对语言敏感写好一个Skill则需要理解任务流程、预判边界情况、设计清晰的接口。这也是为什么很多团队开始把Skill文件当作代码一样来管理有review、有测试、有版本控制。5. 实战中踩过的坑与排查技巧5.1 Skill不生效的常见原因原因一文件位置不对。不同工具对Skill文件的存放位置有不同要求。Claude Code要求放在.claude/skills/目录下Codex要求放在.codex/skills/目录下。如果放错了位置工具根本不会读取这个文件。排查方法查看工具的文档确认Skill文件的正确路径。原因二文件格式有问题。Markdown格式错误、编码不对、文件扩展名不是.md这些都会导致Skill无法被正确解析。排查方法用markdownlint检查格式确认文件编码是UTF-8确认扩展名正确。原因三触发条件不明确。如果Skill的触发条件写得太模糊AI可能不知道什么时候该用这个Skill。排查方法在Skill文件里明确写出触发条件比如“当用户提到‘审查代码’、‘检查代码质量’时使用”。原因四内容有歧义。如果Skill里的指令有歧义AI可能会理解成别的意思。排查方法把Skill文件给另一个同事看问他能不能看懂。如果人看不懂AI大概率也看不懂。5.2 Skill执行结果不稳定的排查思路第一步确认是Skill的问题还是模型的问题。同一个Skill在不同时间执行结果不同可能是模型本身的随机性导致的。可以先用一个简单的Prompt测试模型是否稳定如果模型本身就不稳定那问题不在Skill。第二步检查Skill里是否有模糊表述。把Skill文件从头到尾读一遍把所有“可能”、“大概”、“适当”这类模糊词汇找出来替换成具体的、可操作的指令。第三步增加示例。如果某个步骤AI总是执行不好在Skill里加一个具体的示例展示正确的执行方式。示例比描述有效得多。第四步拆分复杂步骤。如果一个步骤包含多个子任务AI可能会漏掉其中一些。把复杂步骤拆成多个简单步骤每个步骤只做一件事。第五步加入检查点。在关键步骤后加入检查点让AI确认自己是否完成了当前步骤再继续下一步。比如“完成审查后确认是否覆盖了所有五个维度如果有遗漏补充审查”。5.3 常见问题速查表问题现象可能原因解决方法Skill完全不生效文件位置错误确认文件放在正确的目录下Skill偶尔生效触发条件模糊明确写出触发条件执行结果与预期不符指令有歧义用具体示例替代抽象描述执行到一半中断步骤太复杂拆分成多个简单步骤输出格式混乱格式要求不明确给出具体的输出示例修改后效果变差新旧内容冲突回滚到上一个版本逐步修改文件太长AI抓不住重点内容过多精简文件控制在500行以内中文乱码编码问题确认文件编码为UTF-85.4 几个实用的避坑技巧技巧一从简单开始。不要一上来就写一个覆盖所有场景的超级Skill。先写一个只处理最常见场景的简单Skill用起来之后再逐步扩展。这样风险可控而且能快速看到效果。技巧二保留工作版本。每次修改前先复制一份当前版本命名为xxx-backup.md。如果修改后效果不好可以快速回滚。这个习惯帮我省了很多时间。技巧三用注释记录思路。在Skill文件里用!-- --加注释记录为什么这么写、当时考虑了哪些因素。这些注释不会影响AI解析但对你以后回顾非常有帮助。技巧四定期清理。每隔一段时间比如一个月审查一次Skill文件把不再适用的内容删掉把新的经验补充进去。保持文件精简和更新。技巧五多工具复用。如果你同时使用多个AI工具可以把Skill文件设计成通用的格式然后在不同工具之间共享。虽然各工具的Skill体系有差异但核心内容是可以复用的。6. 认知总结Skill思维比Skill文件更重要6.1 从“写提示词”到“设计工作流”用了一段时间Skill之后我最大的认知变化是Skill的本质不是提示词而是工作流。写Skill的过程其实是在梳理和设计一个工作流程。你需要考虑输入是什么、输出是什么、中间经过哪些步骤、每一步的验收标准是什么、异常情况怎么处理。这个思维方式一旦建立起来你会发现很多以前觉得“只能靠人做”的事情其实都可以被Skill化。比如写周报、做会议纪要、整理文献、生成PPT大纲这些任务都有相对固定的流程都可以写成Skill。而且这种思维方式是可迁移的。即使你换了一个AI工具或者AI技术本身发生了大的变化工作流设计的思路是不变的。工具会变流程设计的逻辑不会变。6.2 Skill的复利效应Skill有一个很明显的复利效应你花时间写一个好的Skill它会在后续的每一次使用中为你节省时间。一个中等复杂度的Skill写一次可能花一两个小时但如果它每周能帮你节省半小时一个月就回本了之后都是净收益。更重要的是Skill是可以积累和组合的。你写的Skill越多它们之间的协同效应就越强。比如你有一个“代码审查”的Skill和一个“写测试”的Skill把它们组合起来就能实现“审查代码并自动补充测试”的复合能力。这种复利效应在团队协作中更明显。一个团队如果有共享的Skill库新成员加入后可以直接使用这些Skill不需要重新摸索。团队的最佳实践通过Skill文件固化下来不会因为人员流动而丢失。6.3 保持克制的艺术Skill很好用但也要保持克制。不是所有任务都值得写成Skill。我的判断标准是如果一个任务我每周至少做一次而且流程相对固定那就值得写成Skill。如果只是偶尔做一次或者每次流程都不一样那用Prompt就够了。另外Skill也不是越详细越好。有些人在Skill里把每一步都写得极其详细结果AI执行时反而变得死板遇到稍微不同的情况就不知道变通。好的Skill应该是在关键节点给出明确指令在非关键节点给AI留出灵活空间。这个平衡点需要在实际使用中慢慢摸索。我的经验是流程性的内容写详细判断性的内容给原则。比如“先读取文件再分析内容最后输出报告”这是流程写详细。“分析内容时重点关注逻辑错误”这是判断给原则就行。6.4 后续可以怎么扩展如果你已经掌握了Skill的基本用法以下几个方向可以进一步探索方向一Skill的组合与编排。把多个Skill组合成一个工作流让AI按顺序调用。比如“需求分析 → 代码生成 → 代码审查 → 测试生成”这样一条流水线。方向二Skill的自动化触发。配置工具让Skill在特定条件下自动触发不需要手动调用。比如每次保存文件时自动运行代码审查Skill。方向三团队Skill库的建设。把团队的最佳实践整理成Skill库统一管理和分发。这需要一些工程化的思维但收益很大。方向四跨领域的Skill设计。把编程领域的Skill设计思路应用到其他领域比如科研、写作、设计、数据分析等。这些领域的Skill化程度还比较低有很多机会。方向五Skill的评估与优化。建立一套评估体系量化Skill的效果然后基于数据持续优化。这需要一些实验设计的能力但能让Skill的迭代更有方向。我个人在实际操作中的体会是Skill这个东西入门很容易写好很难但一旦写好回报非常大。它不只是一个技术工具更是一种思维方式的体现。你如何理解一个任务、如何拆解一个流程、如何定义好的标准这些都会反映在你写的Skill里。所以与其说是在写Skill不如说是在梳理自己的工作经验把隐性的知识变成显性的资产。这个过程本身就是很有价值的。
