1. 从“知道”到“会用”：先弄懂 Skills 的准确位置
1.1 它和 Prompt、MCP、Function Calling 有什么不一样
先说结论：Claude Agent Skills 不是另一种 Prompt 写法，也不是 MCP 的替代品，而是一套让 Agent “按需加载能力”的机制。你可以把 Skills 理解成给 Claude 准备的一沓“岗位说明书+操作手册”，平时收在抽屉里，遇到对应任务才抽出来照着做。
很多人第一次听到 Agent Skills 时，会不自觉地把它和 Prompt 工程混在一起。我刚开始也这样想，后来实际写了两三个技能才反应过来——它比塞 Prompt 更结构化，也比裸调 Function Calling 更好维护。举一组粗糙的类比：
| 机制 | 类比 | 适合场景 |
|---|---|---|
| 系统提示词 | 给员工念一遍公司价值观 | 全局性约束，不适合堆细节 |
| Function Calling | 给员工一部电话，说需要时打 | 单个接口调用，缺少上下文 |
| MCP | 给员工一个工具箱+使用手册 | 连外部系统，适合复杂集成 |
| Agent Skills | 给员工一套按任务封装的 SOP | 让模型“学会”做一类事 |
这套机制核心的改动是：技能文件里既能写“怎么想”，也能写“怎么做”，甚至能直接挂一小段可执行脚本。Claude 在对话过程中发现任务符合某个技能描述时，会把技能内容读进来，再按上面约定好的方法和示例完成任务。
所以从实操上看，Skills 照顾的是“单一任务的完成质量”，而不是“整个系统的连接能力”。这一点想清楚后，后面的设计思路才不会跑偏。
1.2 为什么它在 Agent 实操里特别“顺手”
我实际用下来的感觉是：Agent Skills 把“能力封装”的入口做得足够低，几乎不需要写框架代码，也不需要维护消息协议。
传统做法里，你想让模型稳定处理某个重复任务，通常要写一大段带 few-shot 的 Prompt，然后在代码里做输入清洗、结果校验、异常重试。而用 Skills 的话，你只需要建一个目录，把任务说明、规则、示例甚至一个小脚本放进去，模型在合适的时机自己会取用。这样等于把原来散落在业务代码里的“提示词+校验逻辑”集中到了一处，维护成本直接降了一个档位。
我还在一个小项目里对比过：同样做“抽取合同关键字段”这件事，用 Prompt 硬写的话，每次想改字段规则都得改代码；换成 Skill 后，调整的是文档和示例，业务代码几乎不用动。对经常迭代的自动化流程来说，这种“变更隔离”才是真正的价值。
另外一点很实用：Skills 的编排方式完全对人有好。技能目录打开就是说明文本，新同事接手时跑一遍技能描述就能知道流程目的，不用像看老项目注释那样在代码里考古。
2. 动手前的设计思路：先把技能边界画清楚
2.1 按“任务”而不是按“接口”设计技能
我第一次设计技能时犯了一个典型错误：按 API 接口来拆，比如“调用 PDF 解析接口”“调用 OCR 接口”“调用摘要接口”。结果没多久技能目录就膨胀成接口列表，模型经常不知道该拿哪一个，选错后输出质量反而更差。
后来调整思路，按“用户意图+完成标准”来拆。比如不再做“PDF 解析技能”，而是做“合同关键信息抽取技能”——这个技能内部会自己决定要不要解析 PDF、要不要查表格、要不要合并字段。判断技能边界很简单：问自己一句，用户想完成什么任务，而不是这个任务里要不要调某个工具。
实操上我给自己的拆分标准有三条：
- 输入是“一句自然语言目标”，而不是“一个接口参数”。
- 输出有明确交付物，比如填好的表格、改完的文件、一段报告。
- 内部步骤可以变化，但结果稳定可验证。
如果一个技能满足了这三条，那它就是独立成“技能”的候选；如果拆了一半发现输出互相依赖，说明该合并成一个复合技能。
2.2 描述、参数与示例：三个影响成功率的关键点
技能描述是模型判断“什么时候该用我”的依据，这块写得太泛会频繁误触发，写得太窄又会漏触发。我的建议是：描述里必须包含“触发场景+核心目标+关键限制”。比如：
当用户需要从投标文件中提取报价信息时使用本技能。输入可以是任何格式的标书文件，输出为结构化的报价对比表。注意：只处理报价相关字段，不分析技术方案。
这种写法让模型在意图判断阶段就能快速排除掉无关请求。
参数部分看起来简单，但很多人会忽略“类型约束”的重要性。要在技能说明里明确标出：哪些是必填、哪些可选、默认值是什么、枚举值有哪些。模型不是编译器，你不写清楚，它就会在边界值上自由发挥。我遇到过让模型传日期格式，结果一次 yyyy-mm-dd 一次 mm/dd/yyyy 的情况，自从我在示例里固定了“传参格式必须精确到天，格式统一为 YYYY-MM-DD”后，再没犯过这种错。
示例则是模型“照着学”的最短路径。一个技能文档里最好给两个示例：一个最常规的输入输出对，一个带边角情况的输入输出对。示例不需要很长，但要完整展示从“用户输入”到“最终输出”的演变过程，别只给结果。
3. 三个实战案例：从零跑通你的第一个 Skills
3.1 案例一：PDF 内容摘录技能（简单入门）
为了做第一个技能，我选了一个几乎人人都会遇到的场景：把扫描版或文字版 PDF 里的信息整理成条理清楚的摘要。
建好技能目录后，我在里面放了三类东西：技能说明文档、提取规则、以及一个解析脚本的调用示例。技能说明里写了触发场景和输出格式，提取规则里明确了“保留金额、有效期、责任人”等关键字段，示例则演示了针对一个标准合同页，输入长什么样、输出长什么样。
模型在使用这个技能时，会自动读入技能文档，按文档约定先调用解析脚本提取文本，再按字段规则做结构化输出。一次跑完，原来我要手动复制粘贴半天的内容，几百字就生成完毕，排版还很干净。
这个案例对新手最关键的作用是理解“技能目录不是代码仓库”——里面多数内容其实是给人看、给模型看的结构化说明，真正的脚本只是辅助工具。你不需要写出多复杂的代码，先让模型理解“何时用、怎么用、输出成什么样”，技能就已经成功了一大半。
补充几点注意事项：
- 扫描版 PDF 必须先做 OCR，技能说明里就要提醒模型“解析失败时尝试图像识别”，别让它卡在第一步。
- 摘录出来的文档要附带“来源页码”字段，后面人工核对时能省很多事。
这些都是我在真实项目里踩过后整理出来的，直接放进技能说明中当规则即可，模型会替你把麻烦挡在前面。
3.2 案例二：提交信息生成技能（利用 Git 差异）
第二个案例稍微进阶一点：让 Claude 根据 git diff 自动生成提交信息。这个技能需要模型读本地命令的执行结果，所以技能里既要有“读取 git 命令输出”的脚本，也要有“如何总结变更”的规则。
我的做法是在技能目录里放置一个脚本，它负责运行 git diff 并把结果保存到临时文件中；技能说明里则定义总结规则：提交信息必须包含“变更动机+影响范围+风险点”，英文不超过 50 个字符，中文不做严格限制。
模型执行时先跑脚本拿到 diff，再按照规则组织语言，最后直接输出提交信息供我复制。实测下来，大部分常规提交都能一遍过，偶尔需要我手动微调措辞，但已经比从零开始写强得多。
这个案例值得参考的关键点有几个：
- 技能内部调用脚本时，工作目录必须明确，否则模型找不到仓库。
- git diff 输出可能非常长，要在技能说明中交代“只关注非测试文件的关键逻辑变更”，限制输出量。
- 提交信息风格众口难调，最好在技能文档里先给出一个“团队认可模板”，让模型按模板扩写。
我还在技能里加了道“防止自卖自夸”规则：禁止描述中出现“优化了性能”这类没有可度量结论的说法，必须写清楚“减少了多少次请求”或“降低了多少毫秒延迟”。这一点对保持提交信息真实性帮助很大。
3.3 案例三：Web 数据巡检技能（结合定时任务）
这个案例是我不久前才做成功的，也最能体现 Skills 的灵活度：每天定时让 Agent 检查指定页面内容，提取关键更新并汇总成简报。
实现上，技能包含两个核心部分：一个是抓取页面并抽取正文的脚本，另一个是“更新判断”的规则文档。比如检查一个产品文档页面，规则里定义了“哪些字段变化算重要更新（版本号、接口变动、收费说明）”“哪些变化可以忽略（排版调整、文案润色）”，脚本跑完后由 Claude 判断是否需要写入日报。
这个场景的价值在于，日常人工巡检容易疲劳，而模型配合技能可以做到每天固定时间高标准地“盯梢”，把结果整理好发给我。我做出来后最大的感受是：技能封装的不是“抓取”这个动作，而是“巡检并输出报告”这整件事，所以后续想增加检查维度时，只需要改文档规则，完全不用动脚本。
遇到的一个坑是页面编码问题，特别是部分站点返回的字符集声明与文件实际编码不一致。我在技能说明中加了一条：脚本抓取后先尝试按 utf-8 解码，若报错则回退到 gb18030，并把“解析异常”当作一种结果返回，而不是直接让任务失败。加入这个容错逻辑后，整个巡检任务稳定了不少。
4. 调试心得与常见问题速查
4.1 调试思路：先怀疑描述，再怀疑环境
技能出问题时，我的第一反应不是看代码，而是重新读技能描述。实际排查中，大部分“技能失效”都源于描述和真实任务不匹配，模型压根没意识到该用这个技能。
如果你发现模型明明该用技能却没用，请先检查触发条件写清楚了没有，尤其要检查场景词是否具体；如果你发现用了技能但输出完全跑偏，再检查规则文档和示例是否露出歧义。这两步走完，再去检查脚本、权限、路径等环境问题。
举个例子：我早期做过一个“会议纪要整理技能”，描述里只写了“用户提供会议内容时整理纪要”，结果模型在普通聊天中也频繁触发，把闲聊内容也整理成纪要。后来我加了触发约束：“仅当输入包含明确的会议主题、参与人或时间信息，且用户要求整理纪要时才使用”，误触发率立刻降下来。
这类问题非常隐蔽，因为表面看“技能在正常工作”，但整体体验已经乱了。调试时要记得留意对话上下文中技能被调用的时机，而不要只看输出是否合规。
4.2 常见问题速查表
| 症状 | 可能原因 | 处理方式 |
|---|---|---|
| 该用技能时没触发 | 描述中触发条件太模糊 | 补充具体场景词、限制条件 |
| 不该用时触发了 | 描述里缺排除规则 | 增加“注意：仅在…时使用”的排除句 |
| 输出格式不稳定 | 示例太少，格式约束弱 | 增加标准输入输出对，固定模板 |
| 脚本执行失败 | 路径、权限、依赖缺失 | 在技能文档中写明运行环境、相对路径 |
| 结果偶尔正确偶尔错误 | 规则文档有歧义 | 拆开规则，逐条说明，并给出正反例 |
| 模型过度调用脚本 | 技能说明没交代“可选步骤” | 注明哪些步骤可按需跳过 |
这张表是我自己血泪换来的。每个问题基本都遇到过，尤其是“该触发不触发”和“格式不稳定”这两类，占了排障的大半时间。
4.3 哪些坑我踩得最狠
第一个坑是“示例太美好”。我最初写的技能示例都是理想输入，真实使用中用户根本不会按示例说话。比如示例里是“请提取合同中的甲方和乙方”，实际用户说“你看看这合同里俩公司叫啥”。后者照样能触发，但如果技能文档里强依赖“输入必须包含明确动作词”，就会漏触发。所以我现在写示例时会主动加一两个口语化变体。
第二个坑是“技能内部逻辑过重”。有些技能我恨不得把公司所有业务规则都塞进去，结果模型读取时理解负担过大，反而丢关键约束。后来我学会控制在“一屏以内说完核心规则”的体量，更多细节写进可选的参考文档，需要时再让模型去读。
第三个坑是“把输出设计得太复杂”。我曾经要求技能一次输出五段式报告，结果模型为了“凑结构”，经常编造细节。改成“先输出核心结论，再按需展开”后，可信度立刻提升。记住：输出结构越复杂，幻觉风险越高，初始版本尽量让输出简单可验证。
5. 进阶：从单个技能到技能矩阵
5.1 用多个技能组合完成复杂工作流
单个技能解决单点问题，但真实业务往往是多个单点组成的流程。用一段时间后，我开始尝试让 Agent 在工作流中依次调用多个技能。
比较典型的是“周报自动生成”场景：先调用“信息收集技能”扫描本周代码提交和文档变更，再调用“内容筛选技能”判断哪些值得写进周报，最后调用“文风润色技能”把内容整理成正式表述。每个技能独立维护、单独调试，组合起来却是一条完整流水线。
实现这种流程，关键不在某个技能内部，而在技能间“交接形式”。每个技能输出都要足够结构化，最好是统一的 markdown 或 JSON 片段，方便下一个技能直接当作输入。我在每个技能文档末尾都写了一节“输出交接格式”，规定好字段名和层级，这样组件之间才拼得起来。
还有一个技巧：给技能设置“版本说明”，每次调整规则时更新一下日期和变更点。模型虽然不会主动看版本，但在排查问题时，你能快速定位是哪个版本的规则导致行为变化，免去了大海捞针的烦恼。
5.2 我坚持的几条经验原则
做了这么久技能的实操，我渐渐总结出几条做事原则，不一定适合所有团队，但至少在我这边的项目里很管用。
第一，技能要小步迭代。不要想着一次性写出完美技能，先把最核心的一小步跑通，再逐步加规则。我第一版“合同抽取技能”只抽“甲方、乙方、金额”三个字段，跑通后才慢慢加“付款条件、违约责任”。每次只改一个维度，出问题也好定位。
第二，技能文档要“防 AI 味”。如果技能里的规则写得太抽象，模型执行时就会自作主张。我现在写规则时尽量用命令式短句，比如“必须保留原金额单位”“不得猜测缺失字段”，而不是“请尽量确保字段完整”。命令越直接，模型遵守得越好。
第三，保留技能回退入口。哪怕技能做得再完善，也要让用户/模型在异常情况下可以跳出技能、直接人工处理。我在多数技能文档最后都加了一句“如遇到规则无法覆盖的输入，直接输出原始内容并提醒用户检查”，这给 Agent 留了一条安全底线，避免它在错误方向上硬着头皮给出不靠谱结果。
如果说还有最后一条，那就是别滥用技能。有些任务用普通 Prompt 几行就能解决，就不必做成技能；技能真正的价值在“可复用、要维护、多场景使用”这三项全占的时候。设计前先问自己：这个技能本周用了几次？如果不做技能，成本会有多高？想清楚再动手，才不会让技能目录变成一个无人维护的杂物间。
