刚做完整段时间的 AI 编程工具调研和实践，我最大的一个感受是：身边很多人还停留在“写 Prompt”的阶段，一个复杂的提示词贴来贴去，换个项目、换个助手、换个对话窗口，效果就完全飘了。于是越来越多人开始聊 Skill，尤其是 Codex、Claude、DeepSeek Harness 这些工具里冒出来的 skill 插件、skill 脚本、agent skill 的概念。我一开始也觉得 Skill 无非就是“把 Prompt 打个包”，但真正动手拆了几个热门 skill 之后，发现事情没那么简单——它其实是把“一次性的话术”升级成了“可复用的能力模块”。这篇文章会把我在迁移过程中的思考、框架、踩坑和部署经验完整梳理一遍，给正在从 Prompt 走向 Skill 的人一份可以直接照抄的参考。
1. 从“一次性提示”到“可复用能力”：Prompt 模式为什么撑不住
1.1 先别急着做 Skill，看看 Prompt 暴露了哪些硬伤
我先说一个很常见的场景。你在某个 AI 编程工具里写了一段很牛的系统提示词，让模型按照你的编码规范去审查代码、补测试、生成提交信息，当时效果惊艳。但第二天换个仓库，你把这套提示词原样粘过去，模型开始答非所问；再或者同一个对话聊了五十轮，上下文窗口逼近上限，它突然忘了最初的规则。网上有人管这叫 prompt 闪退，也有人遇到 invalid prompt: your prompt was flagged as potentially violating our usage p 之类的报错，直接不让发。
这些症状看着是偶发问题，其实背后有四类硬伤：
- 上下文不可控：提示词里的规则和对话过程中新增的信息混在一起，模型越往后越分不清哪些是“指令基线”、哪些是“临时消息”。
- 复用性差：提示词是一大段连续文本，换一个任务场景，哪怕只改一个变量，也得把整段重写，而且重写之后往往要重新调试。
- 没有校验和回退：提示词只能告诉模型“你该怎么做”，没法定义“如果输入不对怎么办”“如果模型给不出结果怎么办”。
- 不可组合：你想让模型先做代码审查再做重构建议，两个提示词之间没有结构化接口，只能靠模型自己悟。
这些问题的根源在于，Prompt 本质上是一个静态信息片段。你可以把它理解成一张“写满了要求的纸条”，每次都要手动塞给模型，模型还得自己判断这张纸条的优先级。而 Skill 要解决的，就是把这堆纸条整理成一套标准作业程序：有输入、有步骤、有输出、有异常处理。
1.2 token 限制、内容被拦截这些现象，其实都是“提示词无结构”的副作用
很多人遇到 invalid prompt 或者 prompt 被拦截时，第一反应是换措辞、减少敏感词，很少会反思是不是结构本身出了问题。我的经验是，排查这类报错时必须先做一个判断：这个拦截是在模型层还是在工具层？在 Codex 这类工具里，工具层通常会基于规则扫描，长 Prompt 里只要有一句边界模糊的描述就可能触发拦截，而这句话单独拿出来看完全无害，但放在一个大段文本里就可能命中某些特征。
更深层的原因在于，模型对一块无结构的文本做“指令跟随”，本质上是一个概率行为。它要同时处理角色设定、任务描述、输出格式、约束条件、示例，碎片越多，注意力分布越散。你可能会发现，同样一段规则写在对话开始的系统提示里和写在 skill 的步骤字段里，效果完全不同——因为后者被结构约束成了“按顺序执行的步骤”，前者只是一堆并列文本，模型无法确认优先级。
所以，Prompt 本身不是不能做好，而是它适合“一次性、短链路、高容错”的任务。可一旦任务变成“每次都要稳定复现同一个流程”，你就需要一个比 prompt 更高一层的封装，这就是 Skill 出现的原因。
2. Skill 的内核：它到底比 Prompt 多出来的东西是什么
2.1 先拆一个标准 Skill，看它长什么样
网上搜 skill 相关的内容，能看到很多格式：有 YAML 的，有 JSON 的，有 Markdown 的，还有带脚本的 skill 插件。不同平台格式不统一，但核心骨架高度一致。我拿一套常见的 Skill 文件来拆解，它通常包含这么几个字段：
name: code-review-skill description: 对本次代码变更进行系统性审查，输出风险清单和修改建议 inputs: - name: diff_content type: string required: true description: 待审查的代码 diff 或文件内容 - name: language type: string required: false default: python steps: - 识别变更涉及的核心函数和调用链 - 检查是否有潜在的异常处理和边界条件遗漏 - 对照项目编码规范给出违规点 - 按严重程度输出风险清单 fallback: - 如果无法获取 diff_content，反问用户需要审查的文件范围 - 如果审查结果为空，提示用户变更内容太少或提供完整上下文 metadata: version: 1.2.0 author: xxx tags: [code-review, coding]请注意一个细节：description和inputs是 Prompt 里完全不具备的东西。在纯 Prompt 里，你只能写“请审查以下代码，重点关注异常处理”，但用户到底给你什么、缺了什么字段可不可以继续、默认值是什么，模型只能靠猜。Skill 则把这些信息全部契约化了。
2.2 对比 Prompt 和 Skill，差异不在“格式”而在“控制点”
我做过一张对比表，基本上每个维度都能看出差距：
| 维度 | Prompt | Skill |
|---|---|---|
| 信息形态 | 连续自然语言文本 | 结构化字段 + 步骤 + 回退策略 |
| 输入约定 | 依赖模型从上下文推断 | 显式声明字段、类型、是否必填、默认值 |
| 执行顺序 | 模型自行决定关注顺序 | 步骤列表引导模型按序执行 |
| 异常处理 | 没有定义，模型只能硬着头皮回答 | 可配置 fallback 策略，给出替代路径 |
| 组合能力 | 段落之间无接口，只能物理拼接 | 可以定义输入输出契约，被其他 Skill 调用 |
| 维护成本 | 改动一行就要重新调试全文 | 版本化 + 字段独立，定位问题更快 |
最核心的区别，我认为是“控制点的位置”。Prompt 把控制点全部放在模型的理解能力上，你写得再细，模型都有可能漏；Skill 把控制点外移到了结构上，字段缺失、步骤跳转、异常分支，工具层可以提前做校验，模型只要在结构范围内填充内容即可。
2.3 Skill 本质上是给模型装了一套“程序骨架”
你可以把一个 Skill 理解成“给模型用的带注释的伪代码”。模型本身是个极强的自然语言处理器，但它不擅长在没有流程约束的情况下持续保持同一个行为模式。Skill 做的事情，就是把这个流程约束写成显式步骤。
这也是为什么很多 Agent 系统，包括 OpenClaw、WorkBuddy、SpringAI 2.0 这些框架，越来越依赖技能插件。它们不是想让模型读懂更多知识，而是要让模型可以按照既定流程去调用工具、执行子任务、在关键节点做判断。没有 Skill，Agent 每做一步都要从大段 Prompt 里重新理解全局目标；有了 Skill，Agent 可以每次只关注当前步骤的输入输出，目标被拆成了可执行的小任务。
3. 可复用 Skill 设计框架：我总结的五步套路
写了十几个 Skill 之后，我总结出一套五步设计框架，不敢说多高级，但对新手来说足够避免“把 Prompt 换个壳就叫 Skill”的误区。
3.1 第一步：圈定任务边界，越窄越好
很多人第一版 Skill 失败，就是因为把任务边界定义得太宽。比如你想做一个“代码审查 Skill”，结果 description 写的是“帮助用户提升代码质量”，那模型会把代码风格、单元测试、架构设计、安全漏洞全都扯进来，输出必然泛泛而谈。
我建议的做法是把任务拆到“一个 Skill 只干一件有明确终态的事”。代码审查可以拆成“审查变更是否引入异常处理遗漏”“审查 API 变更是否影响调用方”“检查是否违反项目命名规范”，每个拆解项都能独立验证成败。Skill 的边界越窄，description 越容易写清楚，模型也越容易稳定复现。
3.2 第二步：把输入契约定义清楚，别让模型猜
这一步是 Prompt 用户最容易忽略的。在纯 Prompt 里，你写“请分析以下代码”，代码范围全靠模型从上下文里捞。Skill 里必须显式声明 inputs，包括类型、必填性、默认值。以 GIS 空间分析 Skill 为例，它如果要计算缓冲区，就必须声明输入是经纬度坐标、缓冲区半径还是矢量要素对象。
设计输入契约有一条经验：必填字段尽量少于等于三个。字段太多，用户的输入成本和错误率都会上升。超过三个，就把不关键的先设置默认值，或者设计成“如果缺省则自动推导”。
3.3 第三步：把执行过程写成线性步骤，但留分支出口
我见过有些人写 Skill 的 steps，洋洋洒洒二十条，看起来非常细，实际跑起来效果并不好。因为步骤一旦太长，模型在后续步骤中会忘记前面的约束。我的经验是，主流程控制在五到八步，超过八步就考虑拆成多个子 Skill 或者用两个阶段。
步骤本身要写成“动作 + 产出”的结构。比如：
- 提取变更文件中的函数签名和调用关系。
- 生成需要重点审查的函数清单。
- 逐个检查异常处理、边界条件、资源释放。
- 汇总风险，按 P0/P1/P2 分级输出。
每个步骤都隐含一个阶段性产出，模型执行完一个动作，产出物可以作为下一步的输入，这样整条链路的可控性就大大提升。
3.4 第四步：别忽视 fallback，它是 Skill 和 Prompt 的分水岭之一
Prompt 面对“输入不足”只会让模型硬答，Skill 必须显式设计回退策略。我通常会在 Skill 里加这么几类 fallback：
- 输入缺失：必填字段没拿到，是终止还是询问用户？
- 步骤产出为空：某一步模型没给出有效结果，是重试还是跳步？
- 适用范围超出：用户输入的内容明显不属于这个 Skill 的边界，是继续还是引导到另一个 Skill？
设计 fallback 还有一个作用，就是减少“invalid prompt”这类拦截几率。很多拦截其实来自模型在无路可走时产生了含糊输出，而 fallback 给了它一条明确路径，反而降低了违规风险。
3.5 第五步：版本化与元信息，别等到要回滚时才后悔
Skill 文件里我强烈建议至少保留 version、author、tags 三个字段。你可能觉得一个脚本而已，版本号写不写无所谓。但 Skill 是会被组合的，很可能三天后你自己都忘了这个文件里哪段逻辑是旧的。版本号至少让你在出现回归时能定位到是哪一个 Skill 的问题。
tags 字段更重要，它是 Skill 被检索和复用的关键。很多技能库的匹配逻辑就是先扫 description，再扫 tags。你的 Skill 如果 description 写得太文艺、tags 又没写，其他同事或另一个 Agent 根本不会主动调用它。
4. 三个实际迁移案例：从 Prompt 到 Skill 的完整路径
4.1 案例一：把零散的代码审查提示词改成 Skill
我原来有一个代码审查 Prompt，大约四百字，包含角色设定、风格要求、输出格式、禁止事项。直接用它，效果看运气。后来我按五步框架重构成 Skill，精简成上面那一版 YAML，最关键的变化有两个：一是把“审查什么范围”交给了 inputs，二是把审查步骤拆成了四个顺序明确的阶段。
改造之后，最大的收益不是输出质量暴涨，而是输出的一致性。同一个 diff 内容，跑十次，得到的风险清单排序和分类基本稳定。这对纯 Prompt 来说几乎做不到，因为模型每次都会对并列文本中的某一段产生不同的注意力侧重。
4.2 案例二：GIS 空间分析 Skill，一个跨领域迁移的样本
在热搜词里看到“GIS 空间分析 skill”，我挺有共鸣。地理空间分析这种任务，用户输入差异极大：有人给坐标点，有人给 GeoJSON，有人给行政区域名称。如果靠 Prompt，你得在每次对话中反复解释“我的数据是什么格式”，上下文很快被撑爆。
Skill 可以把格式约定和计算流程全部封装。比如定义 inputs 为location_data、analysis_type、buffer_radius，步骤里写清楚先解析数据格式，再调用空间算子，最后输出分析报告。对整个执行过程进行标准化后，用户只需要每次传入新数据，绝大多数格式化默认可通过 skill 自身的解析逻辑处理。
跨领域的经验是：输入差异大的任务，最适合用 Skill 而不是 Prompt，因为它可以把“格式理解”这种消耗模型注意力的事情，固化在结构化字段和步骤里。
4.3 案例三：AI 短剧脚本 Skill，将创意任务流程化
很多人以为 Skill 只适合工程任务，实际上创意类任务同样可以。网上讨论的“用 Agent 制作 AI 短剧”，核心不是让模型会写台词——ChatGPT 本来就会写。核心是如何让 Agent 稳定地输出符合结构的脚本：有分场、有人物动作描述、有镜头提示词。
我测试过一个短剧 Skill，它的步骤是：
- 根据用户提供的故事梗概，拆分成三幕结构。
- 每幕细分场次，标注时间、地点、人物状态。
- 生成对白，同时为每个关键动作补充镜头角度提示。
- 汇总成统一的脚本格式，并检查场次连贯性。
跑完十几次之后，产出脚本的完整度确实比直接用 Prompt 稳定很多。这说明 Skill 不是工程化任务的特权，它本质上是“把任何流程化能力固化下来”的容器。
4.4 这三个案例说明了同一件事
代码审查、GIS 分析、短剧脚本，领域完全不同，但改造逻辑一样：找出这个任务里哪个环节是反复运行的，哪个环节的输入格式是变化的，然后把反复运行的部分固化为步骤，把变化的部分抽象成参数。这一步想通了，Skill 设计就入门了。
5. 部署与排坑：从本地验证到内网服务器的实际经历
5.1 本地快速验证：别一上来就接 Harness
我的建议是本地先跑通一个独立 skill 文件，不要着急部署到 DeepSeek Harness 或者公司的 Agent 平台。本地验证最快的方式，是找一个支持技能导入的桌面客户端或命令行工具，把写好的 skill 文件扔进去，用一个模板输入跑一遍，看输出是否符合预期。
这里有个判断标准：如果同一个 Skill 在不同模型上表现差异巨大，先不要怪模型，先回去检查 skill 的描述和步骤是否足够自洽。Skill 里如果过度依赖某种模型才有的隐含能力，换模型就会翻车。合理的做法是让 Skill 只依赖通用能力，比如指令跟随、文本分析、JSON 解析，这些都是大模型共通能力。
5.2 内网部署最常出错的三件事
很多人搜“deepseek harness 附带 skill 怎么部署到内网服务器”，说明在私有化部署场景里，Skill 并不总能平滑迁移。我实际经历下来，最容易出包的三件事是：
- 路径和权限问题：Skill 文件通常需要放在指定目录，内网服务器往往没有外网下载依赖的能力，如果 skill 声明了外部工具调用，必须提前把工具装好。
- 模型上下文的差异：内网部署的模型参数量可能更小，同一份 Skill 中步骤较多时，小模型容易执行一半就“迷路”。此时不要把步骤压缩成更短的描述，而是拆成两个 Skill，用 Agent 串联。
- 配置文件里编码问题：Skill 文件如果包含中文注释，在部分内网环境的默认字符集下会出现乱码甚至加载失败。怀疑文件本身有问题时，优先排查编码格式，而不是反复调试 prompt 内容。
5.3 “invalid prompt”“skill 编码”这类报错的排查链路
在社区里经常看到有人搜“codex 付费 AI 编程软件”后，第一次跑 Skill 就遇到 invalid prompt: your prompt was flagged as potentially violating our usage p 之类的报错，还有人搜“skill 编码193”“skill 编码247”，以为是某个神秘错误码。这些排查其实都有套路。
我的排查顺序是：
- 先看拦截发生在哪一层。如果发生在工具入口，通常是 skill 文件里的描述文本或步骤文本触发了规则扫描。处理办法不是改措辞，而是把描述改得更加中立、具体、面向任务，避免使用泛化的行为描述。
- 再看模型返回层。如果模型开始正常，输出到一半被中断，多数是生成内容越过了安全边界。此时不要直接删步骤，而是给 fallback 加一个明确的自检动作，让模型在输出敏感结论前先重新验证输入范围。
- 最后查 Skill 文件本身的语法。YAML 里缩进错误、JSON 里多一个逗号，都会导致解析失败，进而被工具层上报成各种奇怪的错误码。把 skill 文件用 validator 跑一遍，能排除大量问题。
5.4 部署之后如何评估 Skill 是否“真的可用”
部署不等于结束。我会用一个非常硬的指标来评估：无人工修正成功率。具体是拿十组不同的真实输入跑同一个 Skill，在完全不改输出、不二次提示的情况下，看有多少组输出的结果可以直接被下游使用。低于 60%，说明 Skill 的定义还不够严谨，应当返回去检查 description 的语义匹配度和步骤的可执行性。
这个指标特别适合对比 Prompt 和 Skill 的差距。我第一次把一个代码审查 Prompt 改成 Skill 后，无人工修正成功率大约从 35% 提升到了 72%，第二次优化输入契约之后到了 85% 左右。没有这个量化指标，你很容易被“偶尔一次效果不错”误导。
6. 让 Skill 变成可迭代的资产，而不是另一个“躺尸文件”
6.1 记住，复用的关键是描述，不是正文内容
Skill 文件写多了以后，你会发现一个大坑：你自己写的 Skill，过两周再看，你都不知道它是干嘛的。如果你都不知道，Agent 更不可能知道。所以 Skill 的 description 字段必须做成“给搜索引擎看的摘要”，里面要有动词、有对象、有产出物。像“对代码变更进行系统性审查，输出风险清单和修改建议”这样的描述，就比“代码分析”好得多。
同理，tags 要预留扩展空间，不要只写一个大类。例如 code-review-skill 可以打上code-review,diff-analysis,risk-assessment,coding-assistant四个标签，这样在不同的 Agent 检索场景里都能被命中。net 上的很多 skill 插件检索不到，八成就是两个问题：描述不具体或者标签太稀疏。
6.2 从个人技能库到团队技能库，还差一个“评审动作”
个人用 Skill 可以随意迭代，但放到团队共享之后，必须有一个最小化的评审机制。我的做法是：任何 Skill 进入共享目录之前，必须包含一份简短的使用示例和一份已知限制说明。使用示例让新人快速上手，已知限制让使用者不会在错误场景里强行调用。
关于版本维护，我强烈建议只保留两个分支：稳定版和实验版。稳定版是经过十组测试达到 70% 以上无人工修正成功率的版本；实验版是正在迭代中的版本。实验版绝不能直接丢到生产 Agent 的默认技能路径里，否则你会看到 Agent 的行为在几天内神秘漂移。
6.3 我最后的感受
从 Prompt 到 Skill，表面上是一次文件格式的变化，实际上是一次思维方式的切换：你不再把 AI 当成一个每次都要重新交代的临时实习生，而是把它当成一个可以反复调用的标准工序。Skill 最大的价值不是让模型更聪明，而是让团队的作业流程可以被沉淀、被测试、被组合、被复用。我建议每个正在重度使用 AI 编程工具的开发者，都尝试把手头最高频的五个 Prompt 逐一改写成 Skill，用无人工修正成功率这个指标去量化前后差异。这一轮改造做完，你对 AI 编程的理解会完全不同。
