如果你关注大模型应用开发，最近一定频繁撞见skills这个词。从各家 Agent 产品到开源框架，都在把"技能"当成头等公民对待。这不是换个马甲炒冷饭，而是大模型从"什么都能聊"走向"用得顺手"的一条必经之路。今天这篇不聊概念，直接拆开揉碎讲清楚：Skills 到底是什么、怎么设计、怎么写、怎么调，以及我在实际项目中踩过的那些坑。
1
1. 内容整体设计与思路拆解
1.1 Skills 解决的核心痛点
先还原一个真实场景。半年前我做了一个文档助手，把公司内部的操作手册、流程说明全部塞进知识库，效果差强人意。用户问"报销单怎么填"，模型能答出大概步骤，但一旦涉及具体系统操作，比如"提交审批时附件格式有什么要求"，它就露馅了。原因很简单：知识库给的是"信息"，而用户要的是"执行能力"。
Skills 这个设计恰好补上了这块短板。它的核心思路是把某一类任务的操作流程、经验规则、边界条件打包成一个可复用的"能力单元"。模型不需要临时推理"这个步骤该怎么走"，而是直接加载一份成熟的操作规范，按图索骥。你可以把它理解成给大模型配了一本岗位 SOP 手册，而不是一本百科全书。
1.2 为什么是现在才火
早先的 prompt 工程不是不能做类似的事，但大家都在一条超长的 system prompt 里堆逻辑，结果就是上下文越堆越长、模型注意力越来越散，改一处牵扯全身。Skills 的做法是拆：把任务拆成多个独立模块，按需加载。用户问报销，就只加载报销技能；问请假，就加载请假技能。每一次对话都不会被无关信息污染。
另一个推动力是各家产品开始支持开放技能格式。Claude 的 Agent Skills、OpenAI 的 Custom GPT Actions，以及开源社区的SKILL.md规范，都在朝"一次编写、到处运行"的方向靠拢。我自己的实测感受是：格式还谈不上统一标准，但骨架已经非常接近，迁移成本比想象中低。
1.3 适用人群和场景边界
如果你正在做这几类事情，Skills 值得花时间研究：
- 做垂直领域的问答机器人，特别是包含多步骤操作指引的场景
- 给企业内部知识库加一层"会干活"的能力，而不是只会检索
- 做自动化流程，比如邮件分类、日报生成、会议纪要整理
- 折腾个人效率工具，希望同一个技能在命令行和网页端都能复用
反过来，如果你的任务是一次性的、不重复的，或者强依赖外部系统的实时状态（比如查库存），Skills 不是最合适的方案，那需要的是 API 编排。
2. 核心细节解析与实操要点
2.1 一份 SKILL.md 的解剖
现在社区里比较公认的 Skills 载体是 Markdown 文件，典型结构长这样：
--- name: meeting-minutes description: 根据会议录音或文字稿整理结构化会议纪要 --- # 会议纪要整理技能 ## 适用场景 - 线上会议录音转文本后的二次加工 - 线下讨论的手写/打字笔记整理 ## 处理步骤 1. 识别会议主题与参会人 2. 提取讨论焦点，按议题归类 3. 区分"已决议事项"与"待办行动项" 4. 明确每项待办的责任人与截止时间 ## 注意事项 - 保留原始语气中的模糊表述，不要擅自补全信息 - 若信息不足，在"待确认"部分列出缺失项关键在于 frontmatter 里的name和description。模型判断"什么时候该用这个技能"，完全靠这两个字段。description 写得好不好，直接决定技能的命中质量。我见过太多人栽在这里，description 写成"整理会议纪要，包括会议主题、参会人、决议、待办"，模型把它和另一个"会议总结技能"搞混。正确写法是要把触发条件、输入要求、输出结果写清楚，比如"将口语化的会议文字稿整理成含决议与待办的结构化纪要，适用于产品评审、项目周会等正式或非正式会议场景"。
2.2 文档与脚本的分工
很多人把 Skills 理解成"写一份更长的 prompt"，这低估了它的设计空间。一个成熟技能往往包含三部分：指令文档、参考资源、可执行脚本。
指令文档（SKILL.md）负责给模型讲清楚"怎么做"。参考资源（references/ 目录）提供补充材料，比如模板、示例、历史案例。可执行脚本（scripts/ 目录）则承担模型不擅长的确定性计算——日期推算、文件格式转换、JSON 解析。模型负责"思考"，脚本负责"计算"，各干各擅长的。
我做过一个周报技能，最早版本全让模型自己输出，结果周一起始日总是算错（模型会默认今天是周一）。后来加了一个 shell 脚本，调用系统日期命令生成本周日期范围，模型只负责按框架填内容，错误率直接归零。这类"模型不可靠、脚本可靠"的部分，一定要从自然语言里剥离出去。
2.3 上下文加载策略
Skills 的文件不能无限堆长。模型单次上下文窗口有限，如果每次触发技能都把整个目录读进去，还没有开始干活，窗口就先爆了一半。
我常用的策略是把指令控制在 500 行以内，超过的部分放到 references 里按需引用。比如一个客户支持技能，处理退换货的规则放在主文件，而完整的退换货政策原始文档放在 references 里。模型先按主文件的步骤走，到具体环节时再决定是否读取政策原文。这种"主指令 + 按需检索"的加载方式，比一次性全量注入稳定得多。
3. 实操过程与核心环节实现
3.1 从零构建一个技能：完整过程
拿一个我最近做的"会议纪要整理技能"当作完整案例走一遍。它接收会议文字稿，输出结构化 Markdown 纪要，包含决议、待办、风险。
第一步，建目录结构：
meeting-minutes/ ├── SKILL.md ├── references/ │ ├── template.md │ └── examples/ │ ├── product-review.md │ └── weekly-sync.md └── scripts/ └── extract_actions.py第二步，写 SKILL.md。开头是 frontmatter，描述部分我反复调了三版才满意。初版是"整理会议纪要"，太泛；第二版加了"生成包含决议和待办事项的 Markdown 文档"，有所改善但没解决触发混乱的问题；终版明确写出"输入为口语化会议记录或录音转写文本，输出结构化 Markdown，含议题清单、明确决议、带责任人和时间的待办事项，适用于产品评审、周会、跨部门同步会"。改动之后，模型在合适的场景调用对的技能，成功率明显提升。
第三步，处理模板。模板是模型输出的格式基准，一定要最细化：
# 会议纪要：<会议主题> - 日期：<YYYY-MM-DD> - 参会人：<姓名，逗号分隔> - 记录人：<姓名> ## 议题与讨论 ### <议题一> <讨论要点及结论> ## 本次决议 - <决议内容，注明达成决议的与会者> ## 待办事项 | 事项 | 责任人 | 截止时间 | |------|--------|----------| | <待办内容> | <姓名> | <YYYY-MM-DD> | ## 风险与遗留问题 - <风险描述或未决事项>模板有两点容易被忽略：一是待办事项必须带责任人和截止时间，否则模型很可能输出"尽快完成"这类无法追踪的内容；二是加一个"默认日期来源"说明，要求模型优先使用会议记录里的日期，不要自己推断。
第四步，写提取脚本。模型能从文本里识别出"张三要在月底前给出新版本排期"，但它不擅长把相对时间换算成绝对日期。extract_actions.py接收模型标记好的待办原文，自动完成日期规范化。脚本逻辑不复杂，几十行 Python，正则加 dateutil 做自然语言日期解析。关键是趁手，把模型不擅长的那部分可靠地补上。
3.2 挂载与调用边界
技能写好之后怎么挂载，取决于你的运行环境。在 Claude 工作区里，直接把SKILL.md放进.claude/skills/meeting-minutes/即可。在很多开源 Agent 框架里，则是通过 tools 配置把技能目录注册进去。自己写代码调用也不复杂，核心思路就是：先把 SKILL.md 和必要的 references 拼装进 system prompt，再把用户输入递进去。一个问题，框架通常会帮你做，不用重复造轮子。
但有一个边界必须说清楚：Skills 不等于 API 调用。如果技能需要读取外部系统的实时数据，比如查询 CRM 里的客户信息，光写 Markdown 不够，你得同时提供一个能被模型调用的函数。SKILL.md负责教会模型"什么时候调、怎么调"，真正的数据交互由函数完成。二者缺一不可。
3.3 组合技能的串联思路
进阶玩法是把技能串联起来。我做过一条完整的"销售线索处理流水线"，由三个技能协作：邮件清洗 → 线索评分 → 日报生成。前一个技能的输出自动成为后一个技能的输入。
组合的关键是格式接口。两个技能衔接处的数据结构必须严格一致，比如邮件清洗技能固定输出 JSON 数组，线索评分技能的输入就必须按这个 JSON 数组设计。衔接格式必须写清楚，否则模型在环节切换时容易自由发挥，输出一堆对方技能读不懂的内容。我在每个技能文档末尾都加了一段"输出格式约定"，标注下游技能的名字和期望输入。这个习惯后来帮了大忙，遇到链路问题时一眼就能定位是哪个环节的字段对不上。
4. 常见问题与排查技巧实录
4.1 技能激活率低的排查思路
技能没被触发是日常最常遇到的问题。排查顺序我总结了一个固定套路。
先看 description 的触发条件是否写清楚。如果描述里没有说明"什么样的输入应该调用本技能"，模型自然不知道何时出手。把触发词、使用场景补进去，往往能解决一大半问题。
再看技能命名是否和现有的其他技能混淆。如果你有"邮件写作"和"邮件总结"两个技能，模型就容易选错。命名尽量差异化，描述里再加一句"与其他邮件类技能不同，本技能仅用于……"这样的排除性说明。
最后看上下文顺序。有些框架会把技能列表放在对话历史之后，距离越远的技能，模型选择的准确率越低，特别是上下文被拉得很长的时候。我试验过把技能清单尽量前置，命中率有可感知的提升。
4.2 上下文过度膨胀的应对
技能文件本身写得太大，触发后把 references 全部加载，会导致对话很快接近上下文上限。一个明显的征兆是，模型生成到一半开始"忘记"技能最初的指令，后续输出偏离步骤。
应对手法有两个。一是主文档精简化，把描述性文字和案例拆到 references 里。二是给 references 里的文件加"按需查找"说明，告诉模型"仅在步骤 3 需要计算截止日期时才读取 calc_date.py 的说明"。这个指令写在主文档的处理步骤里，模型会严格遵循。
4.3 路径与迁移的兼容问题
不同 Agent 框架对技能目录的默认路径不一样，有的读.claude/skills，有的读skills/，有的要求技能文件夹名称与技能名一致。迁移时最先踩的就是路径不一致，SKILL.md 内容没问题，但因为放错位置，框架根本扫不到。
另外 Markdown 里的相对路径也要注意，references 文件在 SKILL.md 里引用时用相对路径，有的框架能正确解析，有的会直接读到不存在的内容。如果发现技能加载后模型频繁"找不到"参考文档，先检查是不是路径解析的问题。
4.4 一个关于中文场景的特别提醒
中文任务的技能，最容易出问题的不是模型能力，而是日期和数量词。"下周五""月底前""大概两百份"这类表达，模型经常理解得有偏差。SKILL.md 里要专门写明"日期一律补充格式要求，遇到相对时间必须结合上下文最近的绝对日期进行换算"。
还有一个奇怪但真实的坑：英文标点。模型有时会把中文逗号写成英文逗号，导致脚本处理 CSV 或 JSON 时直接报错。如果你写了脚本对接步骤，在指令里加一条"所有生成的文本统一使用中文标点"，能省掉不少调试时间。
做这个技能包我自己最深的体会是：Skills 本质上是在训练与模型协作的"契约"，你写得越清晰、越像一份可执行的规章制度，模型的表现就越稳定。它不需要你懂机器学习，但需要你有拆解任务、描述边界、设计流程的能力。
如果你正准备尝试，建议从一个你反复做过的、步骤明确的小任务开始，比如周报整理或简历筛选。做得多了，你会发现那些原本依赖人脑记忆的流程，正在一个个变成可复用、可分享、可持续改进的资产。这大概就是 Skills 最有意思的地方——它让每个普通人都能把自己的经验固化下来，形成可以复制的能力积木。
