跟大模型 Agent 打交道的时间越长我越觉得临场写 Prompt是一种靠不住的交付方式。上周让同一个模型整理一个中大型代码仓库连续跑了三次三次生成的目录结构和模块说明风格都不一样第四次才勉强对味。与其每次靠碰运气不如把这件事应该怎么做的完整流程、检查项、产出模板甚至配套脚本全部打包成一个结构化的技能文件放进 Agent 的技能库里用到时自动加载、按固定流程执行。这就是 Skills 的出发点。这篇文章不打算复述官方文档。我会以一个常年搭 AI Agent 工作流、踩过各种坑的开发者身份把 Skills 从概念到落地讲透它到底解决什么问题、和 Tools 差在哪、一份 SKILL.md 该怎么组织、怎么从零做一个真能用的技能包以及我在技能设计、调试、维护过程中积累的真实经验教训。适合那些已经让大模型做过自动化任务但总觉得输出不可控、流程不可复现想把能力真正沉淀下来的同学。1. 从 Prompt 到 SkillsAgent 能力扩展的范式转变1.1 为什么临场写 Prompt 成不了能力动笔之前先聊一个扎心的问题你不是已经把流程写进系统提示词了吗为什么模型还是不稳定我自己做过实验一段包含 8 步操作流程、3 条禁止事项、1 个输出模板的系统提示词单次执行时效果不错但放在对话轮次多、上下文长了以后模型对流程的遵循率明显下降。原因不复杂大模型对长指令的注意力不是均匀分布的越靠后的步骤越容易被忽略而且当上下文里塞了用户消息、工具返回、中间输出之后最初那几行流程指令的权重会被持续稀释。换句话说Prompt 适合表达当下这一次怎么做不适合表达这一类任务永远怎么做。后者需要一种更结构化的承载方式。你可以把 Prompt 理解成口头交代Skills 更像是把口头交代变成了带图纸、带模具、带质检标准的流水线。同样一句话口头说三遍和三份规范文件跑三遍稳定性完全不在一个量级。1.2 Skills 是什么一次把能力变成文件Skills 的直观形态是一个按约定组织的目录里面放一份描述文件约定俗成叫 SKILL.md、若干配套脚本、模板和参考资料。模型在对话中会根据用户任务和每个 Skill 的元信息决定是否需要加载这个技能加载后按部就班执行。它和系统提示词、SOP 的本质区别在于提示词是文本脚本是逻辑。纯文本靠模型的注意力去理解脚本靠解释器去执行。真正确定性强的环节比如列出目录树过滤忽略文件统计函数数量交给脚本模型把精力集中在理解需求、编排步骤、组织输出上。这个组合解决了两件事一是把重复劳动变成可复用资产二是把模型的自由发挥空间压缩到合理范围。你不需要也不可能让模型每一步都按你的想法走但你可以通过技能文件把关键路径固定下来剩下的细节才让它发挥。1.3 Skills 和 Tools 的关系零件 vs 图纸很多人刚接触时会混淆 Skills 和 Tools在不少平台里叫 Function Calling、MCP、插件。我的理解是Tools 是原子操作Skills 是流程编排实际落地时两者经常嵌套。举个例子一个编辑文档的 Tool 可以读取文件写入文件但把仓库里的所有 TODO 标记汇总成一份风险报告这件事需要 读文件 - 穿行仓库 - 识别 TODO - 分类汇总 - 按模板输出 五六个动作单靠一个 Tool 做不了得把它编排成 Skill。如果说 Tools 是乐高零件Skills 就是拼装图纸。图纸的价值不在零件本身而在它把经验固化成了次序。这也是为什么 Skills 往往比单个 Tool 更能代表某个人的做事方法——你可以在不同 Agent 平台间迁移自己的技能库但不一定能同样轻松迁移底层的 Tool 实现。2. 剖析一份 Skill 的标准结构SKILL.md 的语义与分工2.1 一个技能包的目录布局下面是我比较习惯的技能包布局不一定需要严格遵守但建议保持统一方便自己维护也方便模型识别repo-overview/ ├── SKILL.md # 技能说明书模型主要读取这份文件 ├── scripts/ │ └── scan_repo.py # 确定性脚本数据收集、格式转换 ├── templates/ │ └── overview_template.md # 输出模板限定最终产出形态 └── examples/ └── output_sample.md # 示例输出给模型一个正确长什么样的参照templates 和 examples 的区别要注意模板是可以被填写的空结构示例是已经填好的结果。前者约束格式后者校准语感。对输出风格要求高的任务两者都需要如果只是内部处理不需要生成报告可以只留模板示例都可以省掉。2.2 SKILL.md 的四个核心段落我见过的 SKILL.md 结构五花八门但最终沉淀下来信息基本围绕四件事元信息、触发条件、执行步骤、硬性规则。元信息里最关键的是 name 和 description。name 是技能包的标识description 是模型判断该不该加载这个技能的依据。我的经验是description 要写得像一段任务宣言而不是关键词标签。尽量描述任务场景和用户意图而不是堆名词。执行步骤要写到模型不会做错的程度。不能只写分析仓库要写先读取根目录文件清单再运行 scripts/scan_repo.py 并传入仓库路径根据脚本输出中的 top_level 字段判断项目入口最后使用 templates/overview_template.md 渲染结果。模型需要的不是方向而是检查点。一个简化版的 SKILL.md 长这样你可以感受下密度--- name: repo-overview description: 当用户请求分析一个本地代码仓库并生成结构化概览文档时使用。也适用于这个项目是做什么的帮我看看仓库结构等表述。 --- # Repo Overview ## 使用时机 - 用户想了解本地仓库的整体结构和职责。 - 用户请求生成 README 风格的项目概览。 - 不用于代码内容问答、不用于在线仓库操作。 ## 执行流程 1. 先列出仓库根目录的文件查找 README、依赖清单等入口信息。 2. 运行 python scripts/scan_repo.py repo_path读取 JSON 输出。 3. 结合 README 和脚本输出识别技术栈、入口文件、核心模块。 4. 使用 templates/overview_template.md 渲染最终结果。 ## 硬性规则 - 禁止输出绝对路径一律使用仓库相对路径。 - 禁止将 .git、node_modules 等目录纳入结构和统计。 - 脚本异常时必须如实报告错误信息不得自行猜测结果。2.3 硬性规则把最容易错的写死在前面很多 Skill 最终翻车往往不是因为不知道怎么做而是踩了零散的坑。硬性规则段就是专门用来收纳这些坑的。我会把每一类已知错误浓缩成一句禁止或必须写进去。比如禁止输出绝对路径禁止将 .git 目录加入统计当脚本异常时不要猜测必须如实报告输出内容。模型对规则的遵循跟规则条目数量和措辞直接相关一条一条列清楚别用一大段散文混在一起。提示SKILL.md 是给模型看的代码。它应当严整、简短、可穷举而不是一篇洋洋洒洒的散文。每一条规则都要能通过自动化检查来验证写进去前先问问自己这句话能不能用脚本判断模型是否遵守3. 手把手把代码仓库梳理做成一个可用 Skill3.1 先把要做的事拆成确定动作搭建任何技能之前我习惯先写伪流程再写代码。仓库梳理的伪流程是检查根目录找到 README、配置文件、包管理文件。运行扫描脚本拿到过滤后的目录树和文件统计。识别入口文件main、cli、init.py、index.js 等。按模板输出项目简介、技术栈、目录结构、入口说明、扩展建议。第 2 步是确定性工作必须用脚本第 1、3、4 步留给模型判断但用规则和模板约束。这步拆解非常关键它决定了技能里哪些部分依赖模型智能哪些部分依赖代码逻辑。3.2 配套脚本为什么是兜底扫描脚本用 Python 写核心逻辑其实不复杂遍历目录、过滤常规噪声目录、返回相对路径列表。我在实现中有一个细节过滤逻辑不只判断路径后缀还要判断中间任意层级是否命中忽略目录否则.git子目录下的文件仍然会漏进来。核心实现大约是下面这样def scan_repo(root: Path) - dict: ignore_dirs {.git, node_modules, __pycache__, .venv, dist, build} ignore_files {.DS_Store, .pyc} tree [] for path in sorted(root.rglob(*)): if any(part in ignore_dirs for part in path.parts): continue if path.name in ignore_files: continue tree.append(str(path.relative_to(root))) return { top_level: [item for item in tree if / not in item], file_count: len(tree), tree: tree[:300], }脚本的返回值是 JSON模型只需要读取 JSON 再组织语言不需要自己去翻文件系统。这就把最容易出错的部分变成了确定性操作。我见过不少人试图让模型自己遍历目录最后无一例外会出现路径拼接错误、忽略目录漏过滤、输出顺序随机的问题。脚本兜底的第一原则就是凡是能编程实现的就别让模型自由发挥。3.3 用模板约束输出形态模板我写成一段带占位符的 Markdown模型只需要填空# {项目名称} 概览 - 技术栈{从依赖文件推断} - 入口文件{main_entry} ## 目录结构 {扫描树的关键目录部分} ## 主要模块 - module: {路径} — {职责说明}模板的意义在于模型不用每次发明输出格式它只需要填充内容。这能大幅降低不同会话之间的风格漂移。很多人觉得模板会限制模型的发挥但对于仓库梳理这种任务型输出稳定远比惊艳重要。如果哪天想让输出带更多洞察可以在模板里加一节风险和扩展建议而不是放开格式控制。3.4 一次真实调用后的效果观察搭建完成之后我拿一个实际项目试跑Agent 根据用户一句帮我看看这个仓库是干嘛的先加载 skill运行脚本再结合 README 生成概览。整体流程顺利但我也注意到一个有意思的现象模型对top_level字段的使用比我想象得更好它会自动把根目录下的package.json读进来做技术栈判断而对目录结构的展示它更倾向挑有业务含义的模块而不是平铺所有路径。这说明脚本负责数据、模型负责解释的分工方向是对的。只要你把数据喂干净模型的解释质量会明显改善。反过来如果扫描结果里混着一堆.git内部文件模型也会一本正经地把它们写进概览——脏数据进脏决策出这个规律在 Agent 场景下尤其明显。4. 设计 Skill 时的四个关键决策边界、依赖、权限与参数4.1 这件事值不值得做成 Skill不是所有任务都值得打进技能包。我判断的三条标准是否高频是否多步骤是否容易因为自由发挥而产出不一致如果一个任务一条 Prompt 就能说清楚或者它只做一次那做成 Skill 反而是负资产。等到某类任务开始频繁出现并且每次都要重新教模型同样的流程时才值得固化成技能。我见过一些人第一天接触 Skills 就雄心勃勃做了十几个技能两周后全废在维护上因为大部分技能根本轮不到用反而成了模型误触发的来源。4.2 技能包粒度按任务切不按模块切一个容易犯的错误是拿业务模块划分技能比如用户模块技能订单模块技能。模块的技能往往夹杂了查询、分析、格式化等多个任务模型难以判断该激活哪一种技能内部也可以用等于变相写了一个超长 Prompt。我的建议是按任务类型切summarize_user_profile、summarize_order_details、export_order_report。技能之间以任务为唯一维度职责单一。名称一眼能看出什么时候用副作用是数量会膨胀但维护成本反而低于大而全的技能。划分方式优点典型问题按业务模块符合人的直觉一个技能里塞了多个任务模型容易选错动作按任务类型职责单一触发精准技能数量偏多需要规范命名和索引按输出格式格式统一忽略任务差异容易陷入模板套模板的死循环4.3 控制运行依赖别让你的 Skill 变成环境杀手技能包里的脚本是要在用户环境跑的依赖越重越容易出问题。我踩过的典型场景一个数据整理技能依赖 pandas 和 openpyxl但用户的 Python 环境里没装模型直接报错卡在那里。后来我把脚本改成纯标准库实现几十行就搞定再也没有环境问题。编写技能脚本的原则能不用第三方库就不用必须用时在 SKILL.md 里标注运行前提并在脚本入口做依赖检测给出清晰的安装引导。依赖控制的本质是降低运行门槛你永远不知道用户会在什么样的 Python 版本、什么样的系统环境下加载你的技能。4.4 权限边界与危险操作这是很多人忽视的一点技能脚本能执行系统命令权限边界必须在设计阶段想清楚。我的做法是在 SKILL.md 里显式声明本技能不使用删除指令、不写入系统目录、不访问用户主目录之外的敏感区域同时脚本内部再做一层检查比如拒绝在脚本参数里出现系统目录之外的路径。安全设计不是摆设。一个 Agent 的技能越多越需要有可解释的权限模型。把权限声明写进技能文档既是给模型的约束也是给人看的审计信息。尤其在多人共享技能库的场景里每份技能都应该让人一眼看清它到底能碰哪些东西。5. 踩坑实录Skill 落地中我遇到的五类典型问题5.1 description 写得太宽泛模型疯狂误触发第一次做文档整理技能时我把 description 写成帮助用户分析和整理各种文档结果用户一句帮我把这两个文件合并了也触发了它模型加载了完全不合用的技能输出反而更差。改正思路把触发描述换成具体的场景和用户意图并补充仅当不用于的信号。我发现描述里加一句此为文档整理技能不用于内容生成和问答能显著降低误触发率。触发描述是你的技能第一道门禁写宽了模型乱闯写窄了该用时不用需要反复调到一个平衡点。5.2 脚本路径地狱模型永远找不到脚本早期版本里我在 SKILL.md 写的是运行 scripts/scan.py但 Agent 的工作目录往往不在技能包所在目录于是脚本就找不到。花了很久才定位到问题根源相对路径是以 Agent 当前工作目录为基准而不是以技能文件所在目录为基准。解决方案很朴素在脚本开头用自己的文件路径推导技能根目录再拼接数据路径。模型只需要调用绝对路径或者 SKILL.md 里明确先定位本文件所在目录再运行同目录下 scripts/scan.py。这个问题在个人项目里最多算摩擦在多人协作里就是严重的可用性缺陷——因为每个人的工作目录习惯完全不同。5.3 输出的示例污染了新一轮输入技能包里放了example_output.md之后出现了一个奇怪的问题模型有时会把示例内容当成真实数据直接输出。原因在于模型分不清这是给你看的范例和这是你要处理的数据。我的解决方式把示例文件放到examples/子目录并在 SKILL.md 里用一句话注明examples 目录下的文件仅供格式参考不得作为真实执行数据另外真实的输出统一写到输出目录和技能包的静态资产隔离。隔离原则能避免非常多隐含的上下文污染尤其是当你开始用技能生成内容并反复迭代时。5.4 步骤超过一定数量后遵循率明显下降我最早的一个技能写了 17 个步骤执行得很糟糕模型在步骤 6 之后就边界模糊。后来我把流程重构为主流程 子流程主流程只放核心检查点细节放进可选择的子步骤并用如发现 X 则转入 Y 子流程来组织。这和大模型处理长指令的原理是一致的保留主线分叉条件化。技能描述越扁平模型越容易迷失。如果你发现一个技能需要超过十个步骤几乎可以断定它的粒度出了问题需要拆成多个技能或引入子流程结构。5.5 失败案例没沉淀同样的错误反复出现我以为技能一旦写好就能一劳永逸直到发现同一个错误在这个星期出现了三次模型在读取 scan_repo.py 输出时忽略了 file_count 字段导致报告里没有总文件数。其实我第一次就发现了但我没把这条写进 SKILL.md 的规则里。从那以后我养成一个习惯每次技能执行质量不达标就把失败原因转译为一条新规则加入技能文档。技能的进化不该靠重写而应该靠失败驱动的增量修改。每一次跑偏都是免费的调试数据问题只在你想不想花三十秒把它变成一条对未来的约束。6. 从单技能到技能库版本管理、测试与演进6.1 目录组织的工程化技能数量超过十个之后无组织的散放会变成灾难。我会采用单一 skills 仓库每个技能一个子目录子目录内统一元信息格式。每个 Skills 目录本身也带一个索引文件写明技能名、职责、触发场景、维护者方便人找也方便模型快速浏览可选能力。命名规范我建议用 kebab-case描述用一句动词短语避免形容词堆砌。比如copy-move-file、extract-table-from-pdf。名称不仅要给人看它也常出现在模型触发的描述里。技能库的目录结构本质上是给人和模型共享的地图地图越清晰导航越省心。6.2 回归测试用样板任务验证技能质量不要相信模型这次跑对了就等于稳定。给每个技能配一个samples目录里面存放黄金用例输入 期望输出。每当技能改动后就拿这些样本跑一轮观察是否退化。更精确的做法是用脚本做快照对比把 Agent 输出转为规范化文本和上一版本对比差异过大就人工检查。这本质上把模型行为纳入了回归测试体系虽然没法做到 100% 确定性但它能帮你尽早发现由描述改动引起的输出漂移。我见过最难受的排障就是上周还能用这周怎么就不行了而回归测试几乎能直接定位到是哪次描述改动惹的祸。6.3 什么时候该重构一个技能重构信号有三个触发率低但命中后质量好说明大多数人不知道它什么时候用描述有问题触发率高但每次返回结果都需人工修说明流程没覆盖真实场景伪步骤太多技能之间频繁串门说明任务边界切错了。我的经验是技能库更像花圃而不是粮仓定期修剪比大干一场更重要。每季度把使用日志拉出来看看哪些技能被遗忘哪些技能被滥用再动手调整。别在大家用得好好的时候为了规范去重构重构的驱动力永远是使用数据而不是审美洁癖。最后说一点我自己这几轮做下来的体会。Skills 真正改变我的地方不是让 AI 变得更聪明而是让 AI 的工作结果变得可盘点了。以前我问模型你怎么得出这个结论的它只能给我编一段推理现在我会直接说把技能里第 2 步运行一下把脚本输出给我看逻辑链条一下打回确定性的地面上来。如果你刚开始接触这个概念别急着搭一个大而全的技能库先挑一个自己每周都会重复两三次的任务固化成技能跑一个月再回头看值不值。我相信你会感受到那种同一个问题再也不用解释第二遍的愉快。