最近整理自己常用的 AI 编程工作流时我把手头一堆散落的 SKILLClaude Code、Codex、Cursor 这类 AI 编程工具里的技能包全部翻出来重写了一遍过程中沉淀出一套命名为“DZS--SDF”的 SKILL 编写模板。如果你也写过 SKILL应该能体会那种痛苦写的时候脑子里思路很清晰隔两周回来看却完全不知道当初要表达什么或者同一个功能在两个项目里各写一遍格式和风格完全不统一更常见的是精心写了一堆指令放进 Agent 里却没达到预期效果。DZS--SDF 就是冲着这些问题去的。这篇文章会把这套模板的完整思路、每个字段的设计原因、实际编写步骤以及踩过的坑全部摊开讲清楚适合正在做 Claude Code、Codex 等工具 Skill 开发的人也适合刚接触 Agent 技能编程、想建立自己一套规范写法的朋友。1. 模板是怎么来的从三份失败 SKILL 里提炼出来的结构我最早写 SKILL 完全是“爽文式”写法想到什么写什么。第一版“代码审查 SKILL”洋洋洒洒写了三千字把代码规范、安全审查、性能分析甚至数据库设计全塞进去了结果实际跑起来Agent 每次执行都像开盲盒有时候揪着格式化问题说一堆有时候又只字不提安全问题。后来我才意识到问题不在 AI 能力而是 SKILL 本身的结构太模糊它根本不知道在什么场景下应该重点做什么。1.1 为什么要给 SKILL 做模板化先明确一个概念SKILL 和普通提示词最大的区别在于它是一套“可复用的程序化技能”而不是一段对话文本。好的 SKILL 应该像一份设备操作手册工人看一眼就知道什么时候用、用什么工具、按什么顺序操作、什么情况绝对不能做。但大部分人写 SKILL 还是在写“提示词”缺少边界、输入输出定义和依赖声明。这种写法最直接的后果就是不可控同一份 SKILL 在这个项目里好使换个项目就失灵今天好使下周就退化。模板化的第一个好处是强制收敛。我不会让你天马行空地描述“希望 AI 做什么”而是要求你先回答“这个 SKILL 在什么条件下能被触发”“它需要哪些输入”“它绝对不做什么”。这一串问题问下来差不多一半的烂 SKILL 就已经被淘汰了——因为它们根本回答不出唯一且明确的目标。第二个好处是可维护性。SKILL 是需要迭代的我个人的经验是一个真正能用的 SKILL 至少要改三版以上。没有模板约束的情况下每一版都是推倒重来而用模板写的时候只需要改“步骤区”或“细节区”的某几段其他结构保持不动版本对比非常轻松。第三个好处是团队协作。如果你跟我一样有跟同事共享 SKILL 仓库的需求结构统一带来的优势会非常明显。大家在同一个框架底下补充内容合并起来基本不会有“这块内容该放哪”的争论。1.2 这个模板为什么叫 DZS--SDF起名这件事纯粹是顺手。当时我在整理自己的知识管理方法手里正好有一套“定向-准则-结构-步骤-细节-反馈”的框架拆开重组之后发现它几乎完美匹配 SKILL 编写的完整链路就缩写成了 DZS--SDF。这套模板一共六个环节分两段前段 DZS 解决的是“这是什么、边界在哪、长什么样”后段 SDF 解决的是“怎么跑、写多细、怎么自我闭环”。我特别想把前段和后段拆开是因为 90% 的 SKILL 问题都出在“前段不清楚、后段太潦草”。很多人一上来就钻进细节结果 SKILL 的名字、触发条件、适用范围全是含糊的Agent 经常在不该用的时候调用它或者调用了却在执行方向上走偏。2. DZS--SDF 模板的六个关键环节拆解这一节是全文的核心我会把模板里的每个字母对应什么内容、为什么要这样设计、每个部分理想状态是什么样全部讲透。你会看到它比我前面提到的“字段清单”要更讲究设计逻辑而不仅仅是填空题。2.1 定向不是起个好名字而是给 AI 设一个“触发坐标”定向是模板的第一个字母 D也是我建议你写任何 SKILL 时第一件要做的事。这里说的“定向”分三层定义技能解决的核心问题、定义触发场景、定义隔离边界。拿一份“日志分析 SKILL”举例。如果定向没有做透你写出来的可能是“帮助分析系统日志找出错误并给出建议”——放到 Agent 里它可能在你聊天聊到一半提到“日志”这个词的时候就强行触发或者分析完只给你一句“系统日志中存在错误建议查看错误详情”这种废话。做定向的时候我会强制自己回答三个问题第一这个 SKILL 的输入是什么比如原始日志文本、日志文件路径、某个时间段第二这个 SKILL 的典型输出是什么错误摘要、根因分析、处理建议第三什么情况下绝对不触发比如没有日志输入、日志少于 3 条、用户只是闲聊把这三个问题写进 SKILL 的描述字段里Agent 在触发和编排的时候才会有真正的“坐标感”而不是靠全文语义猜。我的经验是定向部分宁可写得像“起诉书”一样冷冰冰也不要写得像“产品宣传页”一样热情洋溢。AI 不需要你夸这个技能多有用它需要你精确告诉它“什么时候该我上场”。2.2 准则给 Agent 装上“驾驶刹车”准则对应模板里的 Z。这一部分解决的是“哪些事情绝对不做”和“哪些原则不能妥协”。很多人写 SKILL 只写“要做的事”忽略了“不要做的事”这是隐患最大的地方。以代码生成 SKILL 为例我见过有人说“帮我写一个 Python 脚本实现数据清洗”AI 直接给它装了全部依赖还把文件覆盖了——因为 SKILL 里根本没规定“不得删除或修改非目标文件”“不得静默安装重量级依赖”。准则区建议包含三条主线安全边界不能执行哪些高危操作、行为边界回答风格与输出格式的硬性要求、质量边界最低完成标准。我在模板里的写法是让“准则”部分顶格排版每条准则一行允许加粗让 Agent 在读取时能够一眼扫完。这样做的用意是准则区的长度不超过十五行所有的禁止类指令集中在同一个区块Agent 对“红线”的感知会有明显提升这是我自己做了一轮对照测试得出的结论。2.3 结构像画建筑图纸一样搭出叙述骨架结构S是整个模板里看起来最“虚”实则最影响结果的部分。所谓结构就是把 SKILL 要呈现的全部内容划分成有逻辑顺序的段落并且约定每一段的职能。好比你写论文前先出提纲SKILL 也需要提纲才能保证 AI 在生成步骤时不跑偏。做结构时我习惯直接用一个自带的模板骨架不重复造轮子背景与目标两百字内交代清楚解决什么问题、希望达到什么效果工作流程按顺序列出 AI 在接到任务后要执行的阶段通常三到六步输出要求说明最终交付物长什么样格式、字段、结构示例与参考给出至少一个真实输入输出对或者一段参考风格异常处理遇到前置条件不满足时怎么办这个骨架的好处是它把 SKILL 的执行逻辑从“一段长文本”变成了“一个带环节的流水线”。AI 在读取结构时会更容易把工作流程中的步骤当作“必须按顺序执行”的任务链而不是可以自由发挥的指导意见。如果你写出来的 SKILL 每次执行都和猜谜一样先别怪模型不行回去看一眼结构区是不是用大段散文写的。2.4 步骤把“模糊的期望”翻译成“可执行的动作”步骤S是 DZS--SDF 里第一个 S。有了结构骨架之后步骤区要做的事情就是填充每一步的具体动作这是 SKILL 从“描述性”走向“程序性”的临门一脚。步骤写得好不好最直接的判断标准是把 SKILL 里的步骤交给一个完全不懂业务的新人他能不能照着做出来。写步骤的时候我会偏向“指令颗粒度”这个维度。颗粒度太粗AI 不知道先干什么后干什么比如“分析代码质量”这种描述就是典型的无效步骤颗粒度太细又把模型的推理空间卡死结果在处理真实场景时一看细节对不上就整个放弃执行。根据我这段时间的摸索一个比较稳妥的写法是每一步写清楚“动作 对象 产出的中间结果”例如“读取当前目录下所有 Python 文件不包含 test 目录生成待审查文件清单并标记每个文件的行数”。这样 AI 既知道要做什么也保留了自己选择合适的工具去实现的空间。步骤之间的连接词也建议从“然后”“接着”改成“在步骤 1 确认通过后”“将步骤 2 的输出作为步骤 3 的输入”。这种写法能让 Agent 明显更严格地按顺序执行我猜这是因为顺序语义在指令里被显式化了而不是存在于模型的“默契理解”里。2.5 细节示例、参数、异常分支一个都不能少细节D是决定 SKILL 有没有“灵魂”的部分。同样的结构、同样的步骤填进不同的细节跑出来的效果能差一个量级。在我看来最重要的细节一共有三种。第一种是参数说明。如果 SKILL 会接收变量比如日志文件的路径、目标代码的语言、生成报告的语言必须在细节区写清楚每个参数的类型、默认值、可选范围。我见过太多 SKILL 里直接用${code_file_path}这种变量但完全没告诉 AI 这个值应该由用户提供还是它在执行时自己发现结果模型只能猜。第二种是输入输出示例。无论 SKILL 多复杂我都会给一个最小可用的输入输出对。因为大语言模型本质上在做“模式匹配”一个高质量的示例比一百句“请你输出规范的报告”有效得多。比如写“自动生成周报 SKILL”与其反复强调“要结构清晰、言之有物”不如直接给一个真实的周报样本让模型照着这个样本的风格去写。第三种是异常分支。模板里我会留几行专门写“如果……就……”。比如“如果发现当前目录下没有 requirements.txt则停止执行并提示用户先创建虚拟环境”和“如果代码文件超过 20 个则优先扫描最近修改的 5 个”。没有异常分支的 SKILL 是一根捅到底的死脑筋遇到真实环境的变量就只能陷入自我怀疑。2.6 反馈给 SKILL 留一双能够“复盘”的眼睛最后一个字母 F 代表反馈。模板在最后一段会要求 SKILL 的作者写入“如何验证这个 SKILL 是否有效”以及“再次执行时的自检项目”。这一步几乎被所有人忽略但恰恰是 SKILL 能不能迭代进化的关键。我见过不少开发者写了 SKILL 就跑一次效果好就扔进去效果不好就直接删除完全没有沉淀的过程。反馈区可以写的内容包括该 SKILL 执行结束后应该输出什么指标来证明它成功了比如“报告包含根因分析且根因分析部分不少于两百字”或者当执行遇到特定错误码时下个版本应该如何调整。真正会写 SKILL 的人一定会在反馈区留下“上一版遇到了什么问题、这一版改了什么”的记录这本质上是给 AI 也给人用的 changelog。3. 实操记录用 DZS--SDF 从零写一个“代码审查 SKILL”前面讲了一堆设计逻辑这一节拿一个真实场景来走一遍完整流程。我选的例子是一个“代码审查 SKILL”不会选得太猎奇因为它几乎是每个做 AI 编程辅助的人都会用到的能力你能很直观地感受到模板每一块到底填了什么内容。3.1 第一轮定向与准则先写描述再写红线我建议的流程是先打开编辑器新建一个文件夹叫code-review-skill在里面建一个主文件SKILL.md。然后任何代码之前先把前三个要素写掉。--- name: code-review-skill description: 用于对指定目录下的代码文件进行结构化审查。触发时机是用户提出“代码审查”“review code”“看一下代码有没有问题”等明确指令如果用户只是闲聊代码话题或询问一般性编程建议不要触发本技能。 --- # 准则 - 不得删除、修改用户工作目录下的任何文件只能生成审查报告 - 不得运行存在副作用的命令比如安装依赖、执行测试除非用户显式授权 - 审查报告必须基于实际读到的代码内容禁止臆测代码逻辑 - 每个问题必须标注严重级别critical / warning / suggestion这部分写完后整个 SKILL 的边界就清楚了它只会做审查不会擅自改代码、装依赖而且触发的语义范围被收窄到“审查”这个动作。比起原来那种连“给我讲一下这段代码”都会误触发的情况这个版本的可控性好太多了。3.2 第二轮结构与步骤把审查过程做成流水线接下来是结构和步骤。我按照模板的骨架将审查流程拆成了五个阶段扫描文件、定位目标、逐项检查、汇总报告、输出建议。每个阶段都写清楚输入输出而不是简单写一句“审查代码”。# 工作流程 ## 步骤 1扫描代码文件 列出目标目录下所有源代码文件默认支持 .py/.js/.ts/.java/.go排除 test/、node_modules/、build/、dist/ 目录。输出文件清单及每个文件的行数。 ## 步骤 2确定审查优先级 根据文件行数和最近修改时间排序优先审查行数在 100~400 区间且修改时间最近的文件如果文件总数少于 5 个全部纳入审查。 ## 步骤 3逐文件审查 对每个文件执行以下检查 - 变量名与函数名是否符合项目命名约定 - 是否存在明显逻辑错误空指针、索引越界、无限循环等 - 是否泄露敏感信息API Key、密码、内部路径 - 异常处理是否合理 - 性能隐患循环内重复查询、无索引访问等 ## 步骤 4生成审查报告 按“文件级别摘要 问题列表 严重级别 修复建议”的结构输出 Markdown 报告。 ## 步骤 5输出终稿 在报告的末尾添加一段“总体评价”用三句话以内总结代码质量如果存在 critical 级别问题用“建议暂停合并”这样的明确措辞标记。写到这里你会发现DZS--SDF 的步骤部分并没有要求 AI“自己想流程”而是把流程像食谱一样铺开。这样对模型来说试错成本最低尤其在 Agent 自动执行场景中结构化的步骤会显著减少中途偏差。注意我在步骤里加了一个“审查优先级”的环节这是从实际项目中得到的教训——如果没有这个环节AI 常常会挑最简单的文件审查挑软柿子捏而对真正复杂的大文件反而忽略。3.3 第三轮细节与反馈写示例、定参数、预留自检步骤写完模板要求我补充示例和参数。对我来说这一步是“让 SKILL 真正从可用变成好用”的分水岭。我给这个 SKILL 设置了一个可选参数path如果用户不指定目标路径它默认使用当前工作目录如果传入了相对路径则以此为审查起点。示例部分我放了一个非常短的输入输出对是一段有明显问题的 Python 代码def get_user(user_id): conn get_db_conn() result conn.execute(SELECT * FROM users WHERE id user_id) return result.fetchone()针对这个输入SKILL 需要输出的报告里至少包含SQL 注入风险critical、未关闭数据库连接warning、函数缺少返回空值处理suggestion。这段示例的价值是向模型展示“发现问题”的颗粒度它不应该满足于说“这段代码有一个安全问题”而是要给出具体的风险类型、危害和修复建议。反馈区我是这样写的# 自检与迭代记录 - 执行完成后确认报告是否包含具体文件路径、行号、严重级别、修复建议 - 如果用户反馈“报告太笼统”下一版应增加“问题代码片段截取”的要求 - 如果用户反馈“没发现关键问题”下一版应增加对跨文件调用的追踪检查这段写在 SKILL 文件末尾并不参与实际执行但当我下次迭代时它就变成了我的改版清单。一件小事说明它的价值有一次我把这个 SKILL 丢给同事共用他执行完给我发截图说报告里没有行号我翻到反馈区果然当初记录过这一类问题第三版就加了“所有问题必须定位到具体行号”的硬性要求。3.4 关于 dependencies 文件的补充说明我注意到不少人在搜“python skill 缺少 requirements.txt 或依赖声明”这样的关键词看起来很多人在 SKILL 里需要运行 Python 代码却搞不清楚依赖该写在哪。这里我展开说一下在 Claude Code 和 Codex 这类工具中SKILL 可以附带一个dependencies.txt或requirements.txt文件用来声明该 SKILL 运行过程中需要引入的 Python 包。比如做日志分析 SKILL如果要用pandas和matplotlib画趋势图你需要在描述区写明需要安装这些依赖或者放一个requirements.txt文件让运行环境自动识别。我个人的习惯是尽量把对第三方包的依赖降到最低。如果只是做文件处理和格式化优先用标准库只有确实做数据可视化、复杂计算的时候才引入外部包。因为每多一个依赖你的 SKILL 换到新环境时就会多一分“跑不起来”的风险。同时在 SKILL.md 的描述区明确写出“需要环境已安装 Python 3.10 和以下包pandas2.0.0”这样比单纯放一个 requirements.txt 更稳因为有些 Agent 并不读取依赖文件只读主描述文件。4. 这个模板在真实任务里的适配方法如何从通用模板变成领域专用 SKILLDZS--SDF 的六个环节是通用骨架好处是几乎所有类型的 SKILL 都能套坏处是如果你不结合具体领域做二次适配写出来的东西还是会太平。这一节我想聊几个典型领域的适配思路每一个都是正在被大量人尝试的真实方向不是凭空捏造。4.1 面向数学建模的 SKILL 怎么写数学建模类的 SKILL 最近确实热说明很多人想让 AI 辅助完成建模比赛或科研任务。但用通用模板写出来的数学建模 SKILL往往会把“模型选择”这一步做得特别虚。按 DZS--SDF 的框架来拆我会把步骤区设计成先读题并提炼目标函数与约束条件再根据数据规模选择候选模型回归、时间序列、分类树、神经网络然后完成特征工程和模型训练最后输出论文格式的建模说明。关键在细节区的示例必须给一个完整的最小建模流程哪怕是一个简单的线性回归也要写全让 AI 有可参照的“手感”。4.2 面向日志分析的 SKILL 怎么写日志分析 SKILL 是最适合用模板的领域之一因为日志分析本身就是一个高度流程化的动作。先用“定向”约束触发条件比如只在用户提供日志内容或指定文件时触发用“准则”禁止 AI 去修改日志文件本身然后步骤区设计成“读日志 → 按时间分组 → 提取错误级别 → 统计频率 → 关联上下文 → 生成分析报告”。细节区尤其要强调时间戳的解析格式否则 AI 遇到不同格式的日志会直接罢工。我自己写过一份 Nginx 错误日志分析 SKILL实际使用中最大的坑就是日志格式的多样性所以模板里我专门加了一条准则“如果无法确定日志格式先输出日志片段并咨询用户而不是强行猜测”。4.3 测试用例生成的 SKILL 怎么写测试用例类的 SKILL 很考验对“边界条件”的描述而这恰好是 DZS--SDF 的“细节”区擅长处理的。除了让 AI 根据函数签名生成用例我建议在结构区单独加一节“输入域分析”要求 AI 列出合法输入、非法输入、边界值、空值、超长值和并发场景。然后步骤区按“分析函数签名 → 识别依赖 → 生成基本用例 → 补充边界用例 → 标注预期结果”的顺序执行。反馈区可以写上“如果生成的用例无法在现有测试框架中运行应检查框架版本并重新生成”。4.4 带“人味”的写作类 SKILL 怎么调你可能也刷到过“去 AI 味”“humanizer skill”这类词。这说明写作类 SKILL 的需求一直很大但也是最容易写砸的。用 DZS--SDF 的视角看这类 SKILL 最容易踩的坑是把“准则”写得太死板比如“必须使用短句”“不能使用被动语态”结果生成的文章会散发一股机械感因为它们把语气和风格在结构层面就锁死了。我的做法是结构区只搭叙事框架步骤区要求“先写初稿再逐句口语化改写”细节区给一篇同一作者写的真实文章作为风格参考反馈区反复记录读者反馈。通过框架给约束、通过示例给感觉而不是通过规则给铁链。5. 常见翻车场景与排查方法为什么我的 SKILL 还是不听话写 SKILL 这件事真正拉开差距的往往不是写得多漂亮而是遇到问题后能不能快速定位是哪个环节出了问题。我把从实践中遇到的典型问题整理成了一个速查表适合在 SKILL 不按预期运行时逐条对照。现象大概率出问题的环节排查与修复建议SKILL 该触发时不触发定向检查 description 中的触发词换成用户在真实对话中更可能说的口语化表达SKILL 不该触发时乱触发定向在描述区增加“不要触发”的负面条件并在准则区补充红线执行过程跳跃、顺序混乱结构 / 步骤把段落式描述改成编号步骤加入“步骤 N 通过的先决条件”说明输出内容太笼统、千篇一律细节补充输入输出示例尽可能提供真实样本让模型有模仿对象执行时擅自改文件或装依赖准则增加禁止类规则比如“不得修改工作目录文件”“未授权不得安装依赖”换了一个项目就不能用了定向 / 细节检查描述中是否绑定了特定项目路径、语言或框架如果是显式改为可配置参数跑完后感觉没有沉淀反馈检查是否写了自检与迭代记录把用户反馈追加到反馈区这张表并不是万能药但能覆盖我见过的大部分问题。举个例子有个朋友跟我说他的 SKILL“非常不稳定有时候能跑对有时候不能”我让他把 SKILL.md 发给我第一眼就发现在描述区里写着“处理各种代码文件”触发条件宽得吓人。改成“仅处理用户指向的.py/.js/.ts文件未指定文件时先列举目录内容并请用户确认”之后稳定性立刻上来了。除了上述问题我还经常被问到“skill 和 agent 到底有什么区别”。我习惯用一个最简单的方式来区分Agent 是“执行者”它负责调度、决策、调用外部工具而 SKILL 是“说明书”它告诉 Agent 某类具体任务该怎么干。一个好的 SKILL是 Agent 这台车上的转向和刹车系统——底盘和发动机是 Agent 本身SKILL 负责让它精准转向。所以你在写 SKILL 的时候不要试图写成一个无所不能的 Agent而是要写成“一份任务级的手册”。另外一个很多人忽略的点SKILL 并不是越长越好。我刚开头写的第一版代码审查 SKILL 有三千字后来精简到一千二执行稳定性反而提升了。因为太长的 SKILL 会让模型在读取时丢失重点尤其是把关键操作埋在段落深处的时候。如果你发现 SKILL 的效果飘忽不定先别加内容试着删减到只剩“定向、准则、步骤、示例”四块很多时候问题自己就解决了。6. 一些关于工具选型和模板复用的思考最后一部分我想聊聊 SKILL 的跨工具与团队复用问题因为这直接关系到你花半天写出来的东西能不能沉淀出长期价值。目前主流的 AI 编程工具基本都支持类 SKILL 的目录结构不同工具之间只是加载方式和字段命名略有差异。DZS--SDF 模板在设计上不绑定任何特定工具核心文件就是SKILL.md外加一个可选的依赖声明文件所以换工具迁移时只需要调整少数头部字段大部分内容都能直接复用。6.1 如何让一个 SKILL 适配多种工具我用 Claude Code 写过一个“日志分析 SKILL”后来想迁移到 Codex 上只改了两处把权限声明的方式换成了 Codex 的指令格式以及把命令执行的前缀做了替换。其余描述区、步骤区、示例区完全保留。这件事给我一个启发SKILL 的编写规范应该尽量与工具解耦把重心放在“任务的逻辑结构”上而不是放在“某个工具的 API 怎么调用”上。DZS--SDF 模板的核心字段全部围绕任务逻辑展开所以天然具备跨工具复用的基础。如果你担心换工具后又要重写一遍最聪明的办法是在一开始就让 SKILL 的内容不依赖任何特定的 Agent 产品术语。6.2 团队沉淀 SKILL 的协作建议如果你所在的小团队也想建一套自己的 SKILL 仓库我强烈建议在每个 SKILL 的文件头维护一段metadata记录作者、创建时间、适用项目、迭代版本。然后建立一个简单的贡献规范任何人修改 SKILL 时必须在反馈区追加一条记录说明改了什么、为什么改。这件事看起来繁琐但只要你坚持一个迭代周期就会发现 SKILL 质量的提升速度远超各自为战的阶段。我还见过一些人用“给模型写 SKILL”来反向提升自己的业务理解能力我觉得这是特别划算的投资。因为 DZS--SDF 模板逼着你把模糊的经验拆成清晰的流程你写着写着就会突然意识到原来有些任务自己之前也没有真正想清楚。这种“以教代学”的效果算是这套模板带给我的意外收获。最后再多说一句我写 SKILL 时踩过最大的一个坑就是“贪多求全”总希望一个 SKILL 能覆盖所有情况结果每个分支都没有打磨到位。DZS--SDF 的设计本身就是反着来的——它要求你把目标收窄、把边界画清晰、把细节做透彻。如果你也是那种一写 SKILL 就忍不住想“再加一个功能”的人我真心建议你试一次“砍到只剩核心场景”的写法体验一下什么叫少即是多。写一个能精准解决一个问题的 SKILL远比写十个什么都能沾一点却每次都跑偏的 SKILL 有价值。
