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有Skill，Codex有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：提供快捷键、目录生成、预览等功能。我常用的快捷键是
Ctrl+Shift+P然后输入“Markdown: Create Table of Contents”来自动生成目录。 - markdownlint：检查Markdown格式问题，比如标题层级跳跃、列表缩进不一致等。写Skill文件时格式规范很重要，因为AI解析时对格式比较敏感。
- Prettier：自动格式化Markdown文件，保持一致的风格。
编辑技巧：
- 用
Ctrl+K V打开侧边预览，左边写右边看，实时检查渲染效果 - 用
Ctrl+Shift+V打开全屏预览，适合检查整体结构 - 善用代码块折叠功能，把长示例折叠起来，保持文件可读性
- 在文件开头加一个
<!-- 最后修改：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 什么时候需要修改Skill
Skill不是写完就完了，它需要随着使用不断迭代。以下几种情况出现时，说明你的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 Engineering
Prompt 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-8 |
5.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，不如说是在梳理自己的工作经验，把隐性的知识变成显性的资产。这个过程本身，就是很有价值的。
