先说个我自己的真实经历。以前我让 AI 帮我写周报每次都得在对话框里把“本周做了什么、模板格式、别编数据”这些要求重新讲一遍讲完它还偶尔给我编一段本周根本没发生过的“重点成果”。后来我接触到了 Agent Skills也就是常说的技能包、skills这个概念把“怎么写周报”这件事从“每次口头交代”变成了“一个可以复用的技能文件夹”问题解决了一大半。这篇文章不准备讲一堆抽象理论而是把我从零理解、设计、调试、迭代 skills 的全过程记录下来包括踩过的坑和排查思路。内容创作者、开发者、知识工作者还有天天用 AI 干琐碎活的人都可以从中找到可以直接抄作业的部分。1. Skills 到底是什么从 prompt 模板到技能包的进化1.1 一句话理解 Skills 和它的位置先说个最简单的场景对比。你让 AI 帮你写一封项目周报如果是传统 prompt你会写一大段指令要包含哪几部分、语气怎么样、别写什么、最后用什么格式。这些指令模型能听懂但它记不住下次你还得重新写一遍。Skills 做的事情就是把这一整套“过程性知识”打包成一个文件夹里面放一份说明书SKILL.md可能还有模板和脚本。AI 每次遇到对应场景时会先去读这份说明书然后按照里面写的步骤来执行。用大白话说Prompt 是你给 AI 的“一句话交代”Skills 是你给 AI 的“SOP 工作手册”。这个区别在实战里非常关键。skills 不是让模型变得更聪明而是让模型“更懂你的工作流”。同一个模型加了技能包之后输出的稳定性、格式一致性、边界控制会明显提升。我后来把日志总结、会议纪要、代码审查、资料整理这些重复性工作全部改造成了 skills使用体验完全是两个档次。1.2 为什么 skills 突然成了热词很多人第一次听到这词是在 2025 年前后但它的底层逻辑其实不是新东西。真正让它火起来的原因我认为有这么几点。第一大模型的指令跟随能力上来了。以前你把一份 3000 字的工作手册塞给模型它执行到后半段可能就飘了。现在的模型能在长上下文里保持对规则的遵循所以“让模型按照手册办事”才变得可行。第二个人 AI 工作流开始重度复用。大家不再满足于“聊天问答”而是希望 AI 真能把自己每天的重复劳动接走。重复意味着需要标准化标准化就意味着要把流程固化下来这不是一句 prompt 能搞定的。第三生态起来了。社区里出现了大量 skills 仓库和分享清单很多人把自己的技能包开源出去大家互相 copy 再改改就能用。这种“共享工作流”的模式让技能包的传播成本变得极低。打个比方skills 就像游戏里的“宏命令”。你手搓一套连招可能需要五个步骤宏命令一键就放出来了而且绝对不会中间按错。技能包就是 AI 的连招表写好了稳定的重复就交给它。1.3 Skills、Prompt、MCP 的区别我经常被问到这玩意儿和 MCP 有什么区别和 Prompt 模板又有什么区别我建议用一张表来理解。形态主要解决什么典型场景最大特点Prompt 模板一次性指令复用写邮件、翻译、生成标题纯文本无副作用System Prompt设定长期角色和规则客服助手、指定风格回复常驻上下文改一次全局生效插件 / MCP接入外部工具和数据查数据库、调用 API、读文件偏“动手能力”解决连接问题Skills / 技能包固化流程和规范周报生成、会议纪要、代码审查按需加载说明书 可执行脚本Skills 和 MCP 不是替代关系而是协作关系。MCP 提供的是“手”可以帮模型操作外部系统Skills 提供的是“脑子和操作手册”告诉模型这套流程应该怎么做。比如一个会议纪要技能可以用 MCP 去读取会议录音转写文件然后按 SKILL.md 里的步骤整理成纪要两者配合非常顺。2. 解剖一个 Skill目录、说明书与脚本的分工2.1 标准目录结构长什么样一个 skill 本质上就是一个文件夹但社区里逐渐形成了一套约定俗成的目录结构。拿我最常用的“周报生成器”举例它的结构是这样的weekly-report/ ├─ SKILL.md ├─ assets/ │ ├─ report-template.md │ └─ bad-example.md └─ scripts/ └─ collect_metrics.py每个部分都有自己的职责。SKILL.md 是整个技能的入口和核心AI 在做任务之前会先读它。assets 目录用来放模板、参考文档、示例文件这些东西不一定每个任务都要读但需要时可以按说明书指示去取。scripts 目录放能够执行的实际脚本比如收集数据、生成图表、格式化文本这类机械化工作。我在实际使用中最大的体会是目录结构不是越复杂越好而是“说明书为主、脚本为辅”。一个文件夹里躺着 20 个文件AI 反而不知道先读哪个。简单清晰的层级配合写清楚的索引才能让它高效运转。2.2 SKILL.md 的 YAML frontmatter 和正文到底怎么写SKILL.md 是技能包的灵魂它分为两部分文件头部的 YAML frontmatter 和正文指令。YAML frontmatter 里最重要的两个字段是name和description。name是技能的名字方便检索description是 AI 判断“什么时候该用这个技能”的依据。这一点太重要了我后面会专门展开讲先记住一个结论description 写不好技能等于不存在。正文部分一般分为使用时机、执行步骤、输出格式、约束条件四个区块。不要写成“知识科普”要写成“操作流程”。比如写“模型在生成周报时应该保持客观”这是废话写“在输出前检查每一项数据是否来自用户输入若输入中未提及则标注‘待补充’”这才是有效指令。我强烈建议正文里给出一个最小可用的“输入-输出示例”甚至放一个反例。模型对示例的模仿能力很强给它看一段“错误示范”比写十条规则更管用。2.3 assets 和 scripts 什么时候才需要用到先说 assets。很多人做技能时会把模板、规则、样式全堆在 SKILL.md 里结果上下文被撑爆。我的做法是凡是超过半页纸的内容一律拆到 assets 里。SKILL.md 只写“按 assets/report-template.md 中的模板输出”这样每次对话占用的上下文很小模型执行效率反而更高。再说 scripts。我判断要不要写脚本就看一件事这个动作是不是需要确定性计算。比如我要从一堆日志里统计每个项目的耗时这种计算凭自然语言描述容易出错写成 Python 脚本最稳但如果是“用简洁的语言总结这段讨论”自然语言指令就够了写脚本纯属多余。还有一类场景特别适合脚本需要拉取外部数据。比如生成周报前要读取某个 JSON 文件、汇总 git 提交记录这类操作靠模型“手写”是不现实的必须由脚本代劳。一句话总结知识类内容放 assets计算和 IO 类操作放 scripts策略和规则放 SKILL.md。3. 手把手做一个周报生成器技能从需求拆解到可运行3.1 先做好需求拆解别急着写文件我见过太多人一上手就写 SKILL.md写完才发现技能根本不会被触发或者触发了但输出不达标。原因在于没做需求拆解。做技能包之前你至少要回答四个问题使用场景是什么输入是什么输出是什么边界在哪里。以周报为例场景是“用户每周写工作总结”输入可能是微信聊天记录、任务列表、项目日志输出是结构化 Markdown 文档边界是“只能使用用户提供的信息禁止编造和推测”。这里面最容易忽略的是边界。我一开始做技能时没写边界结果模型看到一个历史聊天记录里有“下个月要做 X”就替我写进本周周报搞得我每次都要手动改。边界写清楚后这个问题直接消失。另外一个容易出错的地方是 description。反面例子写“用于写周报的技能”太宽泛模型可能会在用户只想闲聊时误触发。正面例子要这么写当用户要求总结本周工作、生成周报、列出本周进展或者用户提供了工作日志、聊天记录、任务更新并要求整理成报告时使用本技能。关键词给得越具体触发越精准。3.2 设计目录和模板文件需求定完后我先建目录结构和模板。模板是给模型参照的“最终交付物长什么样”的样本一个好的模板能省掉 80% 的人工调整。我常用的周报模板是这样的# 本周工作汇报{日期范围} ## 一、重点项目进展 - {项目名称}{进展描述} ## 二、常规工作事项 - {事项}{状态} ## 三、下周计划 - {计划内容} ## 四、风险与阻塞 - 无 / {风险描述}模板里的占位符越明确越好。模型看到{日期范围}会比看到“根据本周信息”更清楚该填什么。我还喜欢在 assets 里放一个反例文件内容是一份满是“重大突破、显著增长、圆满达成”却没有任何事实支撑的假周报然后在 SKILL.md 里写“绝不输出此类风格”。3.3 SKILL.md 的完整实现我的周报生成器 SKILL.md 大体会长这样。注意它的段落设计前一段是触发条件中间是执行步骤后面是约束和检查清单。--- name: weekly-report description: 当用户要求生成周报、总结本周工作、整理每周进展时使用。输入是工作日志、聊天记录、任务列表或项目更新。输出是结构化 Markdown 周报。 --- # 周报生成流程 ## 使用时机 仅当用户要求生成周报、周总结或本周工作汇报时使用。日常闲聊、询问建议、其他文档生成不适用。 ## 执行步骤 1. 读取用户提供的全部输入内容识别与本周相关的事实。 2. 忽略输入中超过本周范围或与工作无关的部分。 3. 按 assets/report-template.md 中的结构组织输出。 4. 分类填充内容项目进展、常规事项、下周计划、风险阻塞。 5. 自检输出检查是否有事实、数据和观点超出输入范围。 ## 输出约束 - 只使用输入中明确出现的信息。 - 输入中未提及的信息一律标注“待补充”不得编造。 - 不使用“重大突破”“显著增长”等无事实支撑的空泛表述。 - 每条内容尽量包含可验证的时间、人物、项目名。写 SKILL.md 有一个关键经验步骤宁可多写两步不要合并成一两句模糊指令。模型需要的是“先做什么、再做什么”的序列而不是“好好总结”这种评价性要求。把“先扫描再筛选后组织最后自检”写清楚输出稳定性会有质的提升。3.4 调试过程第一次测试就翻车了技能写完后必须测试。我第一次测试输入的是几天的聊天记录当时就翻车了模型把一周之前的一条旧消息也写进了“本周进展”。排查过程是这样的我先怀疑是 description 写得太宽导致模型认为所有工作信息都可以进周报。但实际上问题出在 SKILL.md 正文的第二步——“忽略输入中超过本周范围的内容”这句话描述得太笼统模型不知道“超过本周”怎么判断。我改成“以输入中最晚的时间点为基准以该时间点所在自然周为范围该周之外的记录一律不采用”问题才解决。第二次翻车是模型自己编了一段“本周重点风险”但输入里根本没有相关记录。我以为是约束不够后来发现是模板里“风险与阻塞”是必填项模型为了输出完整结构就脑补了内容。解决办法是在模板里把那一项改成允许填“无”并在约束里加一句“若输入中没有风险信息明确写无”。测试完成后我还会留几个“测试样本”放在 assets/tests 目录下每次改完 SKILL.md 就重新跑一遍确认没有把之前的修复破坏掉。这套做法其实就是给技能做回归测试非常有用。4. 技能包的迭代与管理让 skill 从能用变成好用4.1 用版本管理和回归测试来迭代技能技能包写出来只是开始真正让它“好用”是靠一次次迭代磨出来的。我强烈建议把每个技能当作小型软件项目来管理。首先用 Git 管理技能目录。每次改动只动一个变量改完就提交commit message 写清楚“修改了什么、为什么改”。我早期的技能没有版本管理后来出问题时完全不知道是哪次改动导致的回退都不知道回退到哪特别被动。其次维护固定测试样本。我每个技能都保留 3 到 5 个真实输入样本改动后逐一跑一遍观察输出是否符合预期。如果某项改动让之前正常的输出变差了立刻回退。最后记录关键指标。我一般关注三个触发准确率就是该触发时触发、不该触发时不触发的比例指令遵循率就是输出结构和约束是否被遵守内容完整度就是关键字段是否都有。这三个指标看着简单但能客观反映出技能的质量变化。这里有一条经验得失不要急着加功能。一个技能一周都没被触发问题大概率不是缺功能而是 description 写得不到位。先把注意力放在“让 AI 知道什么时候用它”上比加一堆花哨步骤更有价值。4.2 如何构建一个可持续维护的个人技能库当技能数量超过 5 个之后管理成本就上来了。我目前的技能库管理方案是这样的。命名规范上统一用“领域-动作”的格式比如meeting-minutes、code-review、weekly-report。这样在文件列表里一眼就能看出用途也方便搜索。存放位置上个人通用技能放在统一目录下项目专属技能放在项目内。前者的例子是“简历修改建议”“邮件润色”后者的例子是“某某项目上线检查清单”。通用技能跨项目复用专属技能要绑定到项目上下文。同步和共享方面我用私有 Git 仓库同步多台设备和团队共享时用公开仓库。团队协作特别注意一点合入别人的技能前先审 description 和依赖否则很容易合并进来一个“永远不会触发”或者“乱触发”的技能。我还会定期做技能审计大概一季度一次。把没触发过的技能清理掉把 description 里的过时关键词更新掉把模板里的旧格式维护掉。技能库和代码库一样不维护就会慢慢腐化。5. 高频问题排查我踩过的五个坑和速查表5.1 我踩过的坑第一个坑description 写得太抽象。我曾经写过“用于助理日常工作”结果模型在所有闲聊场景都想触发。后来改成“当用户要求生成会议纪要、总结会议记录、列出会议决策和行动项时使用”触发立刻精准了。记住description 是给你要识别的“用户意图场景”用的不是给技能做自我介绍用的。第二个坑正文内容太多。早期我喜欢把所有规则都塞进 SKILL.md导致上下文被占满。后来把长模板、参考文档挪到 assets 里SKILL.md 只留核心步骤模型执行速度和准确度都提高了。上下文是非常珍贵的资源技能包要尽量“轻”。第三个坑脚本路径写错。我在脚本中使用相对路径读取资产文件结果切换工作目录后脚本找不到文件。解决方案是脚本里通过Path(__file__).resolve().parent这类方式定位技能目录再拼接相对路径而不是依赖当前工作目录。第四个坑危险操作没有加确认机制。有些技能会写文件、删除临时目录有一次差点把源目录里的旧文件覆盖了。现在凡是涉及删除、覆盖、移动文件的操作我都会在 SKILL.md 里强制要求模型“先列出将执行的操作清单经用户确认后再执行”或者干脆不在技能里做破坏性操作。第五个坑不维护版本。我以前改坏了技能只能重写后来统一用 Git 管理每个技能一个仓库改坏了能回退还能对比功能变化前后的差异省了很多事。5.2 高频问题排查速查表症状可能原因解决方案技能从不触发description 写得太窄或太宽用真实场景重写 description加入更多触发词技能乱触发description 中出现“日常、通用”等模糊词收紧触发场景加“仅当”限定输出结构总是偏离SKILL.md 中步骤过于笼统拆分步骤加示例和反例输出里出现编造内容约束条件没写死增加“只使用输入中出现的信息缺失标待补充”上下文总是不够用SKILL.md 正文太长把模板和长文档移到 assets脚本报找不到文件使用了相对路径改为基于脚本文件定位目录某次改动后技能变差没有版本管理用 Git 维护技能随时回退触发后回答很泛缺少执行步骤在 SKILL.md 中写“先做什么再做什么”这套速查表基本覆盖了初学者九成以上的问题。遇到技能不听话先跑一遍这张表大多能找到原因。我个人强烈建议新手不要一上来就做十个技能而是挑一个自己每天都会用的流程比如周报、会议纪要、日志整理把它打磨到位。等你把这个技能的迭代闭环跑通了后面的技能只是重复这个过程而已。最后再分享一个小技巧除了工作型技能我会把“怎么查资料”这种流程也固化成技能。比如遇到不熟悉的概念先让 AI 判断是否需要多源对比再按固定格式输出相关背景、当前进展、争议点。这种元工作流技能看起来不起眼实际用下来省的时间比业务技能还多。如果你也折腾过这类技能包有空可以多交流我这边还有不少翻车现场可以聊。