Skills 这个词最近在 AI 应用圈子里已经快被说烂了。各大 Agent 框架、助手产品都在推自己的 skill 格式社区里也冒出了不少 skill 仓库和共享目录。我前后花了几周时间从照葫芦画瓢抄别人的 skill到自己独立设计、写脚本、迭代验证把这套东西的来龙去脉摸了个大概。这篇就把我理解的 Skills 是什么、内部怎么组织、怎么写一个能真正用得上的 skill、以及我在实践里踩过的坑一次性聊透。适合正在折腾 AI 自动化流程、想把手头反复劳动固化成能力包的人也适合那些已经见过 skill 概念、但还没想清楚怎么下手的观望派。1. Skills 到底是什么以及它解决了我的什么痛点1.1 从 prompt 到 skill 的进化路径先说清楚一件事Skills 不是某个具体产品独有的功能它本质上是一种给 AI 预装能力的标准形态。一个 Skill 就是把一段高质量指令、配套的脚本和资源、以及触发它的说明打包在一起形成一个可以被 AI 按需调用的能力单元。类比一下prompt 像你临时找同事交代任务每次都要从头口述一遍而 skill 像公司的 SOP 手册平时放在架子上谁需要谁去翻翻完照着做就行。这个进化过程是有逻辑的。最早我们靠的是在对话里反复粘贴大段提示词它的痛点是不可复用、容易写长、多套指令混在一起还互相干扰。后来有了 system prompt相当于提前把入职手册发给 AI但 system prompt 一旦超过一定长度模型注意力会被稀释不同任务的需求挤在同一个上下文里彼此打架。Skills 换了个思路能力拆成独立文件AI 在遇到对应任务时才去读那本说明书。这种按需加载的设计让每个任务都能拿到最聚焦的上下文指令质量反而比大而全的 system prompt 更高。我用同一个模型做过对比把三套 skill 塞进 system prompt 的效果远不如拆成三个 skill 按需调用。1.2 它真正解决的三个现实问题第一个是上下文污染。以前把写代码、写文案、做总结的约束全塞在一起AI 回答技术问题时还带着文案风格的影子输出总是串味。拆成 skill 之后各自独立互不干扰。第二个是能力版本化。一段好的提示词经过迭代之后你到底改过几版、为什么改用文件管理之后清清楚楚。每个 skill 就是一个目录Git 历史就是完整的演进记录这比在聊天记录里翻旧版本靠谱太多。第三个是协作分工。团队里懂业务的人写指令会开发的人写配套脚本各管一段最后合并。我在实际项目中就试过这种分工模式业务同事负责梳理输出模板和注意事项我负责写数据采集脚本效率比一个人闷头搞高得多。2. 一个 Skill 的内部结构拆解2.1 标准目录长什么样一个标准的 skill 目录通常长这样my-skill/ ├── SKILL.md # 技能说明书核心文件 ├── scripts/ # 可选配套脚本 │ └── extract.py ├── assets/ # 可选参考模板、资源文件 │ └── template.md ├── requirements.txt # 可选脚本依赖清单 └── README.md # 可选给人类看的说明SKILL.md 是灵魂文件scripts 和 assets 是辅助。很多人以为 skill 就是写个 markdown 说明其实真正让它发挥威力的往往是配套的脚本——模型擅长理解和组织信息但不擅长精确执行命令、解析复杂文件、调用外部接口这些活就应该交给脚本。1.2 SKILL.md 的 frontmatter 怎么写才不会被误触发SKILL.md 通常由 YAML frontmatter 和正文指令两部分组成。frontmatter 里的name和description决定了 AI 什么时候该启用这个 skill这俩字段值得反复打磨。--- name: project_summarizer description: 当用户需要快速理解项目背景、进展和风险时将项目文档整理成决策者简报。 ---description 是触发判断的核心依据。我建议在描述里直接写上当用户请求涉及 XXX 时使用把触发条件焊死。写得太宽泛比如帮助用户处理文档那模型面对帮我改改这段话也会犹豫要不要调用结果就是该用的时候不用、不该用的时候乱用。2.3 指令正文的写作原则指令正文不是作文是可执行的约束。我踩过几次坑之后总结出几条原则用祈使句少用形容词。按四段式输出比输出要清晰有条理有效得多。给反例比给正例管用。明确写禁止输出空泛总结不要重复用户原文比单纯写要深刻更能约束模型。步骤要编号数量控制在五步以内。超过七八步的流程模型执行到后半段往往已经记不清前面的约束了。直接给输出模板。在指令里放一段参考格式模型照葫芦画瓢效果立竿见影。3. 实操过程从零写一个真正能用的 Skill3.1 场景怎么选第一只小白鼠别选大象第一次写 skill最忌讳选太宏大太抽象的命题。我建议选一个你每周至少做一次、每次都要花十分钟以上整理思路、但重复度极高的活儿。我自己的练习项目是周报生成器。为什么选周报它有固定字段、有固定风格、有历史数据可参考属于典型的高重复、低创造性、标准清晰任务。这种任务最容易出效果也最容易验证 skill 写得好不好——因为你心里本来就有明确的好的标准。3.2 完整实现SKILL.md、脚本和资源当时我做的目录结构weekly-report/ ├── SKILL.md ├── scripts/get_commits.py └── assets/report_template.mdSKILL.md 的核心指令部分长这样--- name: weekly_report description: 当用户说写周报、生成本周周报时根据 git 提交记录和本周笔记生成团队周报。 --- # 周报生成 ## 输入来源 1. 运行 scripts/get_commits.py 获取本周 git 提交记录。 2. 检查 docs/weekly_notes.md 是否存在存在则一并读取。 ## 输出结构 - 本周进展按模块归类列出关键变更。 - 数据与指标如有测试覆盖率、构建时长变化等单独列出。 - 风险与阻塞只列未解决事项。 - 下周计划不超过 3 条。 ## 约束 - 每条进展不超过 30 字保留关键动词和对象。 - 禁止出现优化了用户体验这种无信息量表述。 - 如果 git 数据为空明确告知用户本周无提交记录不得编造。配套脚本get_commits.py的核心逻辑非常简单调git log抓过去七天的提交格式化输出成纯文本。这一步的意义在于给模型喂真实数据让生成变成整理。模型最怕凭空编造有了真实素材输出的可靠性完全不一样。import subprocess import sys from datetime import datetime, timedelta def main(): since (datetime.now() - timedelta(days7)).strftime(%Y-%m-%d) print(f数据区间{since} 至今) try: result subprocess.run( [git, log, --since since, --prettyformat:%h %ad %s, --dateshort], capture_outputTrue, textTrue, checkTrue ) print(result.stdout or 本周无提交记录) except subprocess.CalledProcessError: print(错误无法读取 git 仓库请确认当前目录在仓库内。) sys.exit(1) if __name__ __main__: main()3.3 一个真实的迭代过程三个细节教训第一版写完我实际用了一周效果只能说及格真正的问题全在细节里。第一个教训是语言简洁这四个字害死人。我一开始在约束里写了语言简洁结果模型产出的内容干巴巴像电报体动词和对象都丢了。后来改成每条进展不超过 30 字但保留关键动词和对象情况立刻好转。第二个教训是数据区间标注。有一次模型把上周的数据当成这周的因为脚本输出里没有日期信息。我在脚本输出里加了数据区间2025-02-17 至 2025-02-23这样的头信息之后问题彻底消失。模型需要明确的时间锚点才能正确理解数据。第三个教训是关于触发时机。用户直接说写周报时 skill 能正确触发但如果用户先闲聊了几句再提周报部分情况下模型会忘记调用。我的处理是重写 description 里的触发条件同时在 SKILL.md 正文第一句写了只要用户提到周报相关需求立即使用本技能。加了这句显式指令之后遗忘率明显下降。这轮迭代让我意识到写 skill 和写代码没有本质区别第一版永远不是最终版坑都藏在细节里。必须真实使用、留数据、反推问题才能把 skill 打磨到能放心用的程度。4. 让 Skill 更强大的三个进阶技巧4.1 给 skill 配上真脚本而不是纯文本说明书纯文本指令的 skill 是说明书配上脚本的 skill 才是自动化工具。我设计 skill 脚本时遵循一个原则脚本只做取数和格式化两件事不做任何判断。判断留给模型执行留给脚本各司其职。比如周报 skill 里的 get_commits.py模型不需要知道怎么跑 git 命令它只需要拿到格式干净的文本素材。这里有一个容易被忽视的点脚本的输出格式要尽量对模型友好。纯文本就够不要输出 JSON 套 HTML 再包一层 markdown。模型解析越简单的格式越不容易出错。脚本本身的容错性也重要数据为空时明确打印本周无提交记录而不是抛异常让模型面对半截输出继续硬编。4.2 给 skill 写测试用例改起来才敢动手写 skill 不写测试跟写代码不写测试一样危险。我的方法很朴素准备三个固定测试用例每次改完 skill 都跑一遍。第一类是正常用例输入一份规范的完整数据验证输出是否符合要求。第二类是边界用例比如周报场景里本周没有任何 git 提交看模型会不会被逼着编数据。第三类是干扰用例输入里混入无关信息看模型能不能正确聚焦。这三类用例各自写成一段固定文本存成一个文档。每次改动 skill就把三个用例依次跑一遍跑挂了就修。这个习惯帮我挡住了好几次改了一个地方、坏了一个边缘场景的问题。尤其是边界用例它直接决定了你的 skill 在真实世界里会不会一本正经地胡说八道。4.3 控制 skill 之间的边界避免互相抢触发skill 数量多起来之后最大的噩梦不是某个 skill 写得不好而是多个 skill 互相抢触发。我自己就翻过一次车一个文档优化skill 和一个中英文翻译skilldescription 里都写了当用户给你一段文字时使用结果用户让翻译一句话模型先触发了文档优化把英文原文润色了一遍。根源就是描述写得太宽泛。解决办法是用排除法写触发条件。比如翻译 skill 的 description 里补上如果用户要求改写中文表达请交给文档优化技能处理本技能只处理跨语言转换。每个 skill 不仅要写清楚自己干什么还要写清楚自己不干什么、什么情况应该让位给别的 skill。这相当于给模型划边界线经过几轮补充之后误触发率大幅下降。5. 常见问题与排查技巧实录5.1 我的 skill 没有被触发从哪查起这是社区里最常见的求助帖我自己也遇到过。遇到这个问题的排查顺序我建议按下面走。先检查 description 是否足够精确。很多人写 description 时用的是帮助用户处理文档这种表述模型面对帮我改改这段话时根本判断不出来该不该用。改成当用户请求改写、润色、优化中文文档表述时使用触发率立刻上升。再检查语义匹配。模型是按语义匹配触发条件的不是按关键词。如果你的 description 写的是输出项目简报用户说这篇文章讲了啥这两者的语义距离很遥远自然触达不到。所以 description 里的用词要尽量贴近用户实际会说的表达方式。还有一种情况不是没触发而是触发了你却没看出来。我建议在 skill 的执行步骤第一步写上先向用户确认正在使用 xx 技能这样每次被触发都有迹可循排查时能直接排除到底有没有触发这个变量。5.2 我的 skill 被错误触发怎么压制反面问题常常更让人头疼。典型场景用户只是随口说帮我看看这段代码结果模型突然调用代码安全审计skill输出一大堆漏洞分析把简单问题复杂化。根因基本是 description 里没有写清什么情况下不要用。我在容易混淆的 skill 里统一加了这么一句只有当用户明确要求进行安全审查、权限检查、依赖风险评估时使用。 日常的代码解读、bug 排查不属于本技能范围。这相当于给模型划了一条边界线错误触发率明显下降。注意措辞要用只有当……时使用比单纯写用于安全审查更有约束力。5.3 skill 里的脚本跑不动多半是这三类原因脚本问题通常来自依赖没装、路径写死、权限不对这三项。我给 skill 里的所有脚本定了三条约定实测下来非常有用一律从当前工作目录读取输入输出打到 stdout不写临时文件到奇怪的位置。依赖能用标准库就不用第三方库实在需要第三方库必须写清楚 requirements.txt。脚本开头加set -eshell或捕获异常后sys.exit(1)Python避免模型拿到半截结果继续硬编。这些约定看着琐碎但在 AI 自动调用脚本的场景里任何一个不确定性都会被放大。脚本越无脑越好最好是不需要交互、不需要人工确认、一条命令从头跑到尾。6. 什么时候值得做 Skill什么时候单纯对话就够最后聊一个特别容易被忽视的问题不是所有任务都值得做成 skill。我见过有人把回复礼貌邮件也做成了 skill结果就是给模型套了一层绕来绕去的约束效果还不如直接对话。判断一个需求适不适合 skill我自己用三个问题过滤第一这件事你做的频率高不高一年两次的事不值得投入精力做 skill。第二流程是否稳定每次处理逻辑都变来变去的任务skill 里的约束很快就会过时维护成本远超收益。第三你有没有办法验证效果无法验证的东西写了也白写因为你根本不知道它什么时候是对的。真正值得做 skill 的是那些流程固定、你有明确方法论、且反复在做的事情。比如会议纪要整理、报销单初审、日志错误分类、代码提交信息生成这类任务做成 skill 之后等于把你的个人经验沉淀成了可复用的资产。我现在的习惯是先靠对话把流程跑顺连续三次都能得到满意结果才考虑把它固化成一个 skill。对话阶段是试错期skill 阶段是收割期顺序最好别搞反。我个人的体会是Skill 的价值不在于它多炫酷而在于它逼着你去梳理自己的工作方法。写一个 skill 的过程本质上就是回答三个问题我到底在做什么、我按照什么流程做、什么结果算做好。能把这三个问题回答清楚skill 想写不好都难。如果你还没试过建议就从你手头最烦的那个重复性任务开始花一个下午把它写成第一个 skill你会回来感谢自己的。