1. 这个工作流到底在解决什么问题第一次看到“AI-Infra-Auto-Driven-SKILLS”这个名字很多人会以为又是一个把提示词包装成“技能包”的合集。但我实际拆开用下来它的定位比“提示词库”要具体得多它是一套面向 Codex、Claude Code 这类命令行智能体CLI Agent的推理框架工作流核心目标是把“让模型自己决定怎么干活”这件事从玄学变成可复现的流程。先说清楚它是什么。这个项目本质上是一组结构化的技能定义文件加上一套驱动逻辑让智能体在面对一个任务时不是直接闷头写代码而是先走一遍“理解任务 → 拆解步骤 → 选择技能 → 执行 → 自检”的推理链路。你可以把它理解成给智能体装了一个“工作台”而不是让它站在空地上随手抡锤子。它能做什么举几个我实际跑过的场景。你给它一个“把某个目录下的日志按天切分并统计错误率”的需求它不会上来就写脚本而是先判断这属于“文件处理 数据聚合”类任务然后调用对应的技能模块生成带参数校验的脚本最后自己跑一遍验证输出格式。整个过程你能看到它的推理轨迹而不是一个黑盒结果。它解决的核心痛点有三个。第一推理过程不可控。原生智能体经常跳步你让它做A它顺手把B也改了还觉得自己很聪明。第二技能无法复用。同一个团队里每个人调教出来的“好用的提示词”散落在各自的聊天记录里换个人就失效。第三缺乏自检环节。模型写完代码就交差跑不跑得通全靠运气。这个工作流把自检做成了强制步骤。适合谁来参考如果你只是偶尔用网页版问几个问题这个工作流对你来说偏重了。但如果你已经在用 Codex 或 Claude Code 做日常开发、自动化脚本、数据处理并且被“模型不听话”折磨过那这套东西值得花时间研究。它更适合有一定工程习惯、愿意把智能体当成“需要管理的协作者”而不是“许愿池”的人。我自己的感受是第一次配置会有点繁琐因为要理解它的技能注册机制和推理链路的触发条件。但一旦跑通一个完整任务后面再扩展新技能就是复制粘贴改配置的事。下面我按实际搭建和使用的顺序把关键细节拆开讲。2. 整体设计思路与方案选型拆解2.1 为什么是“技能驱动”而不是“提示词堆叠”市面上大多数智能体增强方案走的是“把提示词写长写细”的路线。你打开一个所谓的“超级提示词”里面塞了几千字告诉模型“你要先思考再回答、你要检查边界条件、你要输出JSON格式”。这种做法在单轮对话里有效但在 Codex 或 Claude Code 这种多轮、带工具调用的环境里问题很明显提示词越长模型越容易在中途“忘记”前面的约束尤其是当它开始调用文件读写、执行命令之后注意力会被工具返回结果带跑。这个项目选择“技能驱动”本质上是把一个大而全的提示词拆成一个个独立、可组合、带触发条件的技能单元。每个技能文件只负责一件事比如“解析CSV并推断列类型”或者“生成带错误处理的shell脚本”。智能体在推理时先根据任务描述匹配技能再加载对应技能的内容。这样做的好处是每次加载进上下文的只有当前需要的技能不会把无关约束塞进去干扰模型。我实测下来这种拆分方式对长任务特别友好。一个涉及五六个步骤的自动化任务如果全塞在一个提示词里模型跑到第三步就开始丢细节。拆成技能后每一步的上下文都很干净完成度明显提升。当然代价是你得先把技能库建起来前期投入比复制一段提示词要大。2.2 推理框架的分层结构这个工作流的推理框架我把它理解成三层。最上层是任务理解层负责把用户输入的自然语言需求转成结构化的任务描述包括目标、输入、输出、约束条件。中间层是技能调度层根据任务描述去技能库里匹配决定调用哪些技能、以什么顺序调用。最下层是执行与自检层实际调用工具、生成代码、运行验证并把结果反馈给上层决定是否继续。这三层不是硬编码的而是通过配置文件里的规则串起来的。比如任务理解层输出一个JSON技能调度层读取这个JSON里的task_type字段去映射表里找对应的技能组合。执行层跑完后会把成功或失败的状态写回调度层根据状态决定是重试、换技能还是终止。为什么这么设计因为智能体的能力边界在变。今天你只有文件处理技能明天可能加了数据库操作技能。分层之后加新技能只需要在调度层的映射表里加一条不用动推理逻辑。这种解耦在实际维护时省事很多。我试过在一个已经跑通的工作流里插入一个新的“API调用”技能只改了映射配置其他部分没动一次就跑通了。2.3 与原生 Codex / Claude Code 的协作方式这个工作流不是要替代 Codex 或 Claude Code而是寄生在它们之上。它利用的是这些工具已经提供的文件读写、命令执行、多轮对话能力自己只负责“怎么想”和“怎么管”。具体来说它通过一个入口脚本或者配置文件把技能定义注入到智能体的系统提示或项目上下文里然后在任务开始时触发推理链路。我用的方式是在项目根目录放一个技能配置文件夹Codex 启动时会读取这个文件夹里的内容作为上下文的一部分。Claude Code 那边类似通过项目级的配置文件挂载。这样每次在这个项目里发起任务智能体就自动带着这套工作流跑。如果你不想全局生效也可以只在特定任务前手动加载。这种协作方式的好处是不侵入。你不需要改 Codex 或 Claude Code 的源码也不需要装额外的插件。坏处是依赖这些工具本身的上下文管理机制如果它们某次更新改了读取规则你可能要跟着调。我遇到过一回某次工具更新后技能文件夹的读取顺序变了导致技能匹配错乱后来在配置里显式指定了加载顺序才解决。3. 核心细节解析与实操要点3.1 技能文件的组织结构技能文件是整个工作流的基石。我建议的组织方式是每个技能一个独立文件用 Markdown 或 YAML 格式放在统一的skills/目录下。文件名用动词加名词的形式比如parse_csv.md、generate_shell_script.md、validate_json_output.md。这样在调度层做匹配时可以直接用文件名做初步筛选减少读取全文的开销。每个技能文件内部我习惯分成四个区块。第一个区块是触发条件用自然语言描述什么情况下该用这个技能比如“当任务涉及读取结构化文本并推断字段类型时”。第二个区块是输入要求说明这个技能需要哪些参数参数的格式和来源。第三个区块是执行步骤这是核心把该技能要做的操作按顺序列出来每一步都写清楚意图和预期结果。第四个区块是输出规范定义这个技能跑完后应该产出什么格式是什么怎么判断成功。为什么要这么细因为智能体在加载技能时如果技能描述模糊它就会自由发挥。我踩过的坑是早期写技能时只写了“处理CSV文件”结果模型有时候只读表头有时候读全量有时候还顺手做了数据清洗完全不可控。后来把触发条件和输出规范写死行为就稳定多了。注意技能文件不要写得太长。一个技能超过两屏内容模型在加载时容易丢失重点。如果某个技能确实复杂拆成两个技能用调度层串起来。3.2 推理链路的触发与流转推理链路的触发点通常设在任务开始时。用户输入需求后工作流先跑一个“任务解析”技能把需求转成结构化描述。这个描述里至少包含任务类型、涉及的文件或数据、期望的输出形式、有没有特殊约束。然后调度层拿这个描述去匹配技能。匹配逻辑我建议用关键词加权的方式而不是精确匹配。因为用户输入的自然语言千变万化精确匹配很容易漏。具体做法是给每个技能定义一组关键词任务描述里出现某个关键词就加一分最后选分数最高的技能组合。如果最高分低于阈值就触发“澄清”技能让智能体反问用户而不是硬猜。流转过程中每个技能执行完会返回一个状态码。成功就继续下一个失败就根据失败类型决定是重试还是终止。我一般会设一个最大重试次数比如两次超过就报错并输出已完成的步骤方便人工介入。这个机制在处理外部依赖时特别有用比如某个技能要调用一个可能超时的命令失败一次后重试往往能过。3.3 自检环节的强制插入自检是这个工作流区别于普通提示词方案的关键。我的做法是在每个技能的执行步骤最后强制加一个“验证”子步骤。比如生成脚本的技能最后一步必须是“用bash -n检查语法”或者“用测试数据跑一遍”。验证不通过状态码就是失败调度层会决定是否回退。自检的内容根据技能类型不同而不同。文件处理类技能自检通常是检查输出文件是否存在、行数是否合理、关键字段是否为空。代码生成类技能自检是语法检查和最小用例运行。数据聚合类技能自检是对比总数和分项之和是否一致。这些自检逻辑不用很复杂但必须有而且必须由工作流强制执行不能靠模型自觉。我实测下来加了强制自检之后任务的一次通过率从大概六成提升到了八成以上。剩下的两成失败大部分也能在自检环节被拦住不会把错误结果传给下游。这个投入产出比很高建议一开始就把自检框架搭好后面加技能时直接复用。3.4 参数传递与上下文管理多技能串联时参数怎么传是个容易出问题的地方。我的经验是显式传递不依赖隐式上下文。每个技能执行完后把输出写到一个约定的临时文件或环境变量里下一个技能从明确的位置读取。不要指望模型“记得”上一步的输出尤其是在长任务里上下文会被压缩或截断。具体做法是在项目里建一个.workflow/目录每个步骤的输出按序号存成文件比如step_01_output.json、step_02_output.json。技能文件里写清楚它读哪个文件、写哪个文件。这样即使中间某个步骤需要重跑也不会影响其他步骤。而且出问题时你可以直接打开这些文件看中间结果排查效率高很多。上下文管理还有一个点是技能加载的时机。不要一次性把所有技能都塞进上下文而是按需加载。调度层匹配到哪些技能就只加载哪些。这样上下文占用小模型注意力集中。我试过在一个有二十多个技能的项目里按需加载比全量加载的响应速度快了将近一倍而且输出质量更稳定。4. 实操过程与核心环节实现4.1 环境准备与目录初始化开始之前你需要一个已经能正常使用 Codex 或 Claude Code 的项目环境。我假设你已经装好了对应的命令行工具并且能在项目目录里正常发起任务。然后按下面的结构初始化目录project-root/ ├── .workflow/ │ ├── step_outputs/ │ └── workflow_config.yaml ├── skills/ │ ├── parse_task.md │ ├── match_skill.md │ ├── execute_skill.md │ └── validate_output.md └── README.md.workflow/放工作流的运行时数据skills/放技能定义。workflow_config.yaml是核心配置文件里面定义技能匹配的映射表、重试次数、自检开关等。我建议一开始就把这个结构建好后面加技能只是往skills/里加文件改配置只是改workflow_config.yaml里的一行。初始化完成后先写一个最简单的“任务解析”技能确保工作流能跑通一个单技能任务。不要一上来就搞复杂链路那样出问题很难定位。我的做法是先让工作流能完成“读取一个文件并输出行数”这种任务验证推理链路、技能加载、自检都正常再往上加复杂度。4.2 编写第一个技能文件以parse_task.md为例我实际用的内容大概是这样# 技能任务解析 ## 触发条件 当收到新的用户任务输入且当前没有正在执行的任务时触发。 ## 输入要求 - 用户原始输入文本 - 当前项目目录结构可选 ## 执行步骤 1. 读取用户输入提取核心动词和名词短语。 2. 判断任务类型文件处理、代码生成、数据聚合、系统操作、其他。 3. 识别输入来源文件路径、目录、标准输入、无。 4. 识别期望输出文件、终端输出、代码片段、无。 5. 识别约束条件格式要求、性能要求、依赖限制。 6. 将以上信息整理成 JSON写入 .workflow/step_outputs/step_01_task.json。 ## 输出规范 输出一个 JSON 文件包含字段task_type、input_source、expected_output、constraints。 如果任一字段无法确定值设为 unknown。这个技能看起来简单但它是整个工作流的入口。我踩过的坑是早期没写“如果无法确定就设为unknown”结果模型遇到模糊需求时自己编了一个任务类型导致后续技能匹配全错。加上这个兜底规则后调度层看到unknown就会触发澄清流程不会瞎跑。写完技能文件后在workflow_config.yaml里注册它skills: parse_task: file: skills/parse_task.md trigger: task_start next: match_skilltrigger定义什么时候加载这个技能next定义执行完后流转到哪个技能。这样一条最简单的链路就串起来了。4.3 技能匹配与调度实现match_skill.md是调度层的核心。它的输入是上一步生成的step_01_task.json输出是选中的技能列表和执行顺序。我用的匹配逻辑是关键词加权具体在技能文件里这样写# 技能技能匹配 ## 触发条件 当 step_01_task.json 存在且 task_type 不为 unknown 时触发。 ## 输入要求 - .workflow/step_outputs/step_01_task.json - skills/ 目录下所有技能文件的触发条件区块 ## 执行步骤 1. 读取 step_01_task.json提取 task_type 和 input_source。 2. 遍历 skills/ 目录读取每个技能文件的触发条件。 3. 对每个技能计算匹配分数task_type 匹配加 3 分input_source 匹配加 2 分关键词匹配每个加 1 分。 4. 按分数从高到低排序取前三个技能作为候选。 5. 如果最高分低于 3 分输出空列表并标记需要澄清。 6. 将候选技能列表写入 .workflow/step_outputs/step_02_skills.json。 ## 输出规范 JSON 文件包含字段selected_skills数组、need_clarification布尔值、scores对象。这个匹配逻辑不复杂但够用。我试过更复杂的向量匹配效果提升不明显反而增加了依赖和调试难度。关键词加权的好处是透明你能清楚看到为什么某个技能被选中出问题时好排查。调度层还有一个职责是控制执行顺序。有些技能有依赖关系比如必须先解析再匹配再执行。我在配置里用depends_on字段显式声明依赖调度层按拓扑排序决定顺序。这样即使技能库变大也不会出现顺序错乱。4.4 执行与自检的落地execute_skill.md负责实际调用工具。它的输入是step_02_skills.json里的技能列表逐个执行。每个技能执行时工作流会把该技能文件的内容加载进上下文然后让智能体按技能里的执行步骤操作。执行结果写入step_outputs/目录状态码写入一个单独的状态文件。自检在validate_output.md里实现。它读取执行结果按技能类型跑对应的验证逻辑。比如文件处理类检查输出文件是否存在且非空代码生成类跑语法检查数据聚合类做总数校验。验证不通过就返回失败状态调度层根据重试次数决定是否回退。我实际跑的时候自检环节拦下过不少问题。有一次生成一个批量重命名脚本语法检查过了但自检发现它会把目标目录里所有文件都重命名包括不该动的配置文件。这个逻辑错误如果没拦住直接执行就出事了。自检里加一条“检查重命名范围是否限定在指定后缀”就解决了。提示自检逻辑不要写得太死。有些任务确实允许输出为空比如“清理临时文件”任务输出为空是正常的。在技能文件里加一个allow_empty_output标志自检时读取这个标志决定是否放行。4.5 完整任务跑通记录我拿一个实际任务跑一遍方便你对照。任务是“把data/目录下所有.log文件按日期切分统计每天的ERROR行数输出一个CSV。”第一步任务解析技能输出task_type是“文件处理数据聚合”input_source是data/目录expected_output是CSV文件constraints是“按日期切分、统计ERROR行数”。第二步技能匹配选中三个技能list_log_files、split_by_date、count_error_lines。分数分别是5、4、4。第三步执行。list_log_files扫描目录输出文件列表。split_by_date按文件名里的日期或文件内容里的时间戳切分这里有个细节如果文件名没有日期就要读内容。技能文件里写了两种情况的处理逻辑。count_error_lines统计每个切分后的文件里ERROR出现的次数。第四步自检。检查CSV文件是否存在、行数是否等于日期数、ERROR计数是否都是非负整数。全部通过。整个流程跑下来大概两分钟中间没有人工干预。如果某个步骤失败比如split_by_date遇到无法解析的日期格式它会返回失败状态调度层重试一次还失败就终止并输出已完成的部分。我遇到过一回日期格式是“2024-01-01”和“20240101”混用的情况第一次失败后我在技能文件里补了一条格式兼容规则重跑就过了。5. 常见问题与排查技巧实录5.1 技能匹配错乱怎么办这是最常见的问题。表现是工作流选了一个完全不相关的技能或者该选多个技能时只选了一个。排查思路分三步。第一打开step_01_task.json看任务解析的结果对不对。如果task_type就错了那是解析技能的问题去改解析技能的关键词提取规则。第二看step_02_skills.json里的分数明细确认是哪个关键词没匹配上。第三检查技能文件的触发条件是不是写得太窄或太宽。我遇到过一次任务描述里写的是“整理日志”解析技能把task_type判成了“文件处理”但匹配时list_log_files技能的关键词里没有“整理”这个词导致分数不够。后来在技能关键词里加了“整理、归档、归类”这些同义词问题解决。经验是技能关键词要覆盖常见的同义表达不要只写专业术语。5.2 自检误报怎么处理自检太严会误报太松会漏报。我的一般原则是语法和结构问题必须拦业务逻辑问题尽量拦性能问题不拦。比如输出文件不存在、JSON格式错误、必填字段缺失这些必须拦。业务逻辑比如“统计结果是否合理”能拦就拦但允许通过配置关闭。性能比如“执行时间是否超过阈值”不拦只记录。误报的典型场景是空输出。有些任务正常就是空输出但自检默认不允许空。解决办法是在技能文件里加allow_empty_output: true自检时读取这个标志。另一个场景是输出格式有多个合法变体比如日期可以是2024-01-01也可以是2024/01/01。自检里用正则同时匹配多种格式而不是只认一种。5.3 上下文丢失导致步骤跳步长任务跑到后面模型开始“忘记”前面的约束这是原生智能体的通病。工作流能缓解但不能根治。我的做法是每个技能文件里重复关键约束。比如“输出必须是UTF-8编码”这个要求在解析技能、执行技能、自检技能里都写一遍。虽然冗余但有效。模型在加载每个技能时都会看到这个约束不容易丢。另一个做法是缩短单次上下文。不要把整个任务的所有信息一次性塞进去而是每个技能只加载它需要的那部分。比如执行技能不需要知道用户的原始输入只需要知道任务描述和上一步的输出。这样上下文小模型注意力集中跳步概率低。5.4 技能库膨胀后的维护技能多了之后匹配变慢冲突变多。我的经验是定期合并和归档。功能重叠的技能合并成一个比如read_csv和read_tsv可以合并成read_delimited用参数区分分隔符。半年没用过的技能移到skills/archive/目录不参与匹配但保留备查。还有一个技巧是给技能打标签。在技能文件头部加tags: [file, data, text]匹配时先按标签粗筛再按关键词细筛。这样即使技能上百个匹配速度也不会明显下降。我现在的项目里有三十多个活跃技能用标签粗筛后匹配耗时基本在毫秒级。5.5 常见问题速查表问题现象可能原因排查动作解决方式工作流不启动配置文件未加载检查workflow_config.yaml是否在项目根目录确认工具读取路径必要时显式指定技能匹配为空关键词覆盖不足查看step_02_skills.json分数明细补充同义词降低匹配阈值自检一直失败验证条件过严查看自检日志确认失败原因调整验证规则加allow_empty_output步骤跳步上下文过长检查每个技能加载的内容量拆分技能按需加载重试不生效重试次数配置为0检查workflow_config.yaml的max_retries设为2或3并确认失败状态正确传递输出文件找不到路径不一致检查技能文件里的写入路径和读取路径统一用.workflow/step_outputs/下的相对路径这张表是我实际排查时总结的大部分问题都能在里面找到对应项。遇到新问题先按“现象→原因→动作→解决”的框架记下来慢慢就形成自己的排查手册了。5.6 几个我踩过的坑第一个坑是技能文件里的路径用了绝对路径。换台机器跑就失效。后来全部改成相对于项目根目录的路径问题解决。第二个坑是自检逻辑写在技能文件外面。一开始我把自检写成独立的脚本结果技能更新后忘了同步自检导致验证的是旧逻辑。后来把自检作为技能文件的一部分技能改自检跟着改不会脱节。第三个坑是重试时没有清理中间状态。某个技能失败后重试但上一次的残留输出还在导致重试时读到脏数据。解决办法是在重试前清空该步骤的输出文件或者用带时间戳的文件名区分每次尝试。我现在的做法是每次执行前先删掉对应的step_XX_output.*确保干净。第四个坑是技能之间的参数命名不一致。一个技能输出file_list下一个技能读files匹配不上。后来定了一个命名规范所有技能的输出字段用蛇形命名且在同一类任务里保持一致。这个规范写在README.md里加新技能时对照检查。6. 后续扩展与个人体会这套工作流跑顺之后扩展方向其实很多。我目前在做的一个扩展是技能版本管理。同一个技能可能有多个版本比如parse_csv_v1和parse_csv_v2调度层根据任务复杂度选择版本。简单任务用v1复杂任务用v2。这样不用为了兼容简单场景而把技能写得太臃肿。另一个方向是跨项目复用。把skills/目录做成一个独立的仓库不同项目通过软链接或子模块引用。这样在一个项目里调好的技能其他项目直接能用。我试过在两个项目间共享技能库省了不少重复配置的时间。需要注意的是共享技能库里的路径要写成相对路径且项目目录结构要一致否则会找不到文件。还有一个想法是给技能加性能指标。每次执行记录耗时和成功率积累一段时间后调度层可以优先选择成功率高的技能。这个还在试验阶段目前只是记录数据还没做自动选择。但数据本身已经有用能看出哪些技能不稳定需要优化。我个人在实际操作中的体会是这套工作流最大的价值不是让智能体变聪明而是让它的行为可预测。你大概知道它会怎么想、怎么做、什么时候会停下来问你。这种可预测性在自动化场景里比单纯的“能力强”更重要。一个偶尔惊艳但经常跑偏的智能体不如一个稳定输出八十分结果的智能体好用。最后分享一个小技巧从最小可用工作流开始。不要一上来就设计复杂的技能树和调度逻辑。先让一个技能跑通再加第二个再加匹配和自检。每加一个环节跑几个任务验证稳定性。这样出问题时你很清楚是哪个环节引入的。我见过有人一次性配了二十个技能结果匹配错乱排查了三天才找到是某个技能的关键词写得太宽泛。慢慢来比较快。