先说一个让我头疼了很久的真实场景。我一直在维护自己的一套 AI 编程辅助 Skill 文件用它来约束大模型按固定的方式生成代码。结果在一次 Python 数据处理脚本的生成任务里我给 AI 塞了一份写满约束的 SKILL它却在对话里绕了三轮每次都回“好的我现在开始生成”然后交出来一堆解释性文字代码块空空如也。那一刻我明白问题或许不在 AI 能力而在我写的 SKILL 本身就是个“反执行”的结构。这篇文章就围绕我对 SKILL 的这次重新设计来写记录怎么把它从“堆需求”改成“框架细节”的完整调试验证过程其中一部分重点就是 AI 反复不执行代码这件事到底该怎么排查、怎么修。1. 为什么传统 SKILL 会遇到“说了不执行”1.1 先搞清楚 SKILL 到底是什么SKILL 这个概念在不同场景里有不同含义在 EDA 领域它是一种类 Lisp 的脚本语言在 AI Agent 实践中它是一种“技能包”。我这里说的 SKILL是指你交给 AI 的那套任务说明文件你可以把它理解成 Agent 体系里的“岗位说明书”里面装着模型执行任务时遵循的规则、步骤、输入输出约定和禁止事项。我在实际使用中见过很多人把 SKILL 直接当成“长篇提示词”来写觉得只要把需求写清楚AI 就会老老实实执行。这个认知在简单任务上勉强成立可一旦任务复杂度上来或者 SKILL 里同时存在多个约束条件AI 就会开始“选择性失明”——它只关注最开头几条或者只挑自己认为重要的信息来执行剩下的全被忽略。这其实不是 AI 故意偷懒而是模型在处理超长、扁平的指令序列时注意力会被稀释优先级判断也会失真。1.2 传统堆叠式 SKILL 的三个隐患我先复盘一下自己第一版 SKILL 的问题它很有代表性第一个隐患是注意力被稀释。当时我写了一份上百行的 SKILL里面包含“你要负责”“请不要”“必须确保”“如果……那么……”这些表述规则数量超过二十条。结果 AI 在执行时只记得开头几项后面的要求几乎全部丢失。比如我明确要求“输出文件必须带 output_ 前缀”它生成的代码里还是写死了输入文件名作为输出名完全无视我的约定。第二个隐患是层级扁平。整个 SKILL 就是一段连续排布的规则没有“目标-约束-执行-验收”的层次结构。AI 相当于拿到了一堆散装零件却没有装配图它只能靠自己的理解去组装组装结果自然不可控。后来我对比过几份工业级 Skill 定义发现它们普遍有清晰的分层结构最顶层一定是任务目标其次是输入输出规范再次才是具体执行步骤最后是验收标准和禁止项。一字排开的写法根本算不上 Skill只能算需求清单。第三个隐患是缺少可验证的验收标准。很多 SKILL 会写“生成高质量代码”“确保代码健壮”但从不定义什么算高质量、怎样算健壮。AI 没有量化标准自然没法判断自己有没有完成任务。我之前有一次让它生成批处理脚本它给了我一个“看起来能跑但有严重性能问题”的版本我追问它为什么它回了一句“我已经完成了你的要求”。问题就出在“要求”写得太抽象了。我印象很深的是当时我在网上也找过不少 Skill 模板最流行的结构是“你是 XX 专家你擅长 XX请根据以下需求完成任务”。这种模板适合对话式需求却不适合多步骤代码生成。后来我把它全部推翻重新设计了“框架细节”的结构执行成功率才算是真正稳定下来。2. 框架细节SKILL 设计的核心思路2.1 框架先行细节随后我理解的“框架细节”核心就两句话框架负责回答“做什么、按什么顺序做”细节负责回答“每一步具体怎么做、做到什么程度算完”。这个顺序不能反如果先堆细节AI 就会被碎片信息淹没失去对整个任务路径的把握。打个比方你去餐厅点餐菜单是框架它决定了“前菜-主菜-甜点”的流程但菜单不会告诉你宫保鸡丁要放多少克花生米那是细节。框架保证厨师不会把甜点端到你面前当主菜细节保证菜品味道稳定可复现。AI 执行任务也是同一个道理框架管方向细节管质量两者缺一不可。我在重构 SKILL 时第一步就是画任务流程图。比如一个“CSV 文件数据统计”的任务流程是“读取文件→检查数据→逐列计算→保存结果”。这个流程用文字写出来就是框架。然后把每一环节展开补充“用什么函数读取、空值怎么处理、输出编码用什么”这类细节。这样一来AI 的执行路径就非常清晰想跑偏都难。2.2 SKILL 的推荐结构经过这轮调试我沉淀了一套 SKILL 编写结构现在做任何任务我都会按这个结构来组织任务目标用一两句话说明任务要达成的最终效果必须可量化。输入清单列出 AI 需要接收哪些输入参数以及输入缺失时的处理方式。执行步骤把任务拆分为可验证的步骤每步有明确的输入、操作和输出。输出规范规定交付物的结构和格式比如代码放哪里、运行示例放哪里。验收清单列出完成后必须满足的检查项让 AI 能自查。禁止事项明确列出不能做的事情数量控制在三条以内。这个结构不是拍脑袋想出来的是在反复调试中一点点试出来的。每次 AI 执行异常我都会回头审视 SKILL看是哪个部分出了问题。后来我发现90% 的“不执行”都出在执行步骤不清和输出规范缺失上所以我特别重视这两块。尤其是执行步骤一定要细到“每一步之后 AI 应当输出什么”这样就算它走错了我也能立刻从回复里看出来。3. 按 SKILL 生成代码的完整实操记录3.1 这次要完成的任务为了把这次实践记录完整我重新搭了一个测试场景。任务目标是让 AI 根据 SKILL 生成一个 Python 脚本功能是读取一个名为 data.csv 的时间序列数据文件对每一列计算均值、最大值、最小值然后把统计结果保存为一个新的文件 output_data.csv。任务本身不难但要求很明确使用 pandas 的 read_csv 读取数据。对非数值列要跳过但必须输出提示信息。输出文件必须使用 utf-8 编码避免中文乱码。脚本最后要附带一条可直接运行的示例命令。这个任务是我故意选的因为它能够暴露出 AI“不执行”的几乎所有常见问题。比如只解释不写码、忽略编码参数、输出文件和需求不一致等后面都会一一遇到。3.2 第一版 SKILL只有框架没有细节第一版 SKILL 我写得很简单结构只有框架没有细节任务目标生成一个 Python 脚本读取 data.csv统计每列均值、最大值、最小值保存到 output_data.csv。 输入data.csv。 执行步骤 1. 读取 CSV 文件。 2. 计算每列统计值。 3. 保存结果。 输出规范 - 代码放在 python 代码块中。 - 附带运行示例。 禁止事项 - 不要修改输入文件。这版 SKILL 看起来要素齐全运行后问题却非常多。AI 确实生成了一个完整脚本但 read_csv 没有指定编码遇到含中文路径的输入文件直接报错输出文件名也没有按我预期的 output_data.csv 来命名而是擅自改成了 statistics.csv更离谱的是它生成的“运行示例”是一段伪代码根本没有可执行性。3.3 第一轮测试暴露的问题我拿第一版 SKILL 跑了一轮测试结果可以总结成一张问题表问题类型具体表现原因编码缺失read_csv 未指定 encoding细节约束不足文件名被修改输出文件被改名输出规范不够明确示例不可运行附带的运行命令是伪代码验收清单缺失跳过列未提示非数值列被静默忽略执行步骤缺少分支描述这一轮测试让我认识到框架只能解决“AI 不会走错大方向”的问题没法解决“小细节处处踩坑”的问题。要想让 AI 生成能直接跑起来的代码必须把细节补进去。带着这个结论我开始第二轮优化。4. AI 反复不执行的全程调试实录这一节是文章的重头戏也是标题里“AI 反复不执行”这个问题的完整记录。我把过程拆成了五轮每一轮都有具体的修改动作和验证结果你可以照着这个思路排查自己的 SKILL。4.1 现象描述AI 在“空转”第一次发现 AI“不执行”是我给了一份比上一节更复杂的 SKILL 之后。任务还是生成代码但 SKILL 里增加了一堆“注意事项”比如“要考虑代码性能”“要考虑异常处理”“代码风格要统一”。结果 AI 在对话里绕了一大圈先输出一段“我理解你的需求”再输出一段“我的实现思路”然后停在了“思路”这一步。我催它“生成代码”它回了一句“好的我现在为你生成”然后又开始重复思路。整个过程就像一台发动机在原地空转转速很高但车子一步都没动。后面我试了十几轮每次都是这个模式AI 输出理解输出计划然后停住。它不会得出结论也不会给出实质性的代码内容。4.2 第一轮排查指令太多优先级不明确我做的第一个动作是排查指令优先级。我把 SKILL 从头到尾读了一遍发现自己写了二十多条要求有性能方向的有风格方向的有异常处理方向的还有“不要问用户、直接做”的。这些要求单看都没问题但混在一起就让 AI 失去了优先级判断力。它不知道哪个要求该先满足索性选择了一种最稳妥的执行策略——先描述计划等用户确认。这个现象在心理学上跟“选择悖论”有点像选项过多反而让人无法决策。AI 虽然没有真实意识但它在庞大且互相干扰的指令集合面前很容易陷入“什么都想做结果什么都不做”的状态。解决办法是做减法。我删掉了所有与“生成一个可运行脚本”无关的要求只保留一个核心目标并把它放在 SKILL 最前面。修改后测试AI 终于开始输出代码了虽然还有一些细节错误但至少“不执行”的现象消失了。4.3 第二轮修改把“生成代码”改为“按顺序执行”第一轮做完减法AI 偶尔还是会当场摆烂。我进一步对比了两次对话的差异发现一个关键点我在 SKILL 里用的是“生成代码”这个目标性表述。对 AI 来说“生成代码”既可以指“写出代码”也可以指“给出生成代码的方案”。它选择后者严格来说不算错误但不符合我的预期。这个发现让我调整了措辞。我把 SKILL 里的“生成代码”改成了“按以下顺序执行每个步骤每完成一步在回复中输出当前步骤的结果”。这个改动看起来只有几个字的变化但对 AI 的行为影响极大。它开始真正“分步执行”先输出“读取 data.csv 成功”再输出“计算完成”最后输出“已保存结果”每一步都有实质输出。这个技巧的原理是把抽象目标替换成可验证的过程指令AI 就能明确知道自己在哪个节点、下一步该做什么而不是把任务当成一次“论文式回答”。4.4 第三轮修改用细节消除歧义AI 开始执行之后我遇到了另一类问题它执行了但执行结果跟需求不一致。比如我要求输出文件名必须是 output_data.csv它生成代码时写死成了 data_statistics.csv我要求运行示例必须是可执行的命令它给的是注释文字。这类问题说明 AI 虽然理解了框架但在细节层面仍在自行补全假设。我的解决办法是给关键位置全部加上细节约束。首先是输入输出文件名在 SKILL 里直接用具体文件名替代模糊描述其次是编码参数明确写出“read_csv 时指定 encodingutf-8”再次是运行示例要求“必须是以 python -c 开头的一行命令且可以直接复制到终端执行”。这些细节加上之后AI 生成的结果一下子就“听话”了。4.5 最终稳定版 SKILL经过前三轮修改SKILL 最终定型。下面是一份完整版本你可以直接参考# SKILL 时间序列统计脚本生成器 ## 目标 生成一个数据处理脚本 script.py输入 data.csv输出统计结果到 output_data.csv脚本必须可直接运行。 ## 输入 - input_file: data.csv - output_file: output_data.csv ## 执行步骤 1. 使用 pandas.read_csv 读取 data.csv。 1.1 若文件不存在或读取失败输出错误信息并停止。 1.2 若文件为空输出空文件提示并停止。 2. 对每一列计算 mean、max、min 三个统计值。 2.1 跳过非数值列但必须在回复中注明跳过了哪些列。 3. 将统计结果保存为 output_data.csv。 3.1 使用 encodingutf-8 写入避免中文乱码。 3.2 保留原始列名。 ## 输出规范 - 所有代码必须放在 python 代码块中。 - 代码块之后必须紧接一段“运行命令”命令可直接复制到终端执行。 - 不要输出与脚本无关的解释性文字。 ## 验收清单 - [ ] 脚本能读取 data.csv 并生成 output_data.csv。 - [ ] 非数值列被跳过且回复中包含跳过列的提示。 - [ ] 运行命令可以直接执行。 ## 禁止事项 - 不要修改输入文件。 - 不要省略任何一列的统计结果。这版 SKILL 的使用效果让我很满意同任务跑五轮四轮能一次生成正确可运行的脚本失败的那一轮也是因为我在输入数据里埋了特殊字符串属于测试数据本身的问题不是 SKILL 的问题。我终于把这个“AI 反复不执行”的顽疾治住了。5. 调试过程中的常见问题速查表调试这轮 SKILL 的过程中我积累了相当多的排查经验。下面整理成一张速查表你遇到类似问题可以直接对照使用现象原因解法AI 只解释不写代码指令中缺少“必须输出代码块”的强制约束在输出规范中明确“所有代码必须放在代码块中不输出则视为未完成”AI 生成代码但忽略格式要求输出规范被其他无关指令淹没减少无关指令数量把输出规范放在显眼位置AI 反复停下来反向确认输入条件不完整AI 无法确定下一步在 SKILL 中增加“输入缺失时的处理方式”分支AI 生成代码与需求不一致细节不足AI 按自己的假设补全了逻辑在 SKILL 中补充具体参数、文件名、编码等细节AI 多次修改同一处代码缺少验收标准AI 无法判断是否完成增加“验收清单”列出完成后必须满足的检查项AI 跳步直接给出结论执行步骤语句太长AI 丢失了中间状态把步骤拆成多个短句每步一个动作这张表里我实际踩过最多次的就是第一行“只解释不写代码”。以前我觉得是模型太笨后来才发现是 SKILL 里没有“必须输出代码”这个硬约束。大模型天然倾向于对话式的回复你要是不明确告诉它“代码必须放代码块里”它就可能给你来一大段文字描述让你自己写代码。另一个容易踩的坑是“禁止事项写太多”。我试过写十条禁止内容结果 AI 把禁止项当成需要讨论的话题每条都要“确认一下你是否真的需要禁止”。后来我把禁止项压缩到三条只保留最可能出问题的AI 反而不会纠结了。这也印证了一个原则SKILL 里每一句话都应该有存在的理由没有理由的字句就是噪音。6. 框架细节 SKILL 的通用模板调试完成后我把这套思路提炼成了一个通用模板现在已经在我自己的 Agent 项目里反复使用。模板长这样## 目标 用一两句话说明任务要达成的最终效果必须可量化、可验证 ## 输入 - 参数 1说明 - 参数 2说明 如果输入缺失应该怎么处理 ## 执行步骤 1. 步骤一动作说明 1.1 子步骤 A 1.2 子步骤 B 2. 步骤二动作说明 2.1 子步骤 C 每一步之后 AI 必须输出什么结果需要写清楚 ## 输出规范 - 输出文件格式、命名规则 - 示例命令的书写格式 - 不允许出现的输出形式 ## 验收清单 - [ ] 检查项 1 - [ ] 检查项 2 AI 完成后必须逐项自查 ## 禁止事项 - 禁令一 - 禁令二 最多三条这个模板可以适配大部分代码生成类任务。你在填写时需要注意几点第一细节是“服务于步骤”的不能写成流水账。比如“读取 CSV 文件”这个步骤你可以补充“指定 encodingutf-8”但没必要补充“pandas 是第三方库需要先安装”。后者对执行没有直接帮助反而会让 AI 花注意力在无关信息上。第二每一步都要有可验证的输出。我见过很多 SKILL 写“处理数据”“优化代码”但从不写处理完之后 AI 应该输出什么。对 AI 来说没有验证标准的任务就是模糊任务模糊任务最容易导致“空转”。第三验收清单比禁止事项更有用。禁止事项告诉 AI 不能做什么验收清单告诉 AI 必须做到什么。后者给了 AI 一个自我检查的抓手让它在输出前就能意识到自己漏了步骤。我自己在写模板时会先花五分钟把任务的目标和步骤用最朴素的流程图画一遍。画完再写 SKILL效率和准确率都会高很多。流程图画清楚之后AI 执行的成功率基本上不会低于七成。这次对 SKILL 的全面重构让我彻底改变了编写思路。现在我做任何 AI 辅助开发任务都会先搭框架、再填细节、最后设验收三部曲走完再交给 AI 去执行。如果你也被 AI 反复不执行的问题折磨得头疼建议先别急着换模型或者加更多提示词而是回头审视一下自己的 SKILL 是否缺少了“执行路径”和“验证标准”这两块拼图。很多时候不是 AI 不配合而是它压根没弄明白你想要的路径到底长什么样。
