过去一年我一直在折腾 AI 编程从给大模型写一段 Prompt 让它帮忙补全代码到把整套代码审查流程封装成 Skill 让 Agent 自动跑。我最大的感受是Prompt 解决的是“单次对话”问题Skill 解决的是“可复用能力”问题。这篇东西把我最近沉淀的一套从 Prompt 到 Skill 的可复用技能设计框架完整梳理出来适合那些正在把重复性 AI 任务变成自动化流程、想在 Codex 这类 AI 编程工具里搭建自己技能库的人。我见过太多人把时间耗在“调 Prompt”上——换个项目就要重写一遍换个模型又要微调措辞输出格式忽好忽坏。其实问题不在 Prompt 写得不够好而是你压根不该用 Prompt 去承载一个完整的、可重复的工作流。真正该做的是把高频任务固化成 Skill让 AI 编程工具像调用函数一样调用你的经验。下面这套框架是我踩了两个月坑之后整理出来的从设计逻辑到实操步骤都有希望能给你一条能直接落地的路径。1. 为什么要从 Prompt 走向 Skill可复用的价值逻辑1.1 一次被“复制粘贴”逼疯的瞬间先讲个真实的场景。我上个月接了一个 Python 项目的代码审查要求查安全问题、性能隐患和可维护性。第一版我是这么干的把项目里几个关键文件复制进对话窗口然后贴上一段精心打磨过的 Prompt要求模型从三个维度审查并且按风险等级输出。第一次效果还行但项目有 27 个文件我不能全塞进去。于是我就一遍遍复制文件内容、粘贴 Prompt、调整措辞、整理输出。到第八个文件的时候我发现自己干了一件极其愚蠢的事同一段审查 Prompt 已经原封不动粘贴了七次只是中间的文件内容变了。同时我还发现另一个问题同一个 Prompt 在不同轮次里的表现很不稳定。第三轮它给出了两个安全问题第五轮同样代码它居然只提了代码风格因为我无意中在后面多了一句“重点关注命名规范”——就这一句把整个输出重心带偏了。那一刻我意识到Prompt 这种东西本质上是把指令和责任全压在一次对话上。它没有记忆没有固定的校验逻辑没有可回归的测试。它只适合“一次性提问”不适合“反复执行同一类任务”。1.2 Prompt 与 Skill 的本质差异从“话术”到“程序”Skill 在这个生态里不是一个抽象概念它是一组有结构的文件包含说明文档、脚本和参考资料Agent 运行时读取这些文件按照你的设计去执行。我直接用一张表对比两者对比维度PromptSkill存在形式一段对话文本文件目录 脚本 文档使用方式每次复制粘贴安装后随时调用稳定性依赖临场上下文靠固定逻辑约束输出可复用性换场景就得重写一套逻辑多处复用可调试性只能改措辞试运气可以写测试用例回滚版本增强路径靠感觉微调靠迭代文件版本打个比方Prompt 像你口述做菜步骤每次做完都要重新解释一遍“盐少许”到底是多少Skill 像是把菜谱、食材预处理脚本和标准摆盘图全装进一个盒子你只要说“来一份水煮鱼”它就把完整流程跑完。这个差异背后其实是编程思维的入场。写 Skill 时不只是在“说话”而是在定义输入、处理流程、输出格式、边界条件。你开始像设计接口一样设计 Agent 的行为。1.3 Skill 带来的三个直接收益第一个收益是确定性。Skill 里的审查清单和输出模板是写死的Agent 再怎么发挥最终输出结构基本可控。第二个收益是复用性同一个审查 Skill 可以用于个人项目、团队项目、不同语言的项目只要改一下 references 里的规则文件就行。第三个收益是可迭代Skill 出了毛病直接改文件、加测试不需要向模型“解释清楚”改完重跑就是。所以如果你发现自己某个 Prompt 已经用了超过三次每次还在手动微调它就该升级成 Skill 了。这比我后面讲任何原理都更重要——判断该不该做 Skill不是看它多酷而是看它是否值得固化。2. Skill 的结构与设计原则从零开始规划2.1 一个 Skill 的标准目录结构SKILL.md、scripts、references不同 AI 编程工具对 Skill 的具体格式要求不完全一样但主流做法已经收敛到一套近乎通用的结构。一个最小可用的 Skill 目录大致长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── scan.py ├── references/ │ ├── checklist.md │ └── examples.md └── assets/ └── template.mdSKILL.md 是入口文件Agent 会优先读这个文件判断当前任务能不能用这个 Skill、应该怎么用。scripts 目录放辅助脚本用于执行那些模型不擅长的确定性工作比如正则扫描、文本提取、文件统计。references 是知识库放详细的专业清单、规则说明避免 SKILL.md 又臭又长。assets 放模板或者示例输出。这个结构借鉴了 Spring AI 2.0 里技能加载器的思路先通过描述匹配技能再加载脚本和引用资料最后由模型根据指令生成结果。像豆包、Codex 这些工具虽然不叫 Spring AI但底层逻辑都类似。2.2 写好 SKILL.md 的关键把指令、示例、边界写清楚SKILL.md 才是 Skill 的灵魂。它不是让你写一篇论文而是写一份“给 Agent 看的操作手册”。我写了几十个 SKILL.md 之后总结出四个必须覆盖的模块技能名称和适用场景让 Agent 一眼判断“这个技能该不该用”。输入要求明确任务传入什么格式、来源是文件还是粘贴文本。执行步骤按顺序列出处理流程每一步要尽量具体。输出格式定义标题、字段、排序规则最好给一个参考示例。这里最容易犯的错是“边界模糊”。比如我在一个翻译 Skill 里写了“负责把中文材料翻译成英文”结果 Agent 把编程注释里的中文也翻了一遍注释的语义全被破坏了。后来我加了一句“仅处理用户明确要求翻译的文本块保留代码和文件路径原文”问题就解决了。给一个简化的 SKILL.md 开头片段--- name: python_code_review description: 对 Python 项目做静态代码审查输出安全、性能和维护性问题清单。仅处理用户明确指定的文件或路径。 --- # Python Code Review Skill ## 触发条件 - 用户要求审查 Python 代码 - 用户提到 review 或检查代码质量 - 输入可以是本地文件路径也可以是粘贴的代码块 ## 执行步骤 1. 先读取目标文件优先使用 scripts/scan.py 做静态扫描 2. 结合 references/checklist.md 中的审查规则逐项检查 3. 按输出格式生成报告对高风险问题给出修复建议这个格式简单直接Agent 不需要理解你的深层意图它只需要知道“什么时候用、怎么用、输出什么”。2.3 设计 Skill 的三个原则单一职责、最小依赖、可观测输出第一个原则是单一职责。一个 Skill 就做一件事。我一开始写过一个大而全的“代码助手”Skill既审查代码又生成提交信息还兼顾写测试最后 Agent 每次都乱选子任务。拆成三个独立 Skill 后问题立刻消失。不要偷懒拆开才可控。第二个原则是最小依赖。Skill 里的脚本尽量使用标准库不要依赖需要额外安装的第三方包。原因很简单你换个环境部署的时候pip install 装不上就直接卡死。我自己被这个坑过一次那个依赖只在特定环境下能装内网部署时整整浪费了半天才排查出来。从那以后凡是能用标准库实现的功能我绝不引入外部依赖。第三个原则是可观测输出。Skill 生成的最终结果必须结构清晰、字段固定。这样便于你检查也方便后面再接一个 Skill 继续做二次加工。比如审查报告第一行写风险等级第二行写文件位置第三行写修复建议——这就是给后续自动化留了后门。2.4 从 Prompt 改造为 Skill 的四步法如果你手上已经有一段高频使用的 Prompt改造起来其实不难。按下面四步走审视你的 Prompt 历史找出过去一个月内重复使用超过三次的片段这些就是改造候选。把 Prompt 拆成“知识”和“指令”两层。事实类规则、检查清单、示例这些属于知识放进 references执行动作、输出格式、触发条件属于指令写进 SKILL.md。找出其中可以用脚本代替的部分。比如“扫描代码里的 TODO 标记”“统计函数数量”“提取所有文件路径”这些重复性劳动交给脚本比交给模型稳定得多。准备至少三个测试输入模拟真实场景运行观察输出的稳定性和准确性然后回头修改 SKILL.md 的措辞。这套四步法我用了整整一个季度效果很稳定。它本质上是把一个“凭感觉说话”的过程变成了“设计系统”的过程。3. 实操案例手写一个“代码审查”Skill 的全过程3.1 场景定义与需求边界这里我完整演示一遍我近期在 Codex 这类 AI 编程工具里反复调试通过的“Python 代码审查”Skill 的诞生过程。先定义需求输入是本地 Python 文件路径输出是结构化审查报告覆盖安全风险、性能隐患、可维护性问题三个维度每条问题带风险等级、文件位置、修复建议。边界条件是我反复推敲出来的只做静态审查不执行测试用例只检查用户明确传入的文件不自动扫描全项目不修改源码只输出建议。边界为什么重要因为没有边界Agent 可能自作主张跑去审查 config 文件甚至把依赖文件也列进来。我第一次跑这个 Skill 时它把 venv 里几十个文件全审查了一遍差点把我气笑。加上“只处理用户明确指定的文件”之后它才老实下来。3.2 构建 SKILL.md把要求写成 Agent 能读懂的文档我实际写的 SKILL.md 很短核心就是触发条件、审查规则、输出格式三块。审查规则没有堆在 SKILL.md 里而是放进了 references/checklist.md因为 Agent 可以分段读取引用资料不会一上来就被信息淹没。输出格式部分我给了一个明确的骨架## 输出要求 按以下格式输出按风险等级从高到低排序 - 风险等级[高/中/低] - 位置[文件路径:行号] - 问题描述[一句话说明] - 修复建议[具体可操作的建议] Example: - 风险等级高 - 位置src/main.py:42 - 问题描述直接拼接外部输入构造 SQL 查询 - 修复建议改用参数化查询如 cursor.execute(SELECT * FROM user WHERE id?, user_id)给示例这件事特别关键。我一开始没给Agent 输出的格式每次都不一样有时用表格有时用代码块有时用纯文字。加了这个示例之后输出结构基本固定在九成以上。3.3 编写辅助脚本让 Skill 有“手”可用这个 Skill 里我用了一个 Python 脚本负责扫描代码里的常见标记和安全风险点。脚本不用复杂关键是能输出结构化信息供 Agent 后续拼接#!/usr/bin/env python3 静态扫描脚本提取 TODO/FIXME、函数定义和明显安全风险 import re import sys from pathlib import Path def scan_file(path: Path): results {todos: [], functions: [], risks: []} for lineno, line in enumerate(path.read_text(encodingutf-8).splitlines(), 1): if re.search(r\bTODO\b|\bFIXME\b, line, re.I): results[todos].append((lineno, line.strip())) if re.search(r^\s*def\s\w, line): results[functions].append((lineno, line.strip())) if re.search(r\beval\(|\bexec\(|pickle\.load, line): results[risks].append((lineno, line.strip())) return results if __name__ __main__: for arg in sys.argv[1:]: p Path(arg) if p.is_file(): print(p, scan_file(p))我特意解释一下这里的设计意图。TODO 和函数定义类信息模型自己看代码也能找出来但脚本做这件事更快更准确而且不会漏。安全风险里的 eval 和 pickle.load 属于模式匹配类问题用正则扫一遍是最可靠的模型反而可能因为上下文干扰而漏掉。这个脚本的输出是给 Agent 当“证据链”用的。SKILL.md 里明确写了“先运行 scripts/scan.py然后把扫描结果作为审查报告的输入”这样就形成了一条自动化流水线脚本负责找事实模型负责理解背景和写建议。3.4 实测记录与效果对比Prompt 与 Skill 的差距有多大我用同一个 2000 行的小项目分别跑了原始 Prompt 方案和这个 Skill 方案各跑了五轮结果如下实验项直接用 Prompt用 Skill平均准备时间十几分钟拼接上下文30 秒指定路径输出格式一致性五轮有三种格式五轮基本一致关键风险命中次数两次漏掉高风险 eval 调用五次全部命中是否漏审文件第二轮漏了一个核心模块无遗漏后续修改成本每次都要重贴 Prompt改一行 checklist 即可这个结果并不意外。Prompt 方案的输出质量基本取决于模型当时的注意力分布而 Skill 方案里的脚本保证了大项扫描的完整性SKILL.md 里的输出模板又约束了终稿结构。它俩不是一个维度的产品Skill 是带了控制逻辑的 Prompt。我还观察到一个现象直接用 Prompt 审查时模型很容易把“建议”和“问题”混在一起长篇大论地讲开发技巧Skill 版本里因为输出格式强制让它先列位置再写建议内容收敛了很多。4. 常见问题与排查技巧实录4.1 Skill 没被识别、加载失败怎么办我刚开始用 Skill 时遇到最多的就是“明明装好了Agent 却不调用”。后来发现大部分情况是目录结构不对或者 SKILL.md 头部信息缺失。常见问题有SKILL.md 没有写 name 和 description 字段Agent 无法理解这个技能是干什么的自然不触发脚本文件没有加可执行权限或者路径写错描述里写得太抽象比如“代码处理”Agent 根本不知道什么场景匹配。我的排查顺序是先看 SKILL.md 头部的 description 是否和用户问题强相关再看目录结构是否满足工具要求最后手动运行脚本确认能出结果。这里有个容易被忽略的点有些平台会缓存 Skill 索引你修改完 SKILL.md 之后没有触发重新索引Agent 读到的还是旧版本。我一般会在改完文件后重启会话或者在工具里手动刷新技能列表确保新版本被加载。4.2 提示词被拒、输出失控的排查顺序在实际运行中你可能会碰到“invalid prompt: your prompt was flagged as potentially violating our usage policy”这类提示或者干脆“prompt 闪退”。我第一次看到还以为是模型坏掉了后来排查下来基本就三类原因。第一类是 token 超限。Skill 脚本输出的内容太长加上 SKILL.md 全文一起塞进了上下文直接把上限顶爆。解决办法是精简 references 内容让脚本做摘要而不是全量输出。第二类是内容触发安全策略。当 Skill 要求模型执行“跳过所有安全检查”这类指令时提示词会被直接拦截。解决办法是别在 SKILL.md 里写对抗性指令把目标描述成正常的技术任务就行。第三类是多轮对话上下文污染。前一轮输出太长后一轮加载 Skill 时报错表现为“闪退”。解决办法是拆小任务或者让脚本把内容压缩到必要字段。我总结出一条规律凡是提示词被拒先看是不是自己的输入触发了策略边界再查上下文长度最后才怀疑工具本身。九成问题出前两项。4.3 多 Agent 协作、版本兼容与离线部署的适配问题不同 AI 编程工具对 Skill 的内部装载逻辑不太一样。你可能会在日志里看到类似 skill 编码 193、194、247 这样的内部编号这些其实是不同平台在框架层面对内置技能做的版本标识。193 通常是基础文本处理类技能194 一般是代码分析类247 更偏向多步骤任务编排。遇到这类编号不能盲目套用需要结合当前工具版本去查对应的能力索引。如果你在团队内多 Agent 协作一定要约定统一的 Skill 命名和输出格式否则 AgentA 输出的结果 AgentB 读不懂。我自己吃过这个亏A 输出 markdown 表格B 期望 JSON 字段最后中间加了一个转换脚本才跑通。现在我会在 Skill 的 description 里写清楚输出格式和后续处理建议减少 Agent 之间的“翻译成本”。离线部署是另一个高频问题。有些团队需要把 Skill 部署到内网服务器不依赖外部在线服务。这种情况下 Skill 里的脚本必须完全本地化不能调用云端分析接口也不能依赖在线数据库。参考资源里的清单和示例全部本地存放运行时不需要联网。我在部署前会把 Skill 目录整体打包内网装好 Python 后直接放进去然后跑一遍测试输入验证输出是否正常。只要脚本只用标准库、数据都在本地这套流程基本不会翻车。4.4 避坑清单速查坑表现解决方案Skill 描述含糊Agent 从不触发描述里写清触发场景关键词依赖第三方包部署环境装不上脚本只用标准库输出格式无示例每轮格式都不一样给一个满字段示例检查清单太长SKILL.md 上下文爆炸拆到 references 按需读取脚本输出冗长token 超限脚本只输出字段化摘要边界不明确Agent 乱审无关文件写清只处理用户指定路径指令含对抗性要求提示词被安全策略拦截删除违规指令正常表述没有测试用例改完不知好坏准备三组固定输入做回归这张表基本覆盖了我踩过的所有坑你在自己的 Skill 设计里可以直接对照着查。最后再分享一点个人体会Skill 不是越复杂越好。我见过有人为了写一个“语音转文字”技能硬塞了 300 行 Python 脚本最后还是靠一个系统命令解决的。真正好用的 Skill往往是你已经重复了一百次、熟到闭眼都会做的任务——把它固化下来你才有精力去琢磨那些还没有答案的事情。我现在的工作习惯是任何任务完成三次之后就把它列入 Skill 候选清单每周抽半小时整理一次。这种积累方式会让你的 AI 编程工具越用越顺手而不是每次都在原地重新教它。希望这套从 Prompt 到 Skill 的设计框架能让你少走一点我走过的弯路。
过去一年我一直在折腾 AI 编程从给大模型写一段 Prompt 让它帮忙补全代码到把整套代码审查流程封装成 Skill 让 Agent 自动跑。我最大的感受是Prompt 解决的是“单次对话”问题Skill 解决的是“可复用能力”问题。这篇东西把我最近沉淀的一套从 Prompt 到 Skill 的可复用技能设计框架完整梳理出来适合那些正在把重复性 AI 任务变成自动化流程、想在 Codex 这类 AI 编程工具里搭建自己技能库的人。我见过太多人把时间耗在“调 Prompt”上——换个项目就要重写一遍换个模型又要微调措辞输出格式忽好忽坏。其实问题不在 Prompt 写得不够好而是你压根不该用 Prompt 去承载一个完整的、可重复的工作流。真正该做的是把高频任务固化成 Skill让 AI 编程工具像调用函数一样调用你的经验。下面这套框架是我踩了两个月坑之后整理出来的从设计逻辑到实操步骤都有希望能给你一条能直接落地的路径。1. 为什么要从 Prompt 走向 Skill可复用的价值逻辑1.1 一次被“复制粘贴”逼疯的瞬间先讲个真实的场景。我上个月接了一个 Python 项目的代码审查要求查安全问题、性能隐患和可维护性。第一版我是这么干的把项目里几个关键文件复制进对话窗口然后贴上一段精心打磨过的 Prompt要求模型从三个维度审查并且按风险等级输出。第一次效果还行但项目有 27 个文件我不能全塞进去。于是我就一遍遍复制文件内容、粘贴 Prompt、调整措辞、整理输出。到第八个文件的时候我发现自己干了一件极其愚蠢的事同一段审查 Prompt 已经原封不动粘贴了七次只是中间的文件内容变了。同时我还发现另一个问题同一个 Prompt 在不同轮次里的表现很不稳定。第三轮它给出了两个安全问题第五轮同样代码它居然只提了代码风格因为我无意中在后面多了一句“重点关注命名规范”——就这一句把整个输出重心带偏了。那一刻我意识到Prompt 这种东西本质上是把指令和责任全压在一次对话上。它没有记忆没有固定的校验逻辑没有可回归的测试。它只适合“一次性提问”不适合“反复执行同一类任务”。1.2 Prompt 与 Skill 的本质差异从“话术”到“程序”Skill 在这个生态里不是一个抽象概念它是一组有结构的文件包含说明文档、脚本和参考资料Agent 运行时读取这些文件按照你的设计去执行。我直接用一张表对比两者对比维度PromptSkill存在形式一段对话文本文件目录 脚本 文档使用方式每次复制粘贴安装后随时调用稳定性依赖临场上下文靠固定逻辑约束输出可复用性换场景就得重写一套逻辑多处复用可调试性只能改措辞试运气可以写测试用例回滚版本增强路径靠感觉微调靠迭代文件版本打个比方Prompt 像你口述做菜步骤每次做完都要重新解释一遍“盐少许”到底是多少Skill 像是把菜谱、食材预处理脚本和标准摆盘图全装进一个盒子你只要说“来一份水煮鱼”它就把完整流程跑完。这个差异背后其实是编程思维的入场。写 Skill 时不只是在“说话”而是在定义输入、处理流程、输出格式、边界条件。你开始像设计接口一样设计 Agent 的行为。1.3 Skill 带来的三个直接收益第一个收益是确定性。Skill 里的审查清单和输出模板是写死的Agent 再怎么发挥最终输出结构基本可控。第二个收益是复用性同一个审查 Skill 可以用于个人项目、团队项目、不同语言的项目只要改一下 references 里的规则文件就行。第三个收益是可迭代Skill 出了毛病直接改文件、加测试不需要向模型“解释清楚”改完重跑就是。所以如果你发现自己某个 Prompt 已经用了超过三次每次还在手动微调它就该升级成 Skill 了。这比我后面讲任何原理都更重要——判断该不该做 Skill不是看它多酷而是看它是否值得固化。2. Skill 的结构与设计原则从零开始规划2.1 一个 Skill 的标准目录结构SKILL.md、scripts、references不同 AI 编程工具对 Skill 的具体格式要求不完全一样但主流做法已经收敛到一套近乎通用的结构。一个最小可用的 Skill 目录大致长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── scan.py ├── references/ │ ├── checklist.md │ └── examples.md └── assets/ └── template.mdSKILL.md 是入口文件Agent 会优先读这个文件判断当前任务能不能用这个 Skill、应该怎么用。scripts 目录放辅助脚本用于执行那些模型不擅长的确定性工作比如正则扫描、文本提取、文件统计。references 是知识库放详细的专业清单、规则说明避免 SKILL.md 又臭又长。assets 放模板或者示例输出。这个结构借鉴了 Spring AI 2.0 里技能加载器的思路先通过描述匹配技能再加载脚本和引用资料最后由模型根据指令生成结果。像豆包、Codex 这些工具虽然不叫 Spring AI但底层逻辑都类似。2.2 写好 SKILL.md 的关键把指令、示例、边界写清楚SKILL.md 才是 Skill 的灵魂。它不是让你写一篇论文而是写一份“给 Agent 看的操作手册”。我写了几十个 SKILL.md 之后总结出四个必须覆盖的模块技能名称和适用场景让 Agent 一眼判断“这个技能该不该用”。输入要求明确任务传入什么格式、来源是文件还是粘贴文本。执行步骤按顺序列出处理流程每一步要尽量具体。输出格式定义标题、字段、排序规则最好给一个参考示例。这里最容易犯的错是“边界模糊”。比如我在一个翻译 Skill 里写了“负责把中文材料翻译成英文”结果 Agent 把编程注释里的中文也翻了一遍注释的语义全被破坏了。后来我加了一句“仅处理用户明确要求翻译的文本块保留代码和文件路径原文”问题就解决了。给一个简化的 SKILL.md 开头片段--- name: python_code_review description: 对 Python 项目做静态代码审查输出安全、性能和维护性问题清单。仅处理用户明确指定的文件或路径。 --- # Python Code Review Skill ## 触发条件 - 用户要求审查 Python 代码 - 用户提到 review 或检查代码质量 - 输入可以是本地文件路径也可以是粘贴的代码块 ## 执行步骤 1. 先读取目标文件优先使用 scripts/scan.py 做静态扫描 2. 结合 references/checklist.md 中的审查规则逐项检查 3. 按输出格式生成报告对高风险问题给出修复建议这个格式简单直接Agent 不需要理解你的深层意图它只需要知道“什么时候用、怎么用、输出什么”。2.3 设计 Skill 的三个原则单一职责、最小依赖、可观测输出第一个原则是单一职责。一个 Skill 就做一件事。我一开始写过一个大而全的“代码助手”Skill既审查代码又生成提交信息还兼顾写测试最后 Agent 每次都乱选子任务。拆成三个独立 Skill 后问题立刻消失。不要偷懒拆开才可控。第二个原则是最小依赖。Skill 里的脚本尽量使用标准库不要依赖需要额外安装的第三方包。原因很简单你换个环境部署的时候pip install 装不上就直接卡死。我自己被这个坑过一次那个依赖只在特定环境下能装内网部署时整整浪费了半天才排查出来。从那以后凡是能用标准库实现的功能我绝不引入外部依赖。第三个原则是可观测输出。Skill 生成的最终结果必须结构清晰、字段固定。这样便于你检查也方便后面再接一个 Skill 继续做二次加工。比如审查报告第一行写风险等级第二行写文件位置第三行写修复建议——这就是给后续自动化留了后门。2.4 从 Prompt 改造为 Skill 的四步法如果你手上已经有一段高频使用的 Prompt改造起来其实不难。按下面四步走审视你的 Prompt 历史找出过去一个月内重复使用超过三次的片段这些就是改造候选。把 Prompt 拆成“知识”和“指令”两层。事实类规则、检查清单、示例这些属于知识放进 references执行动作、输出格式、触发条件属于指令写进 SKILL.md。找出其中可以用脚本代替的部分。比如“扫描代码里的 TODO 标记”“统计函数数量”“提取所有文件路径”这些重复性劳动交给脚本比交给模型稳定得多。准备至少三个测试输入模拟真实场景运行观察输出的稳定性和准确性然后回头修改 SKILL.md 的措辞。这套四步法我用了整整一个季度效果很稳定。它本质上是把一个“凭感觉说话”的过程变成了“设计系统”的过程。3. 实操案例手写一个“代码审查”Skill 的全过程3.1 场景定义与需求边界这里我完整演示一遍我近期在 Codex 这类 AI 编程工具里反复调试通过的“Python 代码审查”Skill 的诞生过程。先定义需求输入是本地 Python 文件路径输出是结构化审查报告覆盖安全风险、性能隐患、可维护性问题三个维度每条问题带风险等级、文件位置、修复建议。边界条件是我反复推敲出来的只做静态审查不执行测试用例只检查用户明确传入的文件不自动扫描全项目不修改源码只输出建议。边界为什么重要因为没有边界Agent 可能自作主张跑去审查 config 文件甚至把依赖文件也列进来。我第一次跑这个 Skill 时它把 venv 里几十个文件全审查了一遍差点把我气笑。加上“只处理用户明确指定的文件”之后它才老实下来。3.2 构建 SKILL.md把要求写成 Agent 能读懂的文档我实际写的 SKILL.md 很短核心就是触发条件、审查规则、输出格式三块。审查规则没有堆在 SKILL.md 里而是放进了 references/checklist.md因为 Agent 可以分段读取引用资料不会一上来就被信息淹没。输出格式部分我给了一个明确的骨架## 输出要求 按以下格式输出按风险等级从高到低排序 - 风险等级[高/中/低] - 位置[文件路径:行号] - 问题描述[一句话说明] - 修复建议[具体可操作的建议] Example: - 风险等级高 - 位置src/main.py:42 - 问题描述直接拼接外部输入构造 SQL 查询 - 修复建议改用参数化查询如 cursor.execute(SELECT * FROM user WHERE id?, user_id)给示例这件事特别关键。我一开始没给Agent 输出的格式每次都不一样有时用表格有时用代码块有时用纯文字。加了这个示例之后输出结构基本固定在九成以上。3.3 编写辅助脚本让 Skill 有“手”可用这个 Skill 里我用了一个 Python 脚本负责扫描代码里的常见标记和安全风险点。脚本不用复杂关键是能输出结构化信息供 Agent 后续拼接#!/usr/bin/env python3 静态扫描脚本提取 TODO/FIXME、函数定义和明显安全风险 import re import sys from pathlib import Path def scan_file(path: Path): results {todos: [], functions: [], risks: []} for lineno, line in enumerate(path.read_text(encodingutf-8).splitlines(), 1): if re.search(r\bTODO\b|\bFIXME\b, line, re.I): results[todos].append((lineno, line.strip())) if re.search(r^\s*def\s\w, line): results[functions].append((lineno, line.strip())) if re.search(r\beval\(|\bexec\(|pickle\.load, line): results[risks].append((lineno, line.strip())) return results if __name__ __main__: for arg in sys.argv[1:]: p Path(arg) if p.is_file(): print(p, scan_file(p))我特意解释一下这里的设计意图。TODO 和函数定义类信息模型自己看代码也能找出来但脚本做这件事更快更准确而且不会漏。安全风险里的 eval 和 pickle.load 属于模式匹配类问题用正则扫一遍是最可靠的模型反而可能因为上下文干扰而漏掉。这个脚本的输出是给 Agent 当“证据链”用的。SKILL.md 里明确写了“先运行 scripts/scan.py然后把扫描结果作为审查报告的输入”这样就形成了一条自动化流水线脚本负责找事实模型负责理解背景和写建议。3.4 实测记录与效果对比Prompt 与 Skill 的差距有多大我用同一个 2000 行的小项目分别跑了原始 Prompt 方案和这个 Skill 方案各跑了五轮结果如下实验项直接用 Prompt用 Skill平均准备时间十几分钟拼接上下文30 秒指定路径输出格式一致性五轮有三种格式五轮基本一致关键风险命中次数两次漏掉高风险 eval 调用五次全部命中是否漏审文件第二轮漏了一个核心模块无遗漏后续修改成本每次都要重贴 Prompt改一行 checklist 即可这个结果并不意外。Prompt 方案的输出质量基本取决于模型当时的注意力分布而 Skill 方案里的脚本保证了大项扫描的完整性SKILL.md 里的输出模板又约束了终稿结构。它俩不是一个维度的产品Skill 是带了控制逻辑的 Prompt。我还观察到一个现象直接用 Prompt 审查时模型很容易把“建议”和“问题”混在一起长篇大论地讲开发技巧Skill 版本里因为输出格式强制让它先列位置再写建议内容收敛了很多。4. 常见问题与排查技巧实录4.1 Skill 没被识别、加载失败怎么办我刚开始用 Skill 时遇到最多的就是“明明装好了Agent 却不调用”。后来发现大部分情况是目录结构不对或者 SKILL.md 头部信息缺失。常见问题有SKILL.md 没有写 name 和 description 字段Agent 无法理解这个技能是干什么的自然不触发脚本文件没有加可执行权限或者路径写错描述里写得太抽象比如“代码处理”Agent 根本不知道什么场景匹配。我的排查顺序是先看 SKILL.md 头部的 description 是否和用户问题强相关再看目录结构是否满足工具要求最后手动运行脚本确认能出结果。这里有个容易被忽略的点有些平台会缓存 Skill 索引你修改完 SKILL.md 之后没有触发重新索引Agent 读到的还是旧版本。我一般会在改完文件后重启会话或者在工具里手动刷新技能列表确保新版本被加载。4.2 提示词被拒、输出失控的排查顺序在实际运行中你可能会碰到“invalid prompt: your prompt was flagged as potentially violating our usage policy”这类提示或者干脆“prompt 闪退”。我第一次看到还以为是模型坏掉了后来排查下来基本就三类原因。第一类是 token 超限。Skill 脚本输出的内容太长加上 SKILL.md 全文一起塞进了上下文直接把上限顶爆。解决办法是精简 references 内容让脚本做摘要而不是全量输出。第二类是内容触发安全策略。当 Skill 要求模型执行“跳过所有安全检查”这类指令时提示词会被直接拦截。解决办法是别在 SKILL.md 里写对抗性指令把目标描述成正常的技术任务就行。第三类是多轮对话上下文污染。前一轮输出太长后一轮加载 Skill 时报错表现为“闪退”。解决办法是拆小任务或者让脚本把内容压缩到必要字段。我总结出一条规律凡是提示词被拒先看是不是自己的输入触发了策略边界再查上下文长度最后才怀疑工具本身。九成问题出前两项。4.3 多 Agent 协作、版本兼容与离线部署的适配问题不同 AI 编程工具对 Skill 的内部装载逻辑不太一样。你可能会在日志里看到类似 skill 编码 193、194、247 这样的内部编号这些其实是不同平台在框架层面对内置技能做的版本标识。193 通常是基础文本处理类技能194 一般是代码分析类247 更偏向多步骤任务编排。遇到这类编号不能盲目套用需要结合当前工具版本去查对应的能力索引。如果你在团队内多 Agent 协作一定要约定统一的 Skill 命名和输出格式否则 AgentA 输出的结果 AgentB 读不懂。我自己吃过这个亏A 输出 markdown 表格B 期望 JSON 字段最后中间加了一个转换脚本才跑通。现在我会在 Skill 的 description 里写清楚输出格式和后续处理建议减少 Agent 之间的“翻译成本”。离线部署是另一个高频问题。有些团队需要把 Skill 部署到内网服务器不依赖外部在线服务。这种情况下 Skill 里的脚本必须完全本地化不能调用云端分析接口也不能依赖在线数据库。参考资源里的清单和示例全部本地存放运行时不需要联网。我在部署前会把 Skill 目录整体打包内网装好 Python 后直接放进去然后跑一遍测试输入验证输出是否正常。只要脚本只用标准库、数据都在本地这套流程基本不会翻车。4.4 避坑清单速查坑表现解决方案Skill 描述含糊Agent 从不触发描述里写清触发场景关键词依赖第三方包部署环境装不上脚本只用标准库输出格式无示例每轮格式都不一样给一个满字段示例检查清单太长SKILL.md 上下文爆炸拆到 references 按需读取脚本输出冗长token 超限脚本只输出字段化摘要边界不明确Agent 乱审无关文件写清只处理用户指定路径指令含对抗性要求提示词被安全策略拦截删除违规指令正常表述没有测试用例改完不知好坏准备三组固定输入做回归这张表基本覆盖了我踩过的所有坑你在自己的 Skill 设计里可以直接对照着查。最后再分享一点个人体会Skill 不是越复杂越好。我见过有人为了写一个“语音转文字”技能硬塞了 300 行 Python 脚本最后还是靠一个系统命令解决的。真正好用的 Skill往往是你已经重复了一百次、熟到闭眼都会做的任务——把它固化下来你才有精力去琢磨那些还没有答案的事情。我现在的工作习惯是任何任务完成三次之后就把它列入 Skill 候选清单每周抽半小时整理一次。这种积累方式会让你的 AI 编程工具越用越顺手而不是每次都在原地重新教它。希望这套从 Prompt 到 Skill 的设计框架能让你少走一点我走过的弯路。
