1. 从skills这个热词说起它到底在解决什么问题最近一段时间skills这个词在开发者圈子里出现的频率明显高了起来。如果你在技术社区里逛一圈会看到各种组合词Agent Skills、Claude Agent Skills、Codex Skills、前端开发 Skills、Skills 开发、Skills 推荐……乍一看像是又一个被炒起来的概念但真正上手用过之后会发现它背后对应的其实是一个非常朴素的需求让 AI 助手从什么都能聊两句变成在特定任务上真的能干活。我自己最早接触这个概念是在折腾一个自动化任务的时候。当时想让 AI 帮我处理一批结构化的数据文件结果发现它每次输出的格式都不太一样有时候多一个字段有时候少一个步骤来回纠正的成本比我自己手动做还高。后来才意识到问题不在于模型不够聪明而在于我没有给它一套明确的、可复用的操作规范。Skills 要解决的正是这个问题。简单来说一个 skill 就是一份写给 AI 看的操作手册。它通常包含几个部分这个技能是干什么的、什么时候该用它、具体分几步做、每一步的输入输出是什么、遇到边界情况怎么处理。你可以把它理解成给一个新同事写的 SOP 文档——只不过这个新同事是 AI它理解能力很强但记性有限所以你需要把关键信息显式地写出来。这套思路的价值在于三个层面。第一是一致性同一个任务不管你今天问还是明天问得到的结果结构是稳定的。第二是可组合一个复杂流程可以拆成若干个 skill每个 skill 负责一段像搭积木一样拼起来。第三是可沉淀团队里某个人摸索出来的好方法写成 skill 之后其他人直接调用就行不用重复踩坑。适合读这篇内容的人大概有三类一是刚听说 skills 这个概念、想知道它跟自己有没有关系的开发者二是已经在用 AI 辅助工作、但觉得输出不够稳定想找改进方法的人三是想把自己或团队的流程标准化、沉淀成可复用资产的工程师。不管你用的是什么平台或工具底层的思路是相通的我会尽量把平台无关的部分讲透具体的安装和调用细节放在后面章节。2. Skills 的核心结构一份好的操作手册长什么样2.1 元信息层让 AI 知道什么时候该用我任何一份 skill 文档开头都得有一段自我介绍。这部分的作用不是给人看的而是给 AI 做路由判断用的。当用户提出一个需求时AI 需要快速判断我手头这么多 skill哪一个最匹配如果元信息写得含糊AI 就可能选错技能或者干脆不用技能直接瞎答。元信息通常包含这几个字段名称、一句话描述、适用场景、不适用场景。我见过很多人写 skill 时只写名称和描述结果 AI 经常在错误的场景下调用它。加上不适用场景这一条之后误调用率会明显下降。举个例子如果你写了一个生成周报的 skill那不适用场景里就应该明确写上不用于生成项目技术文档不用于处理实时数据这样 AI 在遇到技术文档需求时就不会误用它。这里有个经验描述要写做什么而不是是什么。比如数据处理技能这种描述就太虚了AI 看了不知道能干嘛。改成把 CSV 文件按指定列去重并输出统计摘要匹配精度会高很多。这个道理跟给函数起名一样——processData不如deduplicateCSVByColumn来得清楚。2.2 流程层把怎么做拆成可执行的步骤流程层是 skill 的主体也是最考验功力的地方。我的建议是步骤要拆到每一步都能独立验证的粒度。什么意思呢就是每一步做完之后你都能判断它对不对而不是等到最后一步才发现前面全错了。举个具体的例子。假设你要写一个从网页提取结构化数据的 skill如果只写打开网页、提取数据、保存结果三步那 AI 执行起来会非常随意。但如果你拆成确认目标网页可访问返回状态码定位数据所在的容器元素输出选择器按字段逐个提取每个字段输出前 3 条样本供确认校验字段完整性缺失字段标记出来按指定格式写入文件输出文件路径和行数这样每一步都有明确的产出物出错时能立刻定位到是哪一步的问题。这个思路其实来自软件工程里的可测试性原则——不可测试的步骤等于不可控的步骤。另外步骤之间要写清楚数据怎么传递。上一步的输出怎么变成下一步的输入这个衔接点最容易出问题。我一般会在每一步里明确写输入上一步的 XX 结果输出XX 格式的数据让数据流一目了然。2.3 边界与异常真正拉开差距的部分新手写 skill 最容易忽略的就是异常处理。正常流程谁都会写但真正让一个 skill 好用的是它对意外情况的处理能力。我总结了几个必须考虑的边界异常类型典型场景处理建议输入缺失用户没提供必要参数明确列出必填项缺失时主动询问格式错误输入的数据格式不符合预期给出格式示例提示如何修正依赖不可用需要的工具或接口调不通说明降级方案或替代路径结果为空查询或提取没有返回内容区分确实没有和出错了两种情况超出范围输入量超过处理能力说明上限建议分批处理这张表是我踩过不少坑之后总结的。有一次我写了个批量处理的 skill没考虑输入量的问题结果用户丢了几万条数据进来处理到一半卡住了前面的结果也没保存。后来加上单次处理上限 500 条超出请分批的说明问题就解决了。提示边界处理不要写得太啰嗦AI 的上下文是有限的。原则是高频异常详细写低频异常一句话带过。2.4 输出规范让结果可预期、可复用输出规范这部分很多人觉得不重要其实它直接决定了 skill 能不能被组合使用。如果你的 skill 输出格式每次都不一样那下游的 skill 就没法稳定地接住它。我的做法是能用结构化格式就用结构化格式。JSON、YAML、Markdown 表格都行关键是字段名和层级要固定。比如一个提取会议纪要的 skill输出就固定成{ meeting_title: 字符串, date: YYYY-MM-DD, attendees: [字符串数组], decisions: [字符串数组], action_items: [ {task: 字符串, owner: 字符串, deadline: YYYY-MM-DD} ] }这样定好之后下游不管是生成任务清单还是发通知都能直接解析不用再做格式转换。字段命名我一般用下划线风格跟大多数编程语言的习惯一致避免大小写混乱。3. 从零写一个 Skill完整流程与关键决策3.1 先想清楚这个 skill 的边界在哪动手写之前最重要的一步是划定边界。一个 skill 管太多事会变得臃肿难维护管太少事又会导致 skill 数量爆炸、组合复杂。我的经验法则是一个 skill 对应一个可独立交付的成果。什么叫可独立交付的成果比如生成一份数据报告是一个成果把报告转成 PDF是另一个成果。这两个应该拆成两个 skill而不是塞进一个。因为前者关注的是数据分析和组织后者关注的是格式转换两者的输入输出、异常处理都不一样混在一起会让每个部分都写不深。反过来如果两个步骤总是成对出现、中间结果没有独立价值那就应该合并。比如读取配置和校验配置就没必要拆开因为没人会只读取不校验。这里有个判断技巧问自己这个 skill 的输出别人会不会单独用到如果会就独立成 skill如果不会就合并。这个标准在实践中很好用。3.2 用最小可用版本快速验证很多人写 skill 喜欢一次写到位结果写了几百行测试的时候发现方向就错了。我的建议是先写一个最小可用版本MVP跑通主流程之后再逐步加边界处理。最小可用版本长什么样就是只包含正常情况下的核心步骤异常处理先不写输出格式先用最简单的。比如一个整理文件的 skillMVP 版本就三步扫描目录、按类型分组、输出分组结果。跑通之后再逐步加上处理重名文件跳过隐藏文件记录操作日志这些。这样做的好处是反馈快。你花十分钟写个 MVP立刻就能测发现问题马上改。如果花两小时写完整版测试时发现核心逻辑有问题那两小时就白费了。这个思路跟敏捷开发里的快速迭代是一个道理。我自己的习惯是MVP 版本控制在 20 行以内能跑通就继续跑不通就推倒重来。因为 20 行的东西重写成本很低200 行的东西重写就很痛苦了。3.3 测试用例怎么设计才有效Skill 写完之后必须测试但测试不是随便问几个问题就完事。我一般会设计三类测试用例第一类是正常用例就是最典型的输入验证主流程能不能跑通。这类用例要覆盖主要的参数组合比如必填参数都填、可选参数填一部分、可选参数全不填。第二类是边界用例专门测那些刚好卡在临界点的情况。比如输入为空、输入只有一条、输入达到上限、输入包含特殊字符。这类用例最容易暴露问题。第三类是异常用例故意给错误的输入看 skill 能不能优雅地处理。比如必填参数缺失、格式不对、依赖的工具没装。好的 skill 应该给出清晰的错误提示而不是直接崩溃或者胡编一个结果。测试的时候有个技巧把每次的输入和输出都记下来。这样一方面能对比不同版本的表现另一方面也能积累成回归测试集。我一般会建一个表格记录用例编号、输入、预期输出、实际输出、是否通过。跑过几轮之后这个表格就成了 skill 的质量保障。3.4 迭代根据实际使用反馈调整Skill 不是写完就完事了真正好用的 skill 都是迭代出来的。我一般会关注几个信号AI 经常不调用这个 skill说明元信息写得不够吸引人或者适用场景描述不准确AI 调用了但结果不对说明流程步骤有歧义或者边界处理不到位用户经常追问说明输出不够完整或者关键信息没突出执行经常中断说明某一步的依赖或前置条件没写清楚每次遇到这些信号就针对性地改。改的时候注意一次只改一个地方这样才能判断是哪个改动起了作用。如果一次改好几处效果好了也不知道是哪处的功劳效果差了也不知道该回退哪个。我维护的一个 skill 前后改了七八版从最初只能处理简单情况到后来能应对各种边界中间就是靠不断收集反馈、小步调整。这个过程急不得但也正是这个过程让 skill 真正变得有价值。4. 安装与调用不同环境下的实操路径4.1 命令行环境下的安装思路在命令行环境里使用 skills核心思路是把 skill 文件放到约定的目录然后通过命令触发。不同工具的目录约定不一样但逻辑是相通的。以常见的做法为例一般会有一个专门的 skills 目录每个 skill 是一个独立的文件或文件夹。安装方式通常有两种一种是从官方市场或社区仓库直接拉取另一种是手动把写好的文件放进去。从仓库拉取的话一般用包管理命令类似npx这种形式。这里要提醒一句网络环境不同拉取的成功率差别很大。如果遇到拉取失败先检查网络连通性再检查仓库地址是否正确最后看是不是版本不匹配。我遇到过好几次安装失败排查半天发现是本地缓存的问题清一下缓存就好了。手动安装的话关键是目录结构要对。一般要求每个 skill 有独立的文件夹文件夹里有主文件通常是 Markdown 或特定格式的配置文件。放好之后可能需要重启一下工具或者刷新一下索引新 skill 才会被识别。注意安装路径不要有中文或特殊字符很多工具对路径编码的处理不够健壮容易出问题。4.2 验证安装是否成功装完之后别急着用先验证一下。验证的方法通常有几个列出已安装的 skills大多数工具都有类似list的命令能列出当前识别到的所有 skill。如果列表里没有你刚装的说明没识别到。查看 skill 详情有些工具支持查看某个 skill 的详细信息能确认元信息有没有被正确解析。跑一个最简单的调用用最典型的输入试一下看能不能正常触发。这三步走下来基本就能确认安装状态了。如果第一步就失败问题多半在目录结构或文件格式如果第一步过了但第三步失败问题可能在 skill 内容本身。我踩过的一个坑是文件编码不对。当时用了一个带 BOM 的 UTF-8 文件工具解析元信息时把 BOM 当成了内容的一部分导致名称识别错误。后来统一改成无 BOM 的 UTF-8问题就没了。这种细节平时不注意出问题的时候很难想到。4.3 调用时的参数传递调用 skill 的时候参数怎么传是个关键。一般有两种方式一种是在命令里直接带参数另一种是通过自然语言描述让 AI 自己提取参数。直接带参数的方式更精确适合参数固定、格式明确的场景。比如skill run extract-data --input file.csv --output result.json这种。自然语言的方式更灵活适合参数不固定、需要 AI 理解的场景。我的建议是能用结构化参数就用结构化参数。因为自然语言提取参数虽然方便但稳定性差同样的意思换个说法可能就提取不出来了。结构化参数虽然写起来麻烦点但胜在可靠。如果 skill 设计得好它应该能同时支持两种方式。元信息里写清楚哪些参数是必填的、格式是什么AI 在自然语言模式下就能更准确地提取。4.4 常见安装与调用问题排查问题现象可能原因排查方向安装命令报错网络不通或仓库地址错误检查网络确认仓库地址装完列表里没有目录结构不对或未刷新索引检查目录重启工具调用无响应skill 名称拼写错误核对名称用列表命令确认调用报参数错误必填参数缺失或格式不对查看 skill 的参数说明结果不符合预期skill 逻辑有歧义检查流程步骤补充说明执行中途卡住某步依赖不可用检查依赖看是否有降级方案这张表是我在实际使用中慢慢积累的。每次遇到新问题就加一行时间长了就成了一份排查手册。建议你也养成这个习惯把遇到的问题和解决方法记下来下次再遇到就能快速定位。5. 组合与进阶让 Skills 真正发挥威力5.1 把多个 skill 串成工作流单个 skill 能解决的问题有限真正的威力在于组合。比如你要做一个自动生成周报的流程可以拆成几个 skill一个负责从各个数据源收集信息一个负责整理成结构化数据一个负责生成文字描述一个负责排版输出。每个 skill 各司其职串起来就是一个完整的工作流。串联的关键是接口要对齐。上一个 skill 的输出格式必须能被下一个 skill 的输入接受。这就是为什么前面强调输出规范要固定——只有格式稳定组合才稳定。串联的方式有两种一种是线性串联A 的输出给 BB 的输出给 C一条线走到底。另一种是分支串联根据中间结果决定走哪条路。比如数据校验通过就走正常流程不通过就走修复流程。线性串联简单可靠分支串联灵活但复杂建议先从线性开始熟练了再上分支。5.2 用 skill 沉淀团队经验Skills 最大的价值之一是把个人经验变成团队资产。团队里某个资深成员摸索出来的方法写成 skill 之后新人直接调用就行不用从头摸索。我见过一个团队把代码审查的规范写成了 skill。每次提交代码前先跑一遍这个 skill它会按照团队约定的检查项逐条过一遍输出一份检查报告。这样一来代码审查的基线就统一了不会因为审查人不同而标准不一。沉淀经验的时候有个要点写为什么而不只是怎么做。因为新人调用 skill 的时候如果只看到步骤不理解背后的原因遇到变通情况就不知道怎么处理。把原因写进去新人就能举一反三。5.3 性能与上下文优化Skill 用多了之后会遇到一个现实问题上下文不够用。每个 skill 都要占一定的上下文空间装太多之后AI 能用来处理实际任务的空间就少了。优化的思路有几个。一是精简 skill 内容把不常用的细节移到外部文档skill 里只留核心步骤。二是分层组织把相关的 skill 归到一个组里按需加载。三是合并同类项把功能相近的 skill 合并成一个减少数量。我一般会定期清理 skill 库把用不上的删掉把能合并的合并。保持一个精简的集合比堆一大堆用不上的强。这个道理跟整理工具箱一样——工具不在多在于顺手。5.4 版本管理与更新Skill 也是代码也需要版本管理。我建议把 skill 文件纳入版本控制每次修改都提交这样能追溯每次改动的内容和原因。更新的时候要注意向后兼容。如果改了输出格式下游依赖这个 skill 的流程可能会受影响。所以改格式的时候要么保留旧格式一段时间要么同步更新所有下游。我自己的做法是小改动直接改大改动开新版本。比如只是修正一个错别字直接改就行如果要调整输出结构就新建一个 v2 版本让旧版本继续可用等下游都迁移过来了再废弃旧版本。这样既保证了稳定性又给了迁移的缓冲期。6. 我踩过的那些坑真实经验分享6.1 描述太模糊导致 AI 选错技能最开始写 skill 的时候我总觉得描述写得宽泛一点适用面更广。结果恰恰相反——描述太宽泛AI 反而不知道该在什么时候用它。有一次我写了个处理文本的 skill结果 AI 在遇到任何跟文本沾边的任务时都想调用它包括那些根本不该用它的场景。后来我把描述改具体了明确写上用于把非结构化文本整理成指定字段的表格误调用就少了很多。这个教训是描述要窄而准不要宽而泛。宁可写清楚不适用什么也不要含糊地什么都能干。6.2 步骤太粗导致执行不稳定另一个坑是步骤写得太粗。我早期写的一个 skill流程就三步收集、处理、输出。结果每次执行AI 对处理这一步的理解都不一样有时候多做一点有时候少做一点输出很不稳定。后来我把处理拆成了五步每一步都写清楚输入什么、输出什么、怎么判断做完了。拆完之后稳定性明显提升。这个经验告诉我步骤的粒度要以能独立验证为准。如果一步做完你没法判断对不对那就说明拆得还不够细。6.3 忽略边界导致中途崩溃边界处理这个坑我踩得最多。有一次写了个批量处理的 skill测试的时候用几条数据跑得好好的结果用户拿几百条数据一跑中途就卡住了。排查发现是某一步没有处理数据量过大的情况内存爆了。从那以后我写任何涉及批量的 skill都会先想清楚输入量有没有上限超了怎么办要么在 skill 里写明上限要么设计成分批处理。这个习惯帮我避免了很多类似的问题。6.4 输出格式不固定导致无法组合还有一个坑是输出格式。我早期写的 skill输出格式比较随意有时候是列表有时候是段落。单独用没问题但想跟其他 skill 组合的时候就麻烦了——下游 skill 没法稳定地解析上游的输出。后来我强制自己所有 skill 的输出都用结构化格式。能用 JSON 就用 JSON不能用 JSON 就用固定格式的 Markdown。这样虽然写的时候麻烦一点但组合起来非常顺畅。6.5 不写不适用场景的代价最后说一个容易被忽略的点不适用场景。我一开始觉得这个字段可有可无后来发现它其实很重要。因为 AI 判断该不该用某个 skill的时候如果有明确的排除条件判断会准确很多。比如一个生成测试数据的 skill如果不写不适用于生产环境数据AI 可能会在需要真实数据的场景下也调用它。写上之后这种误用就避免了。所以现在我写 skill元信息里一定会包含适用场景和不适用场景两部分。7. 关于 Skills 的几个常见疑问7.1 Skills 和普通提示词有什么区别这是被问得最多的问题。简单说提示词是一次性的skill 是可复用的。提示词你这次写完下次还得重新写skill 写一次之后每次调用就行。更深层的区别在于结构化程度。提示词可以很随意想到什么写什么skill 要求有明确的元信息、流程、边界、输出规范。这种结构化带来的好处是稳定性和可组合性代价是写的时候要多花点心思。打个比方提示词像是口头交代一件事skill 像是写了一份正式的操作文档。口头交代快但容易遗漏文档写得慢但可靠、可追溯、可复用。7.2 什么样的任务适合写成 Skill不是所有任务都值得写成 skill。我的判断标准是这个任务会不会重复做如果只做一次写 skill 的时间可能比直接做还长不划算。如果会反复做那写 skill 就是一次投入、长期受益。另外任务要有相对固定的流程。如果每次的做法都不一样那也没法写成 skill。适合写成 skill 的任务通常是那些步骤明确、输入输出可定义、边界情况可枚举的。举几个典型的例子数据格式转换、报告生成、代码规范检查、文件批量处理、信息提取整理。这些任务都有明确的流程适合 skill 化。7.3 写 Skill 需要编程基础吗基础的 skill 不需要编程基础会写清楚步骤就行。因为 skill 本质上是用自然语言写的操作说明AI 负责理解和执行。但如果想写进阶的 skill比如涉及调用外部工具、处理复杂数据结构的那懂一点编程会很有帮助。至少要知道什么是 JSON、什么是 API、什么是异常处理这些概念能帮你把 skill 写得更严谨。我的建议是从简单的开始写边写边学。先写一个纯文本处理的 skill跑通了再尝试涉及工具的。循序渐进比一上来就啃复杂的要有效得多。7.4 Skill 写多长合适这个问题没有标准答案但有个大致的参考核心流程控制在 50 到 200 行之间。太短了说明步骤没拆细太长了说明可能该拆成多个 skill 了。我一般会看两个指标一是执行成功率如果经常出错可能是写得太简略二是维护成本如果改一处要动很多地方可能是写得太臃肿。在这两个指标之间找平衡就是合适的长度。另外内容多的时候可以把细节放到外部文档里skill 里只留核心步骤和引用。这样既保证了完整性又控制了 skill 本身的体积。7.5 怎么判断一个 Skill 写得好不好我的判断标准有三个稳定、清晰、可组合。稳定是指同样的输入多次执行结果一致。如果每次结果都不一样说明流程有歧义。清晰是指读一遍就能明白它在干什么不用猜。可组合是指它的输出能被其他 skill 接住不会因为格式问题卡住。这三个标准里稳定是基础清晰是要求可组合是进阶。先把稳定做到再追求清晰最后考虑组合。一步一步来不用一开始就追求完美。8. 最后分享几个实用技巧写到这里该讲的原理和流程基本都覆盖了。最后分享几个我在实践中总结的小技巧都是那种知道了能省不少事的。第一个技巧给 skill 起名要有规律。我一般用动词名词的格式比如extract-data、generate-report、validate-config。这样一看名字就知道是干什么的也方便按功能分组。避免用tool1、helper这种没信息量的名字。第二个技巧在 skill 里留一个示例区块。给一个典型的输入和对应的输出AI 看了之后对预期的理解会准确很多。这个区块不用长一两组示例就够但效果很明显。第三个技巧定期回顾和清理。我每个月会花半小时过一遍自己的 skill 库把用不上的删掉把能改进的记下来。保持库的精简比一味增加要重要。第四个技巧把踩过的坑写进 skill。每次遇到问题并解决之后把这个问题和解决方法补进 skill 的边界处理部分。这样 skill 会越用越完善下次遇到同样的问题就不用再排查一遍了。第五个技巧不要追求一次写完美。先写个能用的版本用起来根据实际反馈改。完美的 skill 不是写出来的是改出来的。我最好的几个 skill都是改了七八版之后才稳定的。Skills 这个东西说到底就是把怎么做一件事的经验显式地写下来让 AI 能稳定地复用。它不神秘也不复杂关键是要动手写、动手改。写得多了自然就有感觉了。