1. 为什么技能Skills在AI应用里成了新的组织单元做AI应用和智能体大概半年多之后我最大的感受是提示词工程没死但它正在变成一门组织学。以前我们把所有希望寄托在那一两段精心打磨的系统提示词里后来发现提示词越长AI反而越糊涂效果越不稳定。于是有人开始把大任务拆成工作流用流程去约束模型。但现在我身边越来越多的人开始讨论一个更自然的单位——技能Skills也就是把怎么做好某件事完整封装成一个模块让智能体在需要的时候自己找到它、加载它、执行它。1.1 我理解的技能包到底是什么如果让我用一句大白话解释技能包就是给AI的一份带附件的岗位说明书。它不只是一段提示词而是一个小文件夹里面装着三样东西说明文档、可选脚本、参考资料。说明文档告诉AI这个技能是干什么的、按什么步骤做、输出什么格式脚本负责真正需要计算、抓数据、读文件的部分参考资料则是模板、样例、规则清单这些东西。举个例子我给自己做了一个周报生成技能。放在技能目录里就是这样一个结构weekly-report/ SKILL.md templates/ weekly-report-template.md examples/ sample-report.mdSKILL.md 里写清楚当用户提到本周工作汇总、周报、周总结时使用该技能。先问三个必填问题本周重点事项、问题与风险、下周计划然后按给定模板填充最后输出Markdown格式报告。 模板和样例放在 resources 目录里AI 在生成时会自动读取参考。这类技能的妙处在于你不需要在对话里反复贴模板、贴规则AI会在合适的时机主动翻开这个文件夹照着里面的说明书干活。对于用户来说这就像是给AI装了一个肌肉记忆。1.2 从人工编排到按需加载的转变我早期做自动化方案时喜欢把所有环节写死先做A再做B最后做C。这种工作流的好处是稳定坏处是脆弱稍微换一个输入场景全流程就要重写。技能包改变的是控制方式——它把流程定义权交还给模型模型根据用户的真实意图自己觉得现在该用周报技能了于是调用它。这就带来一个很实际的优势技能是可以按场景叠加的。我有大概二十个技能同时挂在智能体上但它不会每次全部执行一遍只会在遇到匹配场景时加载其中一两个。这比过去一个巨大无比的系统提示词要清爽得多也让每次调用的上下文窗口占用小了很多。我在这段时间里反复调整的就是描述description怎么写。描述决定这个技能什么时候被触发、什么时候不该被触发。后面我会专门细讲这部分它看起来不起眼实际上决定整个技能库是顺手还是添乱。1.3 技能和工作流、插件、MCP 工具的关系这里顺便说清楚几个概念因为它们经常被放在一起讨论。我的理解是工作流Workflow强调固定顺序像工厂流水线技能Skills强调按需调用像工具箱里的一把专用扳手插件Plugins通常指带UI或主动干预能力的扩展而MCP工具则是一种标准化的工具接入协议让AI可以调用外部系统的具体能力。它们不是互斥的。我现在的做法是把MCP工具当成手执行具体操作把技能包当成操作手册告诉AI什么时候用什么手、怎么用。技能包里可以引用外部工具也可以直接内置脚本。真正复杂的大任务我会在工作流里编排多个技能让它们按阶段出现。这样组合起来既保留了大流程的确定性又保留了技能点的灵活性。2. 技能包的标准结构我给每个技能定的最小目录很多教程讲技能时喜欢堆功能实际上技能包的核心不是代码多炫而是信息组织是否清晰。我给自己定了一个最小目录规范任何新技能先按这个搭出来再考虑要不要加料。2.1 SKILL.md 的元信息与正文怎么写SKILL.md 是一个技能包的入口文件它的质量直接决定了AI会不会在关键时刻想起这个技能。我用的结构分两块头部元信息和正文说明。头部元信息是目前主流做法中的通用约定通常叫 YAML frontmatter。它最重要的是两个字段name技能名称和 description技能描述。--- name: weekly_report description: 生成周报适用于用户提供本周工作内容、需要汇总为结构化周报或询问本周工作总结时。不适用于日报、月度总结也不适合处理财务明细数据。 ---这个 description 我写了三句话第一句点明触发场景第二句给出示例意图第三句明确边界什么情况不要用。别小看不适用这三个字它是我调试技能时收获最大的改进——有边界说明之后误触发率直线下降。正文部分我习惯按五个小节来写目的、输入要求、执行步骤、输出格式、注意事项。以前我也写过非常长的正文后来发现太长的步骤描述会让模型执行变形。现在的原则是步骤宁可少而稳不要多而乱通常控制在三到六步。2.2 配套脚本和模板文件什么时候必须拆出去很多新手写技能恨不得把所有内容都堆进 SKILL.md包括冗长的计算逻辑、表格数据、判断规则。这种做法会让 SKILL.md 变得非常臃肿而且模型在读取时也容易把注意力放在细节上反而忽略了执行主逻辑。我的经验是三个判断标准凡是需要精确计算、日期处理、数据校验的一律写脚本文件。模型做算术不可靠但Python非常可靠。凡是超过二十行的固定模板一律放 templates 目录。SKILL.md 里只写使用 templates/xxx.md。凡是帮助模型理解格式的样例一律放 examples 目录。一个优秀样例顶得上十句抽象描述。脚本和资源拆出去还有一个额外好处技能包可以被版本管理。我可以用 Git 追踪每次改动哪天技能坏了回滚很方便。2.3 我的技能包目录模板我目前创建新技能时会直接复制这个模板skill-name/ ├── SKILL.md ├── scripts/ │ └── main.py ├── templates/ │ └── output-template.md └── examples/ └── sample-input-output.md如果技能很简单只有 SKILL.md 也是允许的但至少要保持一个原则技能目录里每个文件都不是摆设。我见过有些技能包放了三个脚本实际只用到其中一个剩下两个纯属干扰。AI在读技能的时候会把资源文件都看一遍多余的资源等于在上下文里放了一堆噪音会影响判断。简单技能不配脚本复杂技能才配。这个度需要自己掌控我通常问自己一个问题这个技能如果让AI纯靠生成文本能不能稳定输出正确结果如果不能那就必须上脚本。3. 手把手写一个可落地的技能包月度经营简报生成光说不练没有用。我拿一个真实做过的技能举例子——月度经营简报生成。这是个非常适合做技能包的场景因为它有固定模板、有数据计算、有格式约束而且每月都要用一次复用的价值非常明显。3.1 需求拆解为什么选这个场景我当时的痛点很直白每个月末我要把一份原始经营数据表几十行Excel变成一张管理层能直接看的简报内容包括收入、毛利、订单量、环比变化、Top3客户、风险事项。以前的做法是手动抄数据然后在AI对话框里粘贴模板让它生成。问题是每次粘贴的原始数据格式都可能变模板里的判断规则也不固定导致每月都要花半小时重写提示词。技能包解决的就是这个半固定问题步骤固定但输入数据灵活。我把所有可变部分拆出来交给脚本处理所有固定框架放进 SKILL.md 和模板文件。3.2 SKILL.md 完整示范来看这个技能的核心文件--- name: monthly_summary description: 生成月度经营简报适用于用户提供月度销售/经营数据表并要求整理成管理层简报或询问这个月业绩怎么样时自动汇总关键指标并输出结构化简报。不适用于查看明细流水、做财务报表核算也不适用于跨多个年份的长期趋势分析。 --- # 月度经营简报 ## 目标 将月度经营数据整理成一份管理层可直接阅读的简报。 ## 输入要求 - 数据文件CSV 或 Excel包含字段月份、客户名称、订单金额、订单数量、毛利。 - 如果用户只给了目录路径先用 scripts/scan_data.py 查找文件再读取。 ## 执行步骤 1. 用 scripts/read_data.py 读取并清洗数据输出标准化 JSON。 2. 用 scripts/calc_metrics.py 计算指标总收入、总订单数、总毛利、环比变化率、Top3 客户。 3. 读取 templates/briefing_template.md。 4. 将计算结果按模板填充生成简报。 5. 在简报末尾列出风险提示建议包括环比下滑超过 10% 的指标、头部客户集中度过高等。 ## 输出格式 - 必须输出 Markdown 格式。 - 每个指标必须附带数值和历史对比。 - 风险提示使用引用块展示。 ## 注意事项 - 不要编造模板中不存在的指标。 - 如果原始数据里缺少必要字段直接说明缺失项不要强行生成。 - 金额统一按万元保留两位小数。这份 SKILL.md 的亮点在于执行步骤是很明确的AI 不需要思考下一步是什么照着做就行。脚本先把数据清洗成标准格式模型再负责生成说明文字人机分工就到位了。3.3 配套脚本把原始数据变简报脚本部分我写了两个文件。第一个负责读取和清洗import pandas as pd import sys, json def load_data(path: str): if path.endswith(.csv): df pd.read_csv(path) else: df pd.read_excel(path) df.columns [c.strip().lower() for c in df.columns] required [月份, 客户名称, 订单金额, 订单数量, 毛利] missing [c for c in required if c not in df.columns] if missing: raise ValueError(f缺少必要字段: {missing}) return df if __name__ __main__: input_path sys.argv[1] df load_data(input_path) df.to_json(sys.stdout, orientrecords, force_asciiFalse)第二个负责指标计算import sys, json def calc(data): total_revenue sum(float(r[订单金额]) for r in data) total_profit sum(float(r[毛利]) for r in data) total_orders sum(int(r[订单数量]) for r in data) # 简单环比假设按月份升序排列取最后两个月份 months {r[月份] for r in data} sorted_months sorted(months) if len(sorted_months) 2: last, prev sorted_months[-1], sorted_months[-2] last_rev sum(float(r[订单金额]) for r in data if r[月份] last) prev_rev sum(float(r[订单金额]) for r in data if r[月份] prev) mom_change (last_rev - prev_rev) / prev_rev if prev_rev else None else: mom_change None # Top3 客户 customer_rev {} for r in data: customer_rev[r[客户名称]] customer_rev.get(r[客户名称], 0) float(r[订单金额]) top3 sorted(customer_rev.items(), keylambda x: x[1], reverseTrue)[:3] return { total_revenue: total_revenue, total_profit: total_profit, total_orders: total_orders, mom_change: mom_change, top3_customers: [{name: c, revenue: v} for c, v in top3], customer_count: len(customer_rev) } if __name__ __main__: data json.load(sys.stdin) result calc(data) print(json.dumps(result, ensure_asciiFalse, indent2))脚本的好处是计算过程完全可复现模型不需要自己心算也不会因为数据太大而把数字算错。我在 SKILL.md 里特意让 AI 先调用脚本再把 JSON 结果填充进模板这个顺序不能乱。模板文件长这样## 本月经营简报 - 总收入{{ total_revenue }} 万元 - 总毛利{{ total_profit }} 万元 - 订单总数{{ total_orders }} 单 - 收入环比变化{{ mom_change }}% - 活跃客户数{{ customer_count }} 家 ### Top3 客户 {{ top3_customers_table }} ### 风险提示 {{ risk_notes }}3.4 测试技能在客户端里跑通一次技能文件写完不等于能用我每次都会做一次全流程测试。测试方法很笨但很有效用一个干净的对话窗口只发一句模糊需求比如把上个月的经营数据整理成简报给我。第一次跑的时候AI 没有自动找到数据文件因为它不知道数据存在哪个目录。我后来在 SKILL.md 的输入要求里加了一句如果用户只给了目录路径先用 scripts/scan_data.py 查找文件再读取。 这样它就知道了。第二次跑的时候AI 倒是找到了文件但把环比变化写成了绝对值没有转成百分比。我检查后发现是模板里没有明确单位于是在注意事项里补了一句环比变化用百分比表示保留两位小数。 这种边测边改的过程我前后大概调整了三轮才稳定。4. 描述词决定生死关于触发、路由与边界的设计技能包能不能被正确使用百分之六十的功劳要记在 description 上。你可能会疑惑不就是一段描述吗怎么会有这么大影响原因是在大部分智能体架构里模型是通过把所有技能的 description 拼在一起做一次内部路由判断来决定该用哪个技能。description 写得好等于给路由器画了一张清晰的地图。4.1 为什么AI会找不到或乱用技能我遇到过一个特别典型的反面案例。当时我建了一个合同审查技能description 写的是处理合同审查相关事务。结果用户每次提到合同哪怕只是问合同要不要盖章AI也会触发这个技能然后输出一整段审查流程完全答非所问。问题就出在描述太宽泛。处理合同审查相关事务没有给出判断标准AI不知道哪些情况算审查、哪些情况不算。我后来改成具体场景对甲方/乙方提供的合同文本进行风险审查识别违约责任、付款条件、保密条款等方面的风险并给出修改建议。不适用于合同盖章流程、合同存档、邮寄等行政事项。改完之后误触发的情况少了很多。这说明 description 不只是在描述功能更是在给模型划定触发边界。4.2 写有效description的几条实测准则如果你也想把自己技能包的描述写好我建议遵循这几条我自己摸索出来的准则第一用当用户……时使用句式写触发条件而不是只堆功能名词。比如当用户提到周报、工作总结、本周回顾时比单纯写生成周报要清晰得多。第二至少写一句不适用场景。描述里要有不适用于……的说明。这相当于给路由逻辑加了负向过滤能显著减少AI的过度触发。第三把同领域的多个技能做差异化描述。比如我有日报生成和周报生成两个技能我会在周报的描述里特意写适用于跨一周的汇总不适用于单日记录在日报里写相反的话。没有这种互相排斥的校准模型很容易选错。第四描述不要太长控制在三到五句。太长的话模型在路由时反而抓不住重点。我把篇幅限制看成一条电梯简介——只讲最关键的触发场景和边界细节全部放在 SKILL.md 正文里。4.3 多技能共存时的冲突消解当技能数量变多冲突就不可避免。我现在的技能库里光是和文档处理相关的就有四五个技能包括 Markdown 转 Word、Word 转 PDF、Excel 清洗、文档格式统一。它们本身功能不重叠但描述里如果都用文档处理开头模型就会开始犯迷糊。我的做法是给每个技能加场景锚点。比如 Excel 清洗的描述里写适用于表格内容混乱、格式不统一、存在合并单元格或空行的情况而格式统一的描述里写适用于已经结构清晰但样式不统一的多个文档。这样即使功能相近模型也能根据当前面对的原始数据状态做判断。还有一种冲突是技能名太像。我踩过的坑是同时建了 report_gen 和 report_generator名字视觉上几乎一样描述也没做区分结果模型经常随机选一个。后来我统一了命名规范动词对象全部小写加下划线比如 generate_weekly_report。命名一致之后路由稳定了不少。5. 我踩过的坑技能库从10个涨到50个之后技能少的时候怎么用都顺手但当你攒了四五十个技能问题就出来了。这一节我把自己踩过的坑梳理一遍每个都有症状、排查过程和修法希望对正走到这一步的人有用。5.1 症状一技能被反复触发但不干活有一个阶段我发现会议纪要整理这个技能经常被触发对话框里明明能看到它加载了但最后输出的结果却和普通回答差不多完全没有走技能里的模板。排查过程是这样的我先去看它触发后的执行日志发现技能加载了 templates/meeting_notes_template.md但在生成时没有读取模板内容。再翻开 SKILL.md 一看里面只写了请使用会议纪要模板却没有说明模板文件的具体读取方式。问题就出在指令不等于行为。模型知道有模板但 SKILL.md 的文本没有把它放在执行的必经路径上。我修复的方法是把执行步骤改写成明确指令用 python 读取 templates/meeting_notes_template.md 文件内容严格按文件中的章节结构填充。 加上了读取文件这个动作它才真正去读。这个教训是技能正文里每一步都必须是模型能直接执行的动作而不是模糊的目标描述。5.2 症状二浅层技能覆盖了深度技能技能一多模型总是倾向于选那个描述看起来最相关的但实际效果最浅。我遇到过一次我做了经营分析这个深度技能里面包含多维度指标计算和归因逻辑同时又建了一个简单的数据概览技能只是把表里的数罗列出来。结果用户的提问明明需要深度分析模型却触发了数据概览。复盘后我发现数据概览的 description 里写了分析数据、展示主要指标几乎覆盖了深度技能的触发词。然后经营分析的描述反而写得太窄进行同比环比分析和归因拆解。解决办法是我给浅层技能加了边界仅用于快速浏览数据不做指标计算、不做归因分析如果用户要求解释原因或给出建议请改用经营分析技能。 同时在深度技能的描述里补了一句当用户需要知道数字背后的原因、业务趋势或改进建议时必须使用本技能。 这就把浅层覆盖深层的问题给解决了。5.3 症状三技能包里的脚本跑不起来脚本是技能包里最容易出问题的部分。我做过一个技能SKILL.md 写得挺完整但脚本在指定环境下怎么都跑不起来。后来排查发现是脚本里用了 pandas而运行环境没有安装这个依赖。这类问题隐蔽性很强因为你在自己电脑上测试时一切正常但换一个环境就崩了。我现在会在每个带脚本的技能包里放一个 requirements.txt并在 SKILL.md 里加上一句执行前检查依赖如果缺少 pandas先执行 pip install -r requirements.txt。 这样 AI 在运行时就能先处理环境问题。还有一个容易踩的是路径问题。早年间我把技能脚本里的路径写成绝对路径比如 /Users/me/skills/xxx换机器后直接失效。现在我统一在 SKILL.md 里约定所有脚本相对技能根目录运行并用传入参数指定文件路径不让脚本体内出现硬编码路径。5.4 技能更新的版本管理一个轻量做法技能多了之后改一个旧技能要特别小心因为你不知道它会不会影响其他技能。我现在用一套很轻量的版本方法每个技能目录里放一个 CHANGELOG.md记录改动时间和原因同时在 SKILL.md 里加一个version: 1.0.2字段。更新时我先在版本号上做加法等到确认稳定后再让 AI 调用新版本。这个方案不需要复杂的工具链只要坚持记录就能避免昨天还能用今天突然不行了的尴尬。我的经验是技能包本身也是一种代码凡是代码就得有版本意识。6. 技能库的个人演进路线写了那么多技能之后我认真复盘过自己做技能包的进化路线大致经历三个阶段。第一阶段是把高频提示词直接存成文本文件用时再复制粘贴这其实只是草稿。第二阶段是给这些文本配上结构化 SKILL.md 和资源文件变成了真正可被AI调用的技能。第三阶段是开始考虑技能之间的组合关系比如数据清洗和周报生成搭配使用前者把原始数据整理好后者再把数据变成报告。现在我的新技能诞生流程也固定下来了先观察自己在一周里哪些问题反复问AI、哪些任务重复做把它们记录下来然后挑重复频率最高的三件事做成技能用两周时间在实际场景里测试并迭代稳定之后才能进入正式技能库。这个过程看起来慢但比一次性堆几十个技能要靠谱得多。如果你也在搭自己的技能库我最后建议你关注一个细节技能的命名和描述写成什么样决定了半年后你还认不认识它。我常常回看旧技能如果光看描述完全想不起来当初为什么要建它那就说明这个技能的需求并不真实该删就删。技能库和衣柜一样定期清理比不断增加更重要。