从提示词工程到Skills：为AI助手构建可复用的结构化技能包

我一直觉得，提示词工程玩到最后，瓶颈往往不是“写不出更好的提示词”，而是“提示词根本管不过来”。项目一多、场景一杂，你的超级长文 prompt 要么照顾不到细节，要么塞进上下文后把模型注意力冲散，效果时好时坏。最近半年，我在实际项目里逐步把重心从“堆提示词”转向了“建 skills”——也就是给 AI 助手搭建一套结构化的技能包。这也是我目前认为最能解决实际问题的方式。

什么是 skills？简单说，就是把某类任务的执行知识、步骤约束、判断标准、输出模板沉淀成一个独立单元，让 AI 助手按需加载、稳定复现。我试下来的最大感受是：它不会让模型变聪明，但能让模型每次都在“正确的轨道”上工作。这篇文章我拿来分享自己的完整落地路径，包括为什么这么设计、具体怎么建、怎么测、怎么维护，以及我在真实项目里踩过的坑。如果你是重度 AI 辅助开发者，或者正在帮团队设计一套可复用的 AI 工作流，这篇应该对你有用。

1. 为什么是“skills”而不是“更长的 prompt”

1.1 超长 Prompt 的失效边界

先聊一个现象。我见过不少朋友喜欢维护一份五千字的“万能提示词”，号称覆盖了角色设定、功能指令、代码规范、输出模板、禁止事项。刚写的时候效果惊艳，但随着项目演进，问题开始集中爆发：你会发现自己改一句话，模型对另一部分的理解就悄悄变了；或者明明写了“不要解释，直接给代码”，它还是喜欢先输出一大段分析。

这不是模型变笨了，而是超长指令天然存在几个难以克服的缺陷。

第一，指令稀释。模型对上下文不同位置的注意力并不均匀，核心规则埋在几百行中间时，权重会被大量补充说明挤压。第二，矛盾冲突。长 prompt 里很容易出现两段话在逻辑上互相打架，早期写的“详细说明背景”和后面补的“尽量简短”会同时生效。第三，不可复用。五千字的世界观设定和项目 A 强绑定，换到项目 B 时改三处还是五处？没人说得清。第四，没有验证机制。你没法为“五千字提示词”写自动化测试，改完只能靠肉眼观察一次输出，是变好还是变坏，完全看运气。

用大白话打个比方：给实习生发一本厚厚的《公司全流程手册》，不如让他按场景调用“报销流程卡”“客户接待卡”“会议纪要卡”三张标准作业卡。前者信息全，但用起来全靠临场判断；后者是结构化调用，既快又稳。skills 解决的就是这个“临场判断”带来的不确定性。

1.2 skill 是一种“结构化能力封装”

skills 和普通提示词的差异，不是“组织方式变了”，而是“使用机制变了”。普通提示词是每次对话时手动粘贴的一段文本，模型把它当成背景信息；而一条 skill 更像一个被索引过的接口——它自带名称、描述、适用条件和执行体，系统会在任务匹配时自动触发加载。

我理解中的技能包由四个部分组成：

• 元数据：声明这条 skill 叫什么、擅长什么、何时该用，这是“接口签名”。
• 指令文本：包含执行步骤、必守规则、决策逻辑，这是“方法主体”。
• 资源文件：存放模板、示例、专业资料，动态喂给模型，这是“资料库”。
• 测试集：用“输入样例 + 期望输出”的方式锁定行为，这是“质量卡口”。

四者合在一起，才叫一条完整的 skill。光有一个“角色提示词”只能算技能的第一步。

这种结构最大的好处，是把过去“模型自己决定怎么做”的问题，变成了“人先定义了正确做法，模型负责执行”。我不是在否定大模型的能力，而是把创造性留在了构建技能包阶段，把稳定性留给执行阶段。实测下来，用同一套 skill 跑二十次同类请求，输出格式和核心判断逻辑的差异明显缩小，几乎没有“这次忘写总结、下次多写一段解释”的随机波动。

1.3 适合做成 skill 的任务画像

也不是所有任务都值得封装成技能包。我自己的筛选标准一般看四个特征：重复性够不够高、变动是否低频、结果能不能客观验证、专业边界是否清晰。

我列了一份参考表格：

为什么这条边界很重要？因为技能包是有维护成本的。我见过有人把“帮我想一个活动口号”也做成了 skill，结果每次触发还要读一遍技能说明，效果不如直接说一句 prompt。技能包真正解决的是“专业任务执行的一致性”，不是“通用对话的便利性”。把有限精力花在重复出现的、有标准答案的任务上，ROI 才最高。

