刚做完整段时间的 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差异不在“格式”而在“控制点”我做过一张对比表基本上每个维度都能看出差距维度PromptSkill信息形态连续自然语言文本结构化字段 步骤 回退策略输入约定依赖模型从上下文推断显式声明字段、类型、是否必填、默认值执行顺序模型自行决定关注顺序步骤列表引导模型按序执行异常处理没有定义模型只能硬着头皮回答可配置 fallback 策略给出替代路径组合能力段落之间无接口只能物理拼接可以定义输入输出契约被其他 Skill 调用维护成本改动一行就要重新调试全文版本化 字段独立定位问题更快最核心的区别我认为是“控制点的位置”。Prompt 把控制点全部放在模型的理解能力上你写得再细模型都有可能漏Skill 把控制点外移到了结构上字段缺失、步骤跳转、异常分支工具层可以提前做校验模型只要在结构范围内填充内容即可。2.3 Skill 本质上是给模型装了一套“程序骨架”你可以把一个 Skill 理解成“给模型用的带注释的伪代码”。模型本身是个极强的自然语言处理器但它不擅长在没有流程约束的情况下持续保持同一个行为模式。Skill 做的事情就是把这个流程约束写成显式步骤。这也是为什么很多 Agent 系统包括 OpenClaw、WorkBuddy、SpringAI 2.0 这些框架越来越依赖技能插件。它们不是想让模型读懂更多知识而是要让模型可以按照既定流程去调用工具、执行子任务、在关键节点做判断。没有 SkillAgent 每做一步都要从大段 Prompt 里重新理解全局目标有了 SkillAgent 可以每次只关注当前步骤的输入输出目标被拆成了可执行的小任务。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 编程的理解会完全不同。