1. 从零理解 Skill 到底是什么很多人第一次听到 Skill 这个词脑子里浮现的是游戏里的技能树或者是某个插件市场里可以一键安装的功能包。但如果你真正动手写过、改过、调试过 Skill就会发现它更像是一份写给 AI 的岗位说明书——你告诉它遇到什么情况该做什么、不该做什么、按什么顺序做、输出成什么格式。我最初接触 Skill 这个概念是因为在 Claude Code 和 Codex 这类工具里频繁看到skill目录和.md文件。当时我以为它就是个普通的提示词模板复制粘贴改改就能用。结果第一次自己写了一个 Skill 丢进去AI 完全不按我预期的流程走该调用的工具没调用该输出的格式乱七八糟。后来花了整整两天时间拆解官方示例、对比不同写法才慢慢摸清楚 Skill 的底层逻辑。简单来说Skill 是一个结构化的指令集合通常以 Markdown 文件的形式存在放在特定目录下由 AI 工具在运行时加载。它和普通的 Prompt 最大的区别在于Prompt 是你临时说的一句话Skill 是预先写好的一套规则。Prompt 更像帮我查一下天气Skill 更像你是一个天气播报员每次播报必须包含温度、湿度、风力三个指标输出格式为表格数据来源优先使用某 API。这个区别听起来简单但实际影响非常大。临时 Prompt 每次都要重新描述需求容易遗漏细节Skill 一旦写好每次调用都自动带上完整上下文稳定性和一致性完全不是一个级别。1.1 Skill 和 Agent 的区别到底在哪热词里有人问skill 和 agent 的区别这个问题我一开始也搞混过。后来我的理解是这样的Agent是一个有自主决策能力的执行体它能自己规划步骤、选择工具、判断什么时候该停下来。你可以把它想象成一个员工。Skill是 Agent 可以调用的能力模块它定义了做某件事的标准流程。你可以把它想象成员工手里的一本操作手册。一个 Agent 可以拥有多个 Skill。比如一个负责代码审查的 Agent可能同时拥有安全检查 Skill性能分析 Skill代码风格检查 Skill。当它遇到不同场景时会根据 Skill 的描述决定调用哪一个。这个架构的好处是职责分离。Agent 负责什么时候做Skill 负责怎么做。你修改 Skill 不会影响 Agent 的决策逻辑你调整 Agent 也不会破坏 Skill 的稳定性。1.2 为什么 Skill 要用 Markdown 文件来写热词里频繁出现MD 文件md 文件编辑器如何利用 VS Code 编辑 md 文件说明很多人对 Markdown 作为 Skill 载体这件事有疑问。为什么不用 JSON、YAML 或者直接写代码我的实际体验是Markdown 在人类可读和机器可解析之间找到了一个很好的平衡点。JSON 和 YAML 结构严谨但写起来啰嗦尤其是当你要写大段自然语言指令时嵌套引号和转义字符能把人逼疯。而 Markdown 天然支持标题层级、列表、代码块、引用块这些结构恰好对应了 Skill 需要的元信息步骤说明示例注意事项等模块。更重要的是AI 模型对 Markdown 格式的理解能力非常强。你用##标记的标题模型能准确识别为章节你用-标记的列表模型能理解为并列项你用 包裹的代码块模型知道那是需要原样保留的内容。这种格式即语义的特性让 Markdown 成为写 Skill 最自然的选择。至于用什么软件编辑VS Code 确实是最顺手的选择。装一个 Markdown Preview Enhanced 插件左边写右边预览还能直接看到标题层级结构。如果你只是偶尔改改Typora 或者 Obsidian 也够用。关键是别用记事本因为你看不到格式很容易把层级写乱。2. 创建一个 Skill 的完整实操流程知道了 Skill 是什么接下来就是动手写。我把自己从零创建一个 Skill 的过程完整拆一遍包括目录结构、文件命名、内容组织、调试方法。这套流程我在 Claude Code 和 Codex 上都验证过基本通用。2.1 目录结构和文件命名的约定不同工具对 Skill 的存放位置要求不一样但通常都有一个固定的根目录。以我常用的环境为例Skill 一般放在项目根目录下的skills/文件夹里每个 Skill 一个子目录子目录名就是 Skill 的标识符。skills/ code-review/ SKILL.md doc-writer/ SKILL.md >--- name: code-review description: 对指定代码文件进行审查输出问题列表和改进建议 --- ## 角色定义 你是一个资深代码审查员专注于发现代码中的潜在问题。 ## 触发条件 当用户要求审查代码、检查代码质量、或者提交了代码变更时触发。 ## 执行步骤 1. 读取目标文件内容 2. 按以下维度逐项检查 3. 汇总问题并按严重程度排序 4. 输出结构化报告 ## 检查维度 - 安全性是否存在注入、越权、敏感信息泄露 - 性能是否有不必要的循环、重复计算、内存泄漏 - 可读性命名是否清晰、注释是否充分 - 兼容性是否使用了已废弃的 API ## 输出格式 | 严重程度 | 文件位置 | 问题描述 | 修复建议 | |---------|---------|---------|---------| | 高/中/低 | 行号 | ... | ... | ## 注意事项 - 不要修改代码只输出审查结果 - 如果文件超过 500 行分段读取 - 遇到不确定的问题标记为待确认不要臆断这个骨架看起来简单但每一部分都有讲究。下面我逐块拆解。2.3 元信息区块name 和 description 怎么写才有效文件顶部的---包裹的区域叫 frontmatter是给工具读取的元信息。其中name和description最关键。name是 Skill 的唯一标识通常要求英文、小写、用连字符分隔。这个名字会出现在工具的技能列表里也可能被 Agent 用来判断是否调用。description是给 Agent 看的广告语。当 Agent 面对一个任务时它会扫描所有可用 Skill 的 description判断哪个最匹配当前需求。所以 description 要写得既准确又有区分度。我踩过的坑是一开始把 description 写得太泛比如帮助处理代码相关任务。结果 Agent 在任何代码场景下都调用这个 Skill包括我只是想让它解释一段代码的时候。后来改成对指定代码文件进行静态审查输出问题列表和改进建议不执行代码修改误触发率立刻降下来了。注意description 里要明确写出做什么和不做什么。边界越清晰Agent 的判断越准确。2.4 角色定义和执行步骤的写法角色定义部分决定了 AI 的人格和专业视角。同样一段代码你让它以安全专家的身份看和以性能优化专家的身份看关注点完全不同。我的经验是角色定义要具体到领域 经验层级 关注重点。比如差的写法你是一个程序员好的写法你是一个有十年经验的后端工程师专注于高并发场景下的代码质量和稳定性执行步骤部分要写成有序列表每一步都是一个明确的动作。这里最容易犯的错误是步骤太抽象比如分析代码——分析什么怎么分析分析完输出什么AI 拿到这种指令只能靠猜。正确的做法是把大步骤拆成可执行的小动作读取目标文件如果文件不存在则报错并终止按函数为单位切分代码对每个函数检查是否包含硬编码的敏感信息对每个函数检查是否存在未处理的异常分支将发现的问题按文件位置排序输出 Markdown 表格2.5 输出格式和注意事项的约束力输出格式部分决定了 Skill 产出的稳定性。如果你不指定格式AI 每次输出的结构可能都不一样后续如果要程序化处理就很麻烦。用表格、JSON、固定标题层级都可以关键是要给出明确的模板。比如你要输出 JSON就直接把 JSON 结构写出来{ file: 文件路径, issues: [ { severity: high, line: 42, message: 问题描述, suggestion: 修复建议 } ], summary: 总体评价 }注意事项部分是负面约束告诉 AI 什么不能做。这部分往往比正面指令更重要因为 AI 天生倾向于多做你不限制它就会自由发挥。我常用的负面约束包括不要修改原始文件不要执行任何写操作不要臆断未明确的信息如果信息不足输出需要补充xxx而不是猜测单次输出不超过 2000 字超出时分批输出3. 修改和调试 Skill 的实战经验写完第一个版本只是开始真正花时间的是调试和迭代。我统计过自己写一个能稳定工作的 Skill平均要改 5 到 8 版。下面是我总结的调试方法论。3.1 怎么判断 Skill 有没有生效最直接的验证方法是触发一次调用看 AI 的输出是否符合 Skill 里定义的格式和步骤。但这里有个陷阱AI 可能碰巧输出了类似的格式让你误以为 Skill 生效了实际上它只是根据你的临时 Prompt 在发挥。更可靠的验证方法是故意在 Skill 里加一个特征标记。比如在输出格式里要求报告末尾必须包含一行---END OF REVIEW---。如果 AI 输出了这行说明 Skill 确实被加载了如果没有说明 Skill 没生效或者被其他指令覆盖了。如果确认 Skill 没生效按以下顺序排查检查文件路径和文件名是否正确检查 frontmatter 格式是否合法---必须独占一行检查工具是否需要重启或重新加载检查是否有其他 Skill 的 description 产生了冲突查看工具的日志输出通常会有加载失败的提示3.2 常见失效原因和修复对照表现象可能原因修复方法Skill 完全不触发description 太泛或太窄调整 description增加具体场景词触发了但不按步骤走步骤描述太抽象把每步拆成具体动作加序号输出格式不稳定没有给出明确模板直接写出期望的输出结构和其他 Skill 冲突两个 Skill 的触发条件重叠收窄各自的 description 边界加载报错frontmatter 格式错误检查---是否成对出现中文乱码文件编码不是 UTF-8用 VS Code 另存为 UTF-83.3 迭代优化的三个方向当 Skill 基本能跑通之后我会从三个方向继续优化第一收窄触发边界。初期我总希望一个 Skill 能覆盖尽可能多的场景结果就是什么都能触发什么都不精。后来我把一个大的代码处理 Skill拆成了代码审查代码解释代码重构三个独立 Skill每个的 description 都写得很具体触发准确率大幅提升。第二增加边界情况的处理。比如文件为空怎么办、文件太大怎么办、编码不是 UTF-8 怎么办、用户输入的是目录而不是文件怎么办。这些边界情况在正常使用时不会遇到但一旦遇到就会让 Skill 直接崩溃。第三优化输出的人类可读性。早期我追求输出的结构化全部用 JSON。后来发现人看起来太累改成先给一个 Markdown 表格摘要再附上 JSON 详情。这样既能快速浏览又能程序化处理。3.4 用 VS Code 高效编辑和预览 Skill热词里有人问如何利用 VS Code 编辑 md 文件我分享一下自己的配置。必装插件是Markdown All in One和Markdown Preview Enhanced。前者提供快捷键和自动格式化后者提供实时预览。我常用的快捷键Ctrl Shift V打开预览窗口Ctrl B加粗选中文本Ctrl Shift ]提升标题层级Ctrl Shift [降低标题层级预览窗口建议放在右侧这样左边写右边看标题层级和表格渲染效果一目了然。特别是写 Skill 的时候你需要频繁检查 frontmatter 格式和代码块是否正确闭合有预览会省很多事。另外建议开启显示空白字符功能View 菜单里找 Render Whitespace这样能看出缩进用的是空格还是 Tab避免混用导致的格式问题。4. 不同场景下的 Skill 设计思路Skill 不是千篇一律的不同用途的 Skill 在设计思路上差别很大。我按自己写过的几类 Skill分别讲讲设计要点。4.1 文档写作类 Skill 的结构设计文档写作类 Skill 的核心是风格一致性。你希望 AI 每次写出来的东西都符合同一套规范包括语气、用词、段落长度、标题格式。我的做法是在 Skill 里内置一个风格检查清单让 AI 在输出前先自查是否避免了通过...可以...这类被动句式段落是否控制在 4 到 6 行是否使用了具体的数字和案例而不是空泛的描述标题层级是否连续没有跳级是否避免了总之综上所述这类总结词这个清单本身就是 Skill 的一部分AI 在生成内容后会逐项对照。实测下来加了自查环节之后输出质量的稳定性提升非常明显。4.2 数据分析类 Skill 的参数化技巧数据分析类 Skill 通常需要接收参数比如分析哪个文件按什么维度分组输出什么格式。这些参数不能写死在 Skill 里要让 AI 从用户的输入中提取。我的做法是在 Skill 里定义一个参数区明确列出需要哪些参数、每个参数的格式、缺省值是什么## 输入参数 - 目标文件必填CSV 或 Excel 路径 - 分组维度选填默认为日期 - 聚合方式选填默认为求和可选平均计数最大最小 - 输出格式选填默认为Markdown 表格可选JSONCSV然后在执行步骤里写如果用户未提供某参数使用默认值并在输出开头注明使用了默认值。这样既保证了灵活性又避免了 AI 反复追问。4.3 检索类 Skill 的触发条件设置检索类 Skill 的难点在于什么时候该触发。如果触发条件太宽AI 会在任何需要查资料的场景下调用它包括它自己就能回答的问题如果太窄又会在真正需要的时候不触发。我的经验是把触发条件写成用户明确要求查找外部信息或者问题涉及实时数据、最新版本、具体事实核查。同时加一条负面约束如果问题属于通用知识或逻辑推理不要触发本 Skill。另外检索类 Skill 通常需要调用外部工具或 API这部分要在 Skill 里明确写出调用方式和参数格式。如果工具调用失败要有降级方案比如如果 API 无响应提示用户稍后重试不要编造数据。4.4 多 Skill 协作时的优先级和冲突处理当一个 Agent 拥有多个 Skill 时冲突是难免的。比如代码审查 Skill和代码重构 Skill都可能在用户提交代码时触发。处理冲突的方法有两种方法一在 description 里明确互斥条件。比如代码审查 Skill 写仅输出问题不修改代码代码重构 Skill 写在用户明确要求修改代码时触发。这样 Agent 能根据用户意图区分。方法二设置优先级字段。有些工具支持在 frontmatter 里写priority数值高的优先。但这个方法依赖工具支持不是所有环境都通用。我的实际做法是方法一为主方法二为辅。先把 description 的边界写清楚如果还有冲突再加优先级。5. 那些文档里不会写的踩坑记录这部分是我自己踩过的坑官方文档里基本不会提但实际使用中很容易遇到。5.1 Skill 文件编码问题导致的加载失败有一次我写了一个 Skill本地测试一切正常但换了一台机器就死活加载不了。排查了半天才发现那台机器上的编辑器默认保存成了 GBK 编码而工具只认 UTF-8。这个问题的隐蔽之处在于文件内容看起来完全正常用编辑器打开也没乱码但工具读取时就是解析失败。后来我养成了一个习惯每次新建 Skill 文件后先用 VS Code 右下角的编码指示器确认是 UTF-8如果不是就点一下改成 UTF-8 再保存。提示如果你在 Windows 上写 Skill特别注意编码问题。Windows 默认编码和 Unix 系不一样跨平台协作时最容易出问题。5.2 描述太泛导致 Skill 被频繁误触发前面提过 description 太泛的问题这里展开讲讲具体表现。我曾经写了一个文本处理 Skilldescription 写的是帮助处理各种文本相关任务。结果 AI 在以下场景全部触发了这个 Skill用户让它写一段文案用户让它翻译一句话用户让它总结一篇文章用户让它改一个错别字这些场景确实都和文本处理沾边但我的 Skill 实际只擅长格式化、去重、批量替换这类操作。误触发的结果就是 AI 用错误的流程处理任务输出质量反而比不用 Skill 还差。修复方法就是把 description 改成对文本进行格式化、去重、批量替换操作不涉及内容创作、翻译、总结。加上负面描述之后误触发率从大概 70% 降到了 10% 以下。5.3 步骤顺序写错引发的连锁错误Skill 里的执行步骤是有顺序的顺序写错会导致连锁错误。我写过一个数据清洗 Skill步骤原本是删除空行去除重复行统一日期格式填充缺失值看起来没问题但实际跑的时候发现第 3 步统一日期格式后原本不重复的行变成了重复行因为日期格式不同导致之前没被识别为重复。正确的顺序应该是先统一格式再去重。这个坑的教训是涉及数据转换的步骤要先做归一化再做去重和过滤。顺序错了结果就错了而且很难排查因为每一步单独看都是对的。5.4 输出格式约束不够严格导致结果不可用早期我写 Skill 时输出格式部分只写以表格形式输出。结果 AI 有时候输出 Markdown 表格有时候输出 HTML 表格有时候输出纯文本对齐的表格。虽然都是表格但后续程序化处理时全部报错。后来我改成直接给出模板| 列名1 | 列名2 | 列名3 | |-------|-------|-------| | 值1 | 值2 | 值3 |并且加一句严格按上述模板输出不要添加额外的列或修改列名。这样输出就完全稳定了。5.5 中文标点和英文标点混用引发的解析问题这个问题在写包含代码示例的 Skill 时特别容易遇到。比如你在 Skill 里写输出格式为{key: value}如果引号用了中文引号AI 可能会把中文引号也当成输出内容的一部分。我的做法是所有涉及代码、JSON、命令行的部分一律用英文标点所有自然语言说明部分用中文标点。并且在 Skill 开头加一句代码块内的标点必须使用英文半角。6. 让 Skill 越用越顺手的维护策略Skill 写完之后不是一劳永逸的随着使用场景变化需要持续维护。我总结了几条维护策略。6.1 建立 Skill 版本管理习惯我见过很多人改 Skill 是直接覆盖原文件改坏了想回退都回不去。我的做法是用 Git 管理 Skill 目录每次修改前先提交一版改完测试通过再提交一版。这样任何时候都能回退到上一个可用版本。如果不用 Git至少也要手动备份。我的习惯是在 Skill 目录下建一个_history文件夹每次大改前把当前版本复制一份进去文件名加上日期后缀。6.2 定期清理失效和冗余的 SkillSkill 用久了会积累很多有些是早期写的已经不用了有些是功能被新 Skill 覆盖了。这些冗余 Skill 会增加 Agent 的决策负担也可能造成误触发。我大概每个月会清理一次把最近一个月没触发过的 Skill 标记出来确认不需要就删掉或者归档。归档的意思是移到一个_archive目录不参与加载但保留文件以备将来参考。6.3 从实际使用中收集改进点最好的改进灵感来自实际使用。我有个习惯是每次 Skill 输出不符合预期时随手记一笔什么场景、期望什么、实际什么。攒够几条之后集中改一版。这个习惯的好处是改进有据可依不是凭感觉改。而且记录本身也能帮你发现规律比如某个类型的错误反复出现说明 Skill 里对应的约束写得不够清楚。6.4 和其他人共享 Skill 时的注意事项如果你要把 Skill 分享给别人用有几件事必须做写清楚依赖项这个 Skill 需要哪些工具、哪些环境、哪些前置条件给出最小可用示例让别人能快速验证 Skill 是否正常工作标注适用版本不同工具版本对 Skill 的支持可能有差异说明已知限制哪些场景下这个 Skill 不适用避免别人踩你踩过的坑我自己分享 Skill 时会在 SKILL.md 末尾加一个兼容性说明章节写清楚测试过的工具版本和已知问题。这样别人用的时候心里有数不会一出问题就来找你。6.5 关于 Skill 编写的一点个人体会写了这么多 Skill我最大的体会是好的 Skill 不是写出来的是改出来的。第一版能跑通就不错了真正让它稳定可靠的是后面一轮又一轮的调试和收窄。另一个体会是Skill 的价值不在于多而在于精。与其写十个半吊子 Skill不如把一个 Skill 打磨到能在 90% 的场景下稳定工作。我现在常用的 Skill 也就五六个但每一个都是经过几十次迭代的触发准确率和输出稳定性都很高。最后一个建议写 Skill 的时候把自己想象成在给一个新人写操作手册。这个新人很聪明但完全不了解你的业务你需要把每个步骤、每个判断条件、每个边界情况都写清楚。如果你写的东西自己隔一周再看都能看懂并复现那这个 Skill 就合格了。