2. 拆开一条 skill，里面到底有什么

2.1 一个可落地的目录结构

先看一个我在项目中真实使用的目录结构。我习惯用一个文件夹把一条 skill 的内容归拢起来，让路径本身就成为“这个技能叫什么”的标识：

my-skill/ ├── SKILL.md ├── references/ │ ├── examples/ │ │ ├── good-output.md │ │ └── bad-output.md │ ├── templates/ │ │ └── report-template.md │ └── best-practices.md └── tests/ ├── case-01-input.md ├── case-01-expected.md └── compile-and-run.sh

看着有点复杂，其实拆开就三层。

最外层是SKILL.md，承担“说明书”的角色，告诉 AI 助手这个东西什么时候该用、怎么用、按什么顺序执行；references目录放的是模型执行时按需读取的素材，比如好例子、坏例子、可复用的模板，相当于给模型准备的参考手册；tests目录则是整个技能包的质量保障，用离线用例描述输入和期望输出，方便我改完技能后跑一遍验证。很多人忽略 tests，我觉得这恰恰是技能包和普通提示词最大的分水岭。

2.2 SKILL.md 的书写规范

SKILL.md是全包的入口，我建议至少包含四个部分：元信息、任务说明、执行步骤、输出要求。

一个简化的例子：

--- name: sql-performance-review description: 分析一条 SQL 的执行计划，定位潜在性能风险，输出优化建议。 when_to_use: 当用户提供 SQL 语句并要求进行性能评估或优化时。 license: MIT --- # SQL 性能审查助手 ## 输入要求 - 用户需提供 SQL 语句及所在数据库类型（MySQL / PostgreSQL / SQLite）。 ## 执行步骤 1. 识别 SQL 类型（SELECT / INSERT / UPDATE / DELETE）。 2. 检查是否包含 WHERE 条件、索引、JOIN、子查询等关键元素。 3. 基于数据库类型判断潜在性能瓶颈。 4. 输出结构化建议列表，每条包含风险等级和建议原因。 ## 规则 - 不执行任何真实 SQL，仅为用户提供分析建议。 - 如遇用户未提供数据库类型，默认按 MySQL 分析并显式说明。 ## 输出模板 ### 总览 - SQL 类型： - 主要风险： ### 风险清单 | 风险点 | 严重程度 | 优化建议 | 原因 |

注意这样一个细节：我写了when_to_use但没写“必须每次都用”，因为技能的触发应该由 AI 根据场景判断，而不是让它在所有对话里强行插入。description 要写得“窄而准”，不要出现“帮助你解决一切 SQL 问题”这种泛化描述。否则系统会把大量任务误路由进来，反而干扰正常对话。

2.3 常驻与按需：两种加载模式

实际操作中，我还发现加载模式的设计也会影响体验。目前我一般把技能分成两类：一类是“常驻技能”，一类是“按需技能”。

常驻技能消耗的是每次对话的上下文空间，所以只放最通用、体量小、使用频次高的技能，比如“输出格式化”“代码风格检查”这种每次都用得上的。按需技能则是占大头的内容，只有任务被匹配到时才临时加载，比如“安全审计”“性能诊断”这类重技能，平时不占上下文，被调用时才把完整指令读进来。

这个取舍很像电脑的内存和磁盘：常驻技能像内存，越小越好用；按需技能像磁盘，容量大也没关系，用到再加载。我见过有人把五六个重技能全部设置成常驻，结果一次对话的上下文预算被吃掉了三成，模型回答质量肉眼可见地下滑。所以我的原则是：能按需，就绝不常驻；能小而精，就绝不铺大。

3. 从零开发一条可用 skill 的完整流程

3.1 第一步：画清楚能力边界

做技能包之前，我会先写一段“能力边界说明”，明确三件事：这条技术要解决什么、明确不做什么、遇到边界情况怎么处理。

比如我做过一个“代码审查 skill”，当时的能力边界是这样定的：

• 要做的：检查逻辑错误、潜在 bug、异常处理缺失、可读性问题。
• 不做的：直接修改代码、执行测试、判断业务需求是否正确。
• 边界情况：遇到上下文不完整的代码，提醒用户提供更多的信息，而不是强行臆测。

这段边界说明后来帮我少踩了很多坑。因为模型在没有边界时容易“过度发挥”，比如用户说“帮我审查一下这段代码”，它就顺手把代码改好了。看起来是帮忙，实际上模糊了职责，容易造成误操作。边界写得越清晰，AI 的行为越克制，输出的可控性越强。

