1. 从零理解 Skill它到底是什么为什么值得折腾第一次接触 Skill 这个概念很多人会把它和 Prompt 混为一谈。我一开始也是这么想的——不就是一段写给模型的指令吗能有多大区别直到我在一个实际项目里把同一套任务分别用纯 Prompt 和 Skill 各实现了一遍才发现两者在工程层面的差距远比想象中大。Skill 本质上是一种结构化的能力封装单元。它不只是一段提示词而是一个包含元信息、触发条件、执行逻辑、依赖资源和输出规范的完整模块。你可以把它理解成给 AI 助手写的一份“岗位说明书”——告诉它在什么场景下该做什么、怎么做、做到什么程度算合格。而 Prompt 更像是你临时口头交代的一句话灵活但不可复用换个场景就得重新说一遍。这个区别在实际使用中非常关键。举个例子如果你只是偶尔让模型帮你润色一段文字写个 Prompt 就够了。但如果你需要模型每天帮你处理一批格式固定的周报、按照统一标准做代码审查、或者用同一套逻辑分析不同来源的数据那你就需要一个 Skill——因为你需要的是一致性和可复用性而不是每次靠运气去调教一段提示词。从热词里也能看出这个趋势。“agent skill”“claude code skill”“codex skill”“skill和agent的区别”这些搜索词频繁出现说明越来越多的人开始意识到光会写 Prompt 已经不够了真正让 AI 稳定干活的是 Skill 这套机制。Agent 负责决策和调度Skill 负责执行和落地两者配合才能完成复杂任务。那 Skill 适合谁来学我的判断是三类人一是已经在用 AI 辅助日常工作、但觉得每次都要重新写提示词太累的人二是想把 AI 能力集成到自己产品里的开发者三是需要团队协作、希望统一 AI 输出标准的管理者。如果你属于这三类中的任何一类花时间搞懂 Skill 的创建和修改回报率会非常高。接下来我会从设计思路、文件结构、实操创建、修改迭代、常见问题几个维度把我自己踩过的坑和总结出来的方法完整地分享一遍。文章会比较长但每一段都是实际用过的东西不是纸上谈兵。2. Skill 的整体设计思路与核心结构拆解2.1 为什么 Skill 要用 MD 文件来承载热词里“MD文件”“md文件编辑器”“如何利用vx code编辑md文件”“md文件用什么软件打开”这些搜索量很高说明很多人对 MD 文件这个载体有疑问。为什么不用 JSON、YAML 或者直接写代码我的理解是这样的Skill 的核心受众是人和模型双方。人需要能读懂、能修改、能快速定位问题模型需要能解析、能理解语义、能按结构执行。JSON 和 YAML 对机器友好但人读起来费劲尤其是当 Skill 逻辑比较复杂的时候嵌套几层就看晕了。而 Markdown 刚好在两者之间找到了平衡——它有清晰的结构标记标题、列表、代码块人一眼就能看懂层次关系模型也能通过标题层级和标记符号准确提取信息。另外Markdown 天然支持自然语言描述。Skill 里有很多内容是“解释性”的比如什么情况下触发、遇到异常怎么处理、输出格式有什么要求这些用自然语言写最合适。你硬要用 JSON 的字符串字段来装这些内容写起来痛苦读起来更痛苦。提示如果你还没选好 MD 编辑器VS Code 是目前最稳妥的选择。装一个 Markdown All in One 插件预览、目录、快捷键都齐了。Typora 写作体验更好但不适合看代码块多的文件Obsidian 适合做知识管理但用来编辑 Skill 有点重。2.2 Skill 文件的典型结构长什么样一个完整的 Skill 文件通常包含以下几个部分我用一个实际例子来说明--- name: weekly-report-generator version: 1.2.0 trigger: 当用户提到周报weekly report或提供了一组工作记录时 dependencies: - 需要访问用户提供的数据文件 - 需要知道当前日期 --- # 周报生成 Skill ## 角色定义 你是一个专业的周报撰写助手擅长将零散的工作记录整理成结构清晰、重点突出的周报。 ## 执行流程 1. 读取用户提供的工作记录 2. 按项目维度归类 3. 识别本周关键产出和阻塞项 4. 按照指定模板输出 ## 输出格式 - 本周完成事项按项目分组 - 下周计划 - 风险与阻塞 ## 异常处理 - 如果工作记录为空提示用户补充 - 如果日期不明确默认使用当前周这个结构里---包裹的部分是元信息frontmatter告诉系统这个 Skill 叫什么、什么时候触发、依赖什么。下面的正文部分才是真正的执行逻辑。这种分层设计的好处是系统可以快速扫描元信息来决定是否加载某个 Skill而不需要每次都把全文读一遍。2.3 Skill 和 Prompt 的本质区别在哪里很多人问“skill和agent的区别”“skill和prompt的区别”我用一个类比来解释Prompt像是你给出租车司机说“去机场”每次都要说说错了就得重新说。Skill像是你设定好的导航路线只要输入目的地它就按固定路线走中间怎么拐弯、哪里上高速都是预设好的。Agent像是整个调度系统它决定什么时候叫车、叫哪种车、走哪条路线。从工程角度看Skill 比 Prompt 多了几个关键能力版本管理可以迭代更新、触发条件不需要每次手动调用、依赖声明知道需要什么资源、错误处理遇到异常有预设方案。这些能力让 Skill 从“一次性指令”变成了“可维护的资产”。2.4 设计 Skill 时最容易犯的三个错误我在创建和修改 Skill 的过程中踩过不少坑总结下来最常见的问题有三个第一个是把 Skill 写成了 Prompt 的加长版。就是把一段很长的提示词直接塞进 MD 文件里加了个标题就完事了。这种 Skill 没有结构模型执行起来还是靠猜稳定性很差。正确的做法是把执行流程拆成明确的步骤每一步都有清晰的输入和输出。第二个是触发条件写得太模糊。比如写“当用户需要帮助时触发”这等于没写。好的触发条件应该是具体可判定的比如“当用户输入包含‘生成周报’或提供了包含日期和工作项的结构化数据时”。第三个是忽略了异常处理。很多 Skill 只写了正常流程一旦用户输入不符合预期模型就不知道该怎么办了。我现在的习惯是每写一个 Skill至少花三分之一的时间在想“如果这里出错了怎么办”。3. 手把手创建你的第一个 Skill3.1 环境准备与工具选型创建 Skill 不需要什么特殊的开发环境一个文本编辑器加一个能运行 Skill 的平台就够了。但工具选对了能省很多事。编辑器方面VS Code 是我的首选。原因很简单它原生支持 Markdown 预览装个插件就能实时看到渲染效果同时它还能管理文件夹方便你把多个 Skill 组织在一个项目里。如果你用不惯 VS CodeObsidian 也可以但记得关掉那些花哨的主题用最朴素的编辑模式避免格式干扰。平台方面不同工具对 Skill 的支持方式不一样。Claude 的 Skill 机制、Codex 的 Skill 系统、还有各种 Agent 框架里的 Skill 插件格式上大同小异但细节有差异。我的建议是先在文档里确认你用的平台支持什么格式的 frontmatter 字段别写完才发现字段名不对。注意有些平台对 Skill 文件的命名有要求比如必须用英文、必须用连字符、不能有空格。创建之前先看一眼文档省得后面改名字改到崩溃。3.2 从需求到 Skill一个完整的拆解过程假设我要创建一个“代码审查 Skill”用来让 AI 按照团队规范审查代码。我不会一上来就写 MD 文件而是先做需求拆解第一步明确输入和输出。输入是什么是一段代码、一个文件、还是一个代码仓库的 diff输出是什么是审查意见列表、是修改建议、还是一个通过/不通过的结论第二步梳理执行步骤。代码审查通常包括检查命名规范、检查代码风格、检查潜在 bug、检查性能问题、检查安全问题。每一步都需要明确的检查标准。第三步确定优先级和边界。哪些问题是必须指出的哪些是建议性的遇到不确定的情况怎么处理审查范围有没有限制第四步设计输出格式。审查意见用什么结构呈现是按文件分组还是按严重程度分组每条意见包含哪些字段这四步做完Skill 的骨架就出来了。接下来才是把它写成 Markdown。3.3 编写 Skill 文件的实操步骤我现在写 Skill 有一个固定的流程分享出来供参考先写 frontmatter。把 name、version、trigger、dependencies 这几个字段先填上。trigger 我会写得尽量具体通常包含三要素用户可能说的关键词、用户可能提供的输入类型、以及排除条件什么情况下不触发。再写角色定义。用两三句话描述这个 Skill 扮演什么角色、擅长什么、不做什么。这部分看起来简单但很重要——它决定了模型在执行时的“心态”。然后写执行流程。这是核心部分。我会用有序列表把每一步写清楚每一步都包含做什么、怎么做、输出什么。如果某一步逻辑复杂我会拆成子步骤。接着写输出格式。用代码块或表格把期望的输出结构展示出来。模型看到具体示例后输出会稳定很多。最后写异常处理。把能想到的异常情况都列出来每种情况给出处理方案。这部分我通常会写得很细因为实际使用中出问题的往往就是这些边角情况。写完后自己读一遍。假装你是第一次看到这个 Skill 的人能不能看懂有没有歧义有没有遗漏我经常在读的过程中发现逻辑漏洞。3.4 一个可直接复用的 Skill 模板下面这个模板是我用了很多次之后沉淀下来的你可以直接拿去改--- name: [skill-name] version: 1.0.0 trigger: [具体触发条件] dependencies: - [依赖1] - [依赖2] --- # [Skill 名称] ## 角色定义 [两三句话描述角色和职责边界] ## 输入要求 - [输入类型1及格式要求] - [输入类型2及格式要求] ## 执行流程 1. [步骤一做什么怎么做] 2. [步骤二做什么怎么做] 3. [步骤三做什么怎么做] ## 输出格式 [用代码块或表格展示期望输出] ## 异常处理 | 异常情况 | 处理方式 | |---------|---------| | [情况1] | [处理方案] | | [情况2] | [处理方案] | ## 注意事项 - [需要特别注意的点]这个模板的好处是结构清晰填空就行。但别把它当教条根据实际需求调整结构是完全没问题的。4. 修改与迭代 Skill 的实战方法4.1 什么时候该修改 Skill 而不是重写Skill 用了一段时间后总会遇到需要调整的情况。我的判断标准是如果问题出在执行细节上比如某一步的输出格式不对、某个异常情况没覆盖到那就修改如果问题出在整体逻辑上比如触发条件完全不对、执行流程需要大改那就重写。修改的时候有个技巧只改需要改的部分不要顺手优化其他内容。我吃过这个亏——本来只想改一个输出格式结果看着看着觉得触发条件也可以优化执行流程也可以调整最后改了一大堆新版本反而出了更多问题。后来我给自己定了个规矩每次修改只解决一个明确的问题改完测试通过再考虑下一个。4.2 版本管理让每次修改都可追溯Skill 文件里的 version 字段不是摆设。我的习惯是主版本号1.x.x → 2.x.x整体逻辑重构触发条件或执行流程发生重大变化次版本号x.1.x → x.2.x新增功能或异常处理不影响现有行为修订号x.x.1 → x.x.2修复 bug、调整措辞、优化格式每次修改版本号我会在文件末尾加一个简短的 changelog## Changelog - v1.2.0: 新增对空输入的处理优化输出格式 - v1.1.0: 调整触发条件增加关键词匹配 - v1.0.0: 初始版本这样回头查的时候一目了然也方便团队协作时其他人了解改动历史。4.3 用测试用例验证 Skill 的稳定性修改完 Skill 后怎么知道改对了我的方法是准备一组测试用例每次修改后都跑一遍。测试用例包括正常输入符合预期的标准输入、边界输入刚好满足触发条件的最小输入、异常输入不符合预期的输入、空输入什么都不给。每种情况都记录期望输出和实际输出对比看是否一致。这个方法看起来笨但特别有效。我有好几次以为改好了一跑测试发现边界情况挂了。如果没有测试用例这个问题可能要到实际使用中才暴露出来。4.4 修改 Skill 时的常见陷阱陷阱一改完忘了更新版本号。这会导致你分不清哪个版本是新的团队协作时更麻烦。陷阱二在 Skill 里硬编码太多具体信息。比如把某个项目的特定路径写死在 Skill 里换个项目就不能用了。好的 Skill 应该是参数化的具体信息通过输入传入。陷阱三忽略向后兼容。如果你修改了输出格式但下游有程序依赖旧格式就会出问题。修改前先确认有没有依赖方有的话要么保持兼容要么同步更新依赖方。陷阱四改完不测试直接上线。这个不用多说了血的教训。5. 常见问题与排查技巧实录5.1 Skill 不触发怎么办这是最常见的问题。排查思路按顺序来先检查触发条件。你输入的文本里有没有包含触发关键词触发条件是不是写得太严格了我遇到过好几次触发条件里写的是“生成周报”但用户输入的是“帮我写个周报”多了个字就不匹配了。后来我把触发条件改成更灵活的描述问题就解决了。再检查 Skill 是否被正确加载。有些平台需要手动启用 Skill或者需要把文件放在特定目录下。确认一下文件位置和加载状态。最后检查优先级。如果你有多个 Skill可能存在冲突。比如两个 Skill 的触发条件有重叠系统选了另一个。这时候需要调整触发条件的特异性让匹配更精确。5.2 输出格式不稳定的排查方法模型有时候不按你指定的格式输出原因通常有三个格式描述不够具体。如果你只写“输出一个列表”模型可能用无序列表也可能用有序列表还可能用表格。正确的做法是给出具体示例用代码块把期望的输出结构完整展示出来。执行流程里有歧义。如果某一步的描述模棱两可模型就会自由发挥。检查每一步的指令是否明确有没有“可以”“建议”这类模糊词汇。异常处理没覆盖。当输入不符合预期时模型不知道该怎么办就会按自己的理解来。把异常情况补全给出明确的处理指令。5.3 Skill 执行到一半卡住的处理这种情况通常是因为某一步的依赖没有满足。比如 Skill 需要读取一个文件但文件不存在或者需要调用一个接口但接口超时了。我的处理方式是在 Skill 的异常处理部分为每个可能失败的步骤预设 fallback 方案。比如文件读取失败时提示用户重新提供接口超时时重试一次或返回部分结果。另外有些平台对 Skill 的执行时间有限制太复杂的 Skill 可能会超时。如果遇到这种情况考虑把 Skill 拆成多个小 Skill分步执行。5.4 常见问题速查表问题现象可能原因排查步骤解决方案Skill 不触发触发条件不匹配检查输入是否包含关键词放宽触发条件或增加同义词输出格式混乱格式描述不具体检查输出格式部分增加具体示例执行中断依赖缺失或超时检查依赖项和耗时补充 fallback 或拆分 Skill结果不一致执行流程有歧义检查每步指令消除模糊词汇明确步骤版本混乱未更新版本号检查 version 字段建立版本管理规范5.5 几个让我少走弯路的实操心得心得一Skill 不是越长越好。我一开始觉得写得越详细越好结果一个 Skill 写了三千多字模型执行起来反而容易迷失。后来我把 Skill 控制在 500-1500 字之间重点突出效果反而更好。心得二用注释标记待优化项。写 Skill 的时候经常会有“这里以后要改”的想法我会用!-- TODO: xxx --标记出来下次修改时直接搜索 TODO 就能找到。心得三保留旧版本。每次大改之前我会把旧版本另存一份。有几次改完发现新版本还不如旧版本直接回滚就行了。心得四让 Skill 自己解释自己。我会在 Skill 末尾加一段“设计说明”解释为什么这么设计、有哪些取舍。过几个月回头看的时候这段说明能帮我快速回忆起当时的思路。心得五别在 Skill 里写敏感信息。路径、密钥、账号这些不要直接写在 Skill 文件里通过环境变量或输入参数传入。一方面是安全考虑另一方面是方便在不同环境间迁移。5.6 关于 Prompt 和 Skill 配合使用的经验虽然 Skill 比 Prompt 更工程化但两者不是替代关系而是配合关系。我的做法是Skill 负责框架和流程Prompt 负责具体执行时的微调。比如一个“数据分析 Skill”定义了整体的分析流程和输出格式但在实际执行时我会根据具体的数据特点临时加一段 Prompt 来引导模型关注某些特定维度。这样既有 Skill 的稳定性又有 Prompt 的灵活性。另外热词里提到的“prompt engineering”“prompt提示词”“分析项目结构好用的prompt”这些本质上都是在解决“怎么让模型更好地理解意图”的问题。Skill 把这个问题的解决方案固化了但 Prompt 工程的方法论依然适用——写 Skill 的时候你其实就是在做 Prompt 工程只不过是在一个更结构化的框架里做。6. 从 Skill 到 Agent能力边界的延伸6.1 Skill 和 Agent 的协作模式热词里“agent skill”“skill和agent的区别”搜索量很高说明很多人对两者的关系有困惑。我用一个实际场景来解释假设你要做一个“自动处理客户反馈”的系统。Agent 负责接收反馈、判断类型、决定调用哪个 SkillSkill 负责具体执行比如“分类 Skill”负责判断反馈属于哪一类“回复 Skill”负责生成回复内容“升级 Skill”负责判断是否需要转人工。Agent 是决策者Skill 是执行者。Agent 可以根据情况灵活选择调用哪个 Skill、按什么顺序调用Skill 则专注于把自己的那件事做好。这种分工让系统既灵活又稳定。6.2 多个 Skill 如何组织和管理当你有了十几个甚至几十个 Skill 之后管理就成了问题。我的做法是按功能域分目录skills/ ├── data/ │ ├──>