2026年初的这场AI编程浪潮，相信很多开发者都深有体会。公司大力推广AiCoding，年前请导师、定场景、写Spec，从系统架构到目录结构，再到端到端的代码生成，我们试图用一个个精心编写的Prompt文件来驾驭AI。
但现实往往是骨感的，完全指望AI“心领神会”去生成代码，效果并不理想，最后往往还是退化成了“人工编写模版+AI填充”的半自动化模式。
过完年，技术圈的风向变了，大家开始疯狂地将提示词转换为SKILL。加上大模型的升级，于是，我们又陷入了新一轮的“不停迭代”“不停适配”中。
这不禁让人困惑：Prompt和SKILL到底有什么区别？为什么换了模型又要重新折腾？究竟什么样的SKILL，才能称得上是规范、稳定且通用的“工业级”标准？
今天，我们就来彻底拆解这个问题，并补充更多技术细节与实例。
Prompt与SKILL：从“口头指令”到“操作手册”
要理解为什么SKILL是下一代，我们先得搞清楚它和Prompt的本质区别。
如果把AI比作一个新入职的实习生：
-
**Prompt（提示词）是“口头指令”**你站在他旁边，告诉他：“嘿，帮我把这个Vue文件改成TypeScript，记得用script setup语法。”
-
特点：即时性强，说完即焚。
-
缺点：每次都要重新说一遍；如果实习生心情不好（模型波动）或者你表达有歧义，他可能理解错；由于没有书面记录，他每次做这件事的标准可能都不一样。
-
你的现状：之前写的 Prompt.md文件，就是这种“口头指令”的集合。一旦模型升级，之前的“口头习惯”可能就不适用了，导致你需要重新调整措辞。
-
**SKILL（技能）是“岗位操作手册（SOP）”**你递给他一本厚厚的手册，上面写着《Vue3重构标准作业程序》。手册里明确规定了：第一步做什么，第二步检查什么，遇到闭源框架的特定注解该怎么处理，甚至附带了标准代码示例。
-
特点：持久化、标准化、可复用。
-
优势：写在本地文件（如 SKILL.md）中，AI每次执行前都会“查阅”这本手册。无论模型怎么变，只要手册里的规则（SOP）足够清晰，输出结果就能保持高度一致。
一句话总结：Prompt解决的是“怎么说清楚”，而SKILL解决的是“怎么做标准”。
为什么你的SKILL还在“不停迭代”？
很多团队从Prompt转到SKILL后，发现效果提升了，但依然不稳定，换个大模型版本又要重写。这通常是因为你的SKILL还停留在“长Prompt”的阶段，而不是真正的“工程化技能”。
一个规范的、能抗住模型迭代的SKILL，必须具备以下三个核心要素：
结构化元数据：给AI一张“身份证”
一个标准的SKILL目录，核心是 [SKILL.md](http://SKILL.md) 文件。它不应该只是一堆文字，而应该包含YAML格式的前置元数据。
---
name: vue3-refactor-standard
description: 专门用于将旧版Vue2或JS代码重构为Vue3+TS+ScriptSetup的标准流程。当用户提出重构、升级或转换Vue组件时激活。
version: 1.0.0
---
价值：这让AI知道“我是谁”、“我该在什么时候被激活”。当任务涉及Vue重构时，AI会自动加载这个SKILL，而不是依赖你每次在对话框里喊“请用Vue3写法”。
渐进式披露：节省“脑力”与Token
很多失败的SKILL是因为把几千字的规则一股脑塞给AI，导致AI“消化不良”或Token超限。
规范的SKILL采用“渐进式披露”策略：
-
发现阶段：AI启动时，只读取SKILL的
name和description（极短）。 -
激活阶段：只有当你触发相关任务（比如“重构这个文件”）时，AI才会去读取
[SKILL.md](http://SKILL.md)里的详细指令。 -
执行阶段：在SKILL内部，可以引用具体的代码片段或脚本，而不是纯文字描述。
代码优于文字：把“经验”变成“脚本”
这是最关键的差异。你在文中提到“闭源框架上效果不理想”，这是因为纯文字描述很难让AI精准理解复杂的框架约束。
一个工业级的SKILL，不仅仅是Markdown文档，它还可以包含scripts文件夹。
skill-name/
├── SKILL.md (指令与流程)
└── scripts/ (可执行的Python/Bash脚本或代码模板)
与其告诉AI“请在框架的Controller层加上@Transactional注解”，不如直接在SKILL里提供一个代码模板或检查脚本。让AI“照着写”或者“运行检查”，比让AI“思考怎么写”要稳定得多。
实例解剖：一个工业级SKILL的诞生
让我们以“为公司框架生成CRUD接口”为例，看看一个真正的工业级SKILL长什么样。
目录结构：
internal-framework-crud/
├── SKILL.md
├── references/
│ ├── api-spec-
template.md
│ └── entity-annotation-
guide.md
└── scripts/
├──
generate_controller.py
└──
validate_entity.py
这个文件是整个技能的大脑，它定义了流程、规则和约束。
---
name: internal-framework-crud
description: 为公司内部闭源框架生成标准的CRUD接口，包括Controller、Service和Entity层。
version: 2.1.0
---
### 目标
根据用户提供的业务需求（如“用户管理”），生成一套符合公司框架规范的完整CRUD代码。
### 执行流程
1. **需求澄清**：首先，向用户确认核心实体（Entity）的名称和关键字段。例如，对于“用户管理”，实体是`User`，字段包括`username`, `email`等。
2. **加载规范**：读取`references/
entity-annotation-guide.md`
，确保生成的Entity类使用正确的框架注解。
3. **生成代码**：
- 调用`scripts/
generate_controller.py`
脚本，传入实体名和字段，生成`
UserController.java`
。
- 在生成Service层时，必须遵循“接口+实现”的模式。
- **关键约束**：所有数据库操作必须通过`BaseMapper`，严禁在Controller层直接编写SQL。
4. **输出模板**：将生成的代码按照`references/
api-spec-template.md`
的格式整理并输出给用户。
### ️ Gotchas (避坑指南)
- **禁止** 使用`@Autowired`，必须使用构造器注入。
- 遇到`@CompanyDataSource`注解时，必须保留原样，不要尝试修改或移除。
- 如果用户未指定主键策略，默认使用`@TableId(type =
IdType.ASSIGN_ID)`
。
- 生成的代码必须包含基础的参数校验（如`@NotNull`, `@Size`）。
2. references/：知识资料库
这个文件夹存放了所有AI需要参考的静态资料，如API文档、代码规范、模板等。
references/ [entity-annotation-guide.md](http://entity-annotation-guide.md)
### Entity注解规范
* 表名映射: 使用`@TableName("t_user")`。
* 主键: 使用`@TableId`。
* 字段忽略: 使用`@TableField(exist = false)`。
* 数据权限: 必须添加`@DataPermission(deptId = "dept_id")`。
references/ [api-spec-template.md](http://api-spec-template.md)
### API: [功能名称]
* **URL**: `/api/v1/[entity]/[action]`
* **Method**: `POST`
* **Request**:
```json
{
"id": "long",
"name": "string"
}
```
* **Response**:
```json
{
"code": 200,
"msg": "success",
"data": {}
}
```
3. scripts/：自动化执行工具
这个文件夹存放了处理确定性任务的脚本，将AI从繁琐的“体力活”中解放出来，专注于逻辑决策。
scripts/ [generate_controller.py](http://generate_controller.py)这个Python脚本可以根据传入的参数，直接生成符合规范的Controller代码骨架，AI只需要在此基础上填充业务逻辑即可，极大地减少了出错的可能。
什么样的SKILL才算“稳定”？
一个能穿越模型版本的SKILL，应该遵循“SOP化”原则：
-
单一职责不要试图用一个SKILL解决所有问题（比如“全栈开发助手”）。应该拆分为：“代码审查SKILL”、“单元测试生成SKILL”、“闭源框架CRUD生成SKILL”。 SKILL.md文件最好控制在500行以内。
-
防御性指令在SKILL中加入“Gotchas（避坑指南）”模块。例如：
## ️ Gotchas
- 不要使用Options API，必须使用<script setup>
- 遇到公司闭源框架的@DataSource注解时，必须保留原样，不要尝试重构它
- 大文件（>1000行）请分段处理，不要一次性输出
这种明确的“负面约束”，比单纯的“正面引导”更能防止AI在模型升级后“乱发挥”。
结合MCP：给AI装上“机械手”
SKILL解决了“怎么做（流程）”，但有时候AI还需要“用什么做（工具）”。
MCP（模型上下文协议）是给AI提供外部工具能力的（比如读取数据库、调用内部API）。
最佳实践：SKILL定义审查流程 -> MCP提供读取代码库的能力 -> SKILL执行审查 -> 输出报告。
SKILL负责“大脑”的逻辑，MCP负责“手脚”的延伸。
写在最后
从Prompt到SKILL，不仅仅是文件格式的变化，更是开发思维的升级。
我们正从“堆砌提示词”的魔法时代，走向“编写SOP”的工程时代。如果你还在为模型升级而焦虑，不妨停下来检查一下：你的SKILL里，究竟是充满了模糊的自然语言指令，还是沉淀了确定性的流程、脚本和标准？
把“人的经验”固化进SKILL，让AI成为那个拿着标准作业手册、无论换什么脑子（模型）都能稳定干活的资深工程师。这才是AiCoding的终极形态。