3.2 第二步：指令写作的金字塔结构

SKILL.md内部的执行指令，我的写法是分四层递进：目标、步骤、禁忌、模板。

• 目标：用一句话说明技能的唯一使命。
• 步骤：固定执行顺序，拆成 4～7 步，不能多到模型记不住。
• 禁忌：明确禁止的行为，比“要求做什么”更能约束输出。
• 模板：规定最终输出的结构和样式。

比如我之前调试过的一个技术写作技能，模板部分写的是：

## 输出模板 # 标题：一句话概括本次变更 ## 背景 （为什么会有这次变更） ## 变更内容 （列出主要变化，尽量分点） ## 影响范围 （影响哪些模块、服务或用户）

固定模板最大的价值，是让输出变成“填空题”而不是“创作题”。模型只需要在固定的框架里填内容，不必每次重新组织结构。我实测过，有模板的输出比没模板的内容质量稳定性要高很多，后处理成本也低。

3.3 第三步：建立可验证的测试集

技能包能不能“改不坏”，全看测试集够不够扎实。我给技能包搭测试集的方式很简单：准备若干组“输入样例”和“期望输出”，每组包含一个典型测试文件。

比如对于“SQL 审查”技能，我准备了三组典型 SQL——一个正常查询、一个缺少索引的查询、一个明显会做全表扫描的查询，再注明每组对应的核心期望点。改完技能后，我只要把三组输入依次丢进对话，观察每组是否命中预期，就能判断改动是朝好方向还是坏方向偏移。

如果项目的自动化水平更高，还可以把这套测试接入本项目常用的自动化流程：跑完输入样例后自动对比输出是否包含关键敏感词，再人工复核一次。我的原则是：先有“离线测试集+手工检查”，再谈自动化。大部分项目做不到全自动验证，但只要每个技能背后有可对照的样例，维护效率就已经好过纯改 prompt。

3.4 迭代节奏：像写单元测试一样更新技能包

开发模式我强推“测试先行”。我摸索出来的节奏是：

1. 拿到一个失败案例，先从输出反推是哪个指令导致的偏差。
2. 把该输入加入测试集，写清楚当前为什么不合格。
3. 修改SKILL.md或补充references里的资料。
4. 跑一遍全部测试集，确认本次改动没有破坏其他已有行为。
5. 新增“再运行几次不相关输入”做冒烟检查，防止技能被误触发。

这个循环和写单元测试的日常几乎一模一样，唯一不同的只是“断言”从代码变成了人工核验输出内容。我习惯每次改动只改一个变量，改完立刻回跑测试集，这样即使出了问题，也能精确定位到是“新增规则”还是“调整模板”造成的。

4. 把多条 skill 组合成有效的工作流

4.1 单任务多技能：轮询与自动触发

当系统里积累到十几条 skill 之后，新的问题出现了：一个复杂任务往往需要多个技能协同。比如一次完整的“发布前质量检查”，可能需要先跑“代码审查”，再跑“生成变更日志”，最后跑“配置检查”。如果让用户手动挨个触发，体验很割裂。

我现在更喜欢的做法，是把整个流程拆成多个技能，靠系统描述按需触发，让它们按顺序自动接力。比如“代码审查”技能处理完后输出了结构化的审查结果；“变更日志”技能识别到这份结果里合入的变更点，自动生成更新日志；“配置检查”再对日志中提到的配置路径做复核。每一步的输出，就是下一步的输入，中间不需要人来切换。

4.2 技能与技能之间怎么设计接口

接口设计是组合能否成功的关键。跨技能的数据交接，最重要的原则是“输出结构化”。如果“代码审查”输出的是零散的自然语言，后面的“变更日志”就没法可靠地从中提取要点。

我会在技能模板里特意设计一个“机器可读摘要”区，一个纯 Key-Value 列表，比如：

{ "files": ["src/auth.py", "src/db.py"], "severity": "high", "issues": ["missing exception handling", "n+1 query detected"] }

后面接手的技能只需要从这段摘要里读取字段，完全不需要重新理解整个审查过程。这个做法，本质上是把“人给模型讲清楚”变成了“模型给模型交接数据”，效率完全不一样。

4.3 团队级技能仓库的目录规划

如果你是在团队里推广这套玩法，我建议提前为团队搭建一个“技能仓库”，让所有技能按统一目录组织、集中管理。一个可参考的结构：

