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），跑通主流程之后再逐步加边界处理。
最小可用版本长什么样？就是只包含"正常情况下的核心步骤"，异常处理先不写，输出格式先用最简单的。比如一个"整理文件"的 skill，MVP 版本就三步：扫描目录、按类型分组、输出分组结果。跑通之后，再逐步加上"处理重名文件""跳过隐藏文件""记录操作日志"这些。
这样做的好处是反馈快。你花十分钟写个 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 的输出给 B，B 的输出给 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 能稳定地复用。它不神秘，也不复杂，关键是要动手写、动手改。写得多了，自然就有感觉了。
