技能工程化：从简历清单到可复用技能包的实战指南

我最近把自己简历上那一栏skills整个删掉了。别误会，不是觉得技能不重要，而是“技能”这个词在我这儿早换了含义。过去它代表你能写在简历上的关键词清单：Python、项目管理、数据分析、会开会、能写周报。现在它代表另一种东西——可以被调用、被复用、被验证的能力单元，我管它叫“技能包”。

如果你平时会拿智能体帮你处理重复性工作，或者想把团队里某个人“特别会做某件事”的经验固化下来，让其他人也能直接调用，这篇文章就是给你准备的。我会从为什么要把技能工程化、技能包的标准结构、描述怎么写得准、怎么调试、怎么做版本管理这五个层面，把我在实操里踩过的坑和沉淀下来的方法整个摊开。

1. 为什么我现在把 skills 当成“工程问题”来做

1.1 “技能清单”和“技能包”是两回事

先做个区分。你简历上的技能清单是“我具备哪些能力”的声明，它不要求可执行、可验证。老板看了你的简历，知道你“会 Python”，但你到底能用来干什么、代码习惯如何、能不能独立交付，他心里没底，你心里其实也没底。

技能包不一样。技能包是“某件事该怎么做的完整定义”，它必须包含四个部分：触发条件、执行步骤、边界约束、示例验证。有了这四样，一个完全没参与过这项工作的另一个人，或者一个智能体，都能照着这个定义把事做出来。

我举一个很日常的例子。团队里有个同事特别会做周报，他写出来的周报结构清晰、重点突出、风险写得明明白白。其他同事写周报就很痛苦，要么流水账，要么该暴露的风险不敢写。我一度试图让他把写法整理成一篇文档发在共享目录里，结果那篇文档除了他自己没人真正参考。为什么？因为文档是“给人看的说明书”，它不会在你动手写周报的时候自动出现，也不会提醒你“这一步你要注意别漏掉风险项”。

技能包解决的就是这个“关键时刻能否被调用”的问题。它把经验做成了可以挂在智能体身上的标准件，你只需要在对话里说“帮我写周报”，技能包就会被拉起来执行。

1.2 为什么文档和 Wiki 沉淀不住经验

我不是说写文档没用，我只是说文档在“经验复用”这件事上效率太低。

你想想，一份写得很好的内部文档，它的问题是：第一，它躺在共享目录里，被动等待阅读；第二，它没有明确的输入输出格式，每个读者理解出来的执行方式都不一样；第三，它无法被测试——你怎么判断一个人“学会”了这份文档的内容？没法判断。

技能包在一定程度上把文档“程序化”了。它规定了输入是什么、输出是什么、中间哪些步骤必须严格执行、哪些步骤可以自由发挥。这不是为了限制人，而是为了降低执行结果的不确定性。我在推进某团队的技能库建设时，一开始阻力很大，有人觉得这是在“把人的工作标准化”，像流水线。但实际做下来之后，大家发现恰恰相反：技能包解决的是最枯燥、最重复的那部分，真正需要判断和创造的部分反而被空出来了。

1.3 哪些技能值得做，哪些不值得

不是所有经验都值得做成技能包。我自己定了一个筛选标准，满足任意两条的才值得做。

• 重复频率高：每月至少要做一次，最好每周都在做。
• 步骤相对固定：不需要大量临场判断。
• 结果可以被检查：输出有相对明确的合格标准。
• 换人执行差异大：同样的输入，不同的人做出来质量差很多。

像“生成周报”“整理会议纪要”“给代码写单元测试”“把客户反馈归类成产品需求”都属于典型的好技能。而像“设计一个产品的商业化策略”这种极度依赖上下文和判断力的事，做成技能包的意义就不大——你当然可以把它的思考框架整理进技能里，但最终结果很大程度还是依赖调用者的能力。

2. 技能包的标准结构：目录、描述、脚本、示例

2.1 一个最小技能包的目录长什么样

先看一个我使用的标准目录。无论技能多简单，我都会保持这套骨架，因为只有结构统一，后面做批量管理、备份、复盘时才不会乱。

weekly-report/ ├── SKILL.md ├── scripts/ │ ├── parse_log.py │ └── render_markdown.py ├── assets/ │ └── template.md └── examples/ ├── input_demo.md └── output_demo.md

• SKILL.md：技能定义文件，所有元信息都在这里，是整个技能包的入口。
• scripts/：需要跑脚本时放这里，不需要可以没有。
• assets/：模板、参考文档、数据字典等静态资源。
• examples/：示例输入和对应输出，用来校验技能包是否按照预期工作。