team-skills/ ├── development/ │ ├── code-review/ │ ├── sql-review/ │ └── dependency-check/ ├── devops/ │ ├── changelog/ │ ├── ci-config-review/ │ └── log-troubleshooting/ └── writing/ ├── technical-post/ └── meeting-notes/

目录规划的意义在于：让团队成员能按“任务类型”而不是“个人喜好”找到技能；也方便把维护权下放到各对应职责的角色。写代码规范的团队维护 development 目录，运维同事维护 devops 目录，互不干扰。更进一步，还能给每个技能加上负责人和更新时间，让技能包变成团队共同维护的资产。

5. 踩过坑之后，写给新手的避坑清单

5.1 高频雷区：为什么我一开始做不好

做技能包最初的几个月里，我几乎把能踩的坑都踩了一遍，整理出几个高频雷区，帮你直接绕开。

第一，description 写得太泛。“分析代码并给出建议”这种描述会导致几乎所有对话都试图触发它。一个技能的正确触发率，很大程度上取决于描述里是否写清了“什么时候用、什么时候不用”。

第二，指令与系统提示冲突。我曾在技能里写了“始终输出中文”，但全局系统要求里写了“保留代码注释原文”，结果两边同时生效，行为摇摆不定。解决方式很简单：技能只约束技能范围内的输出，不要干预全局。

第三，辅助文件路径写错。AI 在处理相对引用时会依据上下文推断路径，路径写得不清晰很容易失效。我现在的做法是写绝对路径或带明确目录说明的引用，并在测试集中专门放一个“引用路径准确性”用例。

第四，测试集与真实场景脱节。最初的测试样例都是我“亲手撰写的完美案例”，结果真上线之后，遇到用户那些乱糟糟、缺字段的真实输入，表现很差。后来我把线上失败的真实案例全部回灌进测试集，准确率才提上来。

第五，过度封装。新手很容易沉迷于给所有任务建技能，最后技能数量比项目代码还多，维护负担远超收益。我建议从“周复用次数大于三次”的任务开始做，不为一次性任务建技能。

5.2 几个我觉得值得坚持的实践习惯

这几条算不上什么先进方法论，属于我自己的经验性规矩，但确实让我省了不少事。

• 每次只改一处：改完立刻回跑测试集，保持因果清晰。
• 为每个技能配一个“最佳实践”文档：里面记录当前版本的设计决策、为何这样写，方便三个月后的自己快速回忆。
• 定期清理失效技能：技能包和代码一样需要技术债管理；长期不用的技能要及时归档，避免系统误匹配。
• 把失败案例当宝：一次输出不符合预期，不是“模型不行”，而是“技能包该补课了”。把案例补进测试集，迭代几次后，这类问题就很少复现。

5.3 什么时候不该用 skill

最后一条，可能和你期待的相反——我建议某些场景不要用技能包。

一种是高度依赖实时上下文的任务。比如“根据当前 Git 分支所有未提交的改动生成发布说明”，这种任务执行时需要的不是技能，而是实时环境信息，技能包反而会占用上下文。

另一种是探索型任务。项目方向还没定，你也不知道最终要什么结果，这时候与其做一个预定义的技能包，不如先把 prompt 写清楚，等思路收敛后再把经验沉淀成技能包。技能包是“路走通之后铺出来的跑道”，不是“探路时用的地图”。

还有一种是极短任务。比如“把这段英文翻译成中文”，一句 prompt 就解决的问题，没必要为了形式建一个技能。技能包有加载成本，短任务用技能包，只会在响应速度和结果稳定性之间两头吃亏。

最后说几句个人的体会

做 skills 这件事，最吸引我的不是“让 AI 更准确”，而是“让经验变得可持续”。以前我沉在项目里的那些判断标准、细节考量和易错点，只能靠记忆和文档碎片勉强维护；现在它们被落进一条条技能包里，跟着测试集一起迭代，成了真正能反复使用、交给任何人都能稳定输出的资产。

如果你准备开始尝试，我给的最小起步建议是：挑一个你每周都会重复做的小任务，比如写变更说明、审查 SQL、检查配置清单，把它做成第一条最简技能包，配上三个测试用例。不需要一开始就把目录搭得多完整，先跑通这一个循环。等这条技能的效果稳定了，你会自然而然想扩到第二、第三条，这个时候再回头设计目录、考虑团队协作，顺理成章。

我个人现在的习惯是：每次遇到一次精彩的处理思路，就把它补进对应技能的 best-practices 文档里。技能包越用越厚，但对话里的指令却越来越薄——这种感觉，挺踏实的。