很多人的第一个误区是：技能包就是一段提示词。不是的。提示词只是技能包的一部分。当你把技能包做得越来越大，你会发现脚本、模板、示例这些非文本资产往往比那段提示词更值钱。

2.2 SKILL.md 里到底要写什么

SKILL.md是智能体读取的核心文件，我会把它分成五个段落，顺序基本固定：

--- name: weekly-report-builder description: 根据工作日志生成结构化团队周报。适用于团队周会场景，输入为本周事项列表，输出为 Markdown 格式周报正文。 --- ## When to Use 当用户要求生成周报、写周报、汇总本周工作内容时使用。 ## Steps 1. 读取输入，将事项拆分为单条记录。 2. 按「本周完成」「进行中」「风险与阻塞」三栏归类。 3. 对风险与阻塞事项，必须补充影响范围和期望协助。 4. 使用 assets/template.md 中的模板渲染输出。 ## Constraints - 不虚构任何工作内容；未明确分类的事项放入「其他」。 - 每周报不超过 600 字。 - 如果输入内容无法归类，先询问用户，不要擅自判断。 ## Examples 见 examples/ 目录。

注意，我故意没有把描述写成一段长文章。“描述”承担的任务是让智能体在“看到一段文字时”判断该不该调用这个技能。它需要的是高识别度的关键词和触发条件描述，而不是一篇散文。

2.3 脚本和模板的作用

纯文本技能能覆盖的场景有限。比如上周我想做一个“会议纪要里程碑提取”的技能，会议的录音转写文本有几千字，里面散落着大量时间节点和负责人信息。如果全靠智能体在上下文里找，它容易漏，也容易把无关日期当成里程碑。

解决方案是写一个脚本先做粗筛。我用正则把包含“周”“月”“日”的时间表达式、包含“负责人”的段落先抽出来，生成一个中间文件，再让智能体基于这个中间文件做细分类。这样做的效果非常明显，漏召回率低了很多。

模板文件的作用则是保证输出格式稳定。我最开始做周报技能时没放模板，结果每次生成的周报结构都有细微差别，今天用表格，明天用列表。后来我直接把模板固化在assets/template.md里，要求技能必须基于模板渲染，问题立刻消失。

2.4 示例输入输出为什么不能省

示例是技能的“验收标准”。我自己在调试技能时最依赖的就是示例。

做法很简单：先准备一份真实的输入，比如某位同事脱敏后的工作记录；然后人工写一份你理想中的输出。把这一对文件放进examples/，每次修改技能描述或步骤后，都用这对文件跑一遍测试，对比智能体输出和人工金标的差异，就能直观地看到改得好不好。

没有示例的技能包是不可维护的。你今天改了一句话，怎么知道是改好了还是改坏了？凭感觉没用，拿示例跑一下立刻有结论。

3. 技能描述是核心中的核心：触发、上下文与边界

3.1 描述是“门牌号”，不是说明书

我在做第一批技能包时犯过一个典型错误：把描述写成了说明书。一个“代码审查技能”的描述我写了四百字，把审查规范、编码风格、安全注意事项全部堆了进去。结果智能体对该不该触发这个技能非常犹豫——因为它想起来太“重”了，模型在真正需要时反而不敢激活它。

后来我把描述压缩成三句话：

description: 当用户要求审查代码、找代码中的 bug 或安全隐患时使用。 工作方式：读取用户提供的代码，按规范输出问题列表、风险等级、修改建议。

短短几句话，触发判断立刻变清晰了。描述的功能是“门牌号”——让技能在合适的门口被认出来。至于进了门之后屋里怎么布置，那是 Steps 和 Constraints 的事。

3.2 触发条件怎么写才不容易误伤

误触发是技能最让人头疼的问题。我的“周报生成技能”曾经在一个用户聊产品方案时莫名其妙被调用，就是因为描述里写了“汇总本周工作内容”这句话，而用户在讨论产品规划时提到“这周要做的事”触发了匹配。

我现在写触发条件会坚持两条原则。

第一，用动作性更强的动词，少用模糊名词。“帮我把本周工作整理成周报”比“这周的工作内容”更明确。第二，在描述末尾加一句“不适用场景”。“当用户只是在讨论工作计划而非要求生成周报时，不要使用本技能。”这句负向约束能挡掉大部分误触发。

3.3 技能包内部的知识从哪来

很多时候技能需要外部知识支撑，比如团队的产品名词表、项目代号含义、历史决策记录。我经历过一个“用户反馈归类”技能，早期每次都把“支付失败”和“退款慢”混为一谈，因为技术侧没有告诉它这俩在后端体系里是不同的模块。

解决办法是在assets/下放一个数据字典文件，写明每个业务术语的定义和边界，并在 Steps 中强制要求“分类前先读取>