搭建一个可以长期使用的 Codex Agent，需要同时设计两件事

文件放在哪里，以及任务如何使用这些文件。

目录结构解决职责划分，运行流程解决读取、执行和交付。两者对应起来，Agent 才能知道接到任务后应该进入哪个流程、读取哪些资料、调用什么工具，以及怎样判断任务已经完成。

本文采用一套分层设计方法：

AGENTS.md 管全局规则与入口，Skill 管任务流程，Knowledge 管事实与方法，Script 管可程序化的执行。

在此基础上，再配置模板、数据结构和产物目录。

其中，AGENTS.md 和 SKILL.md 对应 Codex 的实际指令与技能机制；knowledge/、templates/、output/ 等目录，则是本文采用的工程组织约定。

一、先划分职责，再创建文件

文件分类应根据它承担的职责，而不只是根据内容属于哪个主题。

例如，同样围绕“产品介绍”，至少存在四类内容：

• 产品功能、适用对象和使用边界，属于业务事实。
• 先分析读者、再确定角度、最后完成正文，属于任务流程。
• 怎样把产品功能转化为读者能理解的价值，属于写作方法。
• 检查字段是否齐全、把结果保存成指定格式，属于程序执行。

把这些内容放在同一个文件里，短期可以工作，后续却很难单独更新、复用和验证。

可以用下面这张表决定文件归属：

文件或资源	核心问题	主要内容
AGENTS.md	这个工作区如何工作，任务从哪里进入？	身份职责、全局约束、目录说明、必要路由
SKILL.md	这类任务分几步，怎样完成？	输入、步骤、依赖、分支、输出、失败处理
Knowledge	这一步依据什么事实，怎样判断和做好？	业务事实、方法论、平台规范、质量标准
Script	哪些操作可以稳定交给程序？	计算、转换、校验、文件处理、接口调用
Template	结果采用什么固定结构？	章节、字段、占位符、输出骨架
Schema	数据结构是否符合约定？	必填项、类型、枚举、嵌套关系

这是一套职责划分，不要求每个工作区都创建全部目录。简单任务可以只有一个 Skill 和少量知识文件。

二、这套结构首先要实现两个目标

第一个目标：按需加载，控制 Token 和上下文占用。

Agent 不需要在开始工作时读完整个工作区。

更合理的方式是：先获得必要的全局规则和能力索引，再进入匹配的 Skill，执行到某一步时，读取这一步真正需要的资料。

Codex 的 Skill 机制本身支持渐进式加载：先提供技能名称、描述等元信息，匹配后再读取完整 SKILL.md，附属资源按需使用。OpenAI Skill 文档

工作区里的知识文件也应按照这个思路组织。

例如，只修改标题时，通常需要标题方法、当前正文和必要事实；没有理由同时加载图片规范、发布接口说明、全部产品资料和历史案例。

这样做有两个直接作用：

• 减少无关内容进入上下文，让当前任务的依据更清楚。
• 减少不必要的文本输入，节省 Token，保留更多上下文空间处理实际任务。

具体能节省多少，取决于文件体量和调用方式，不能给所有工作区统一承诺一个比例。已经读入的内容，也不会因为进入下一步就自动从上下文中消失，因此还要避免无意义的重复读取。

第二个目标：单一信源，减少冲突和版本漂移。

同一个重要事实、方法或规则，应当有一个明确的当前权威位置。

例如，某产品的适用范围统一维护在：

knowledge/products/product-a.md

公众号、小红书、客服问答等 Skill 都引用这个文件，不分别维护自己的产品介绍副本。

产品信息变化时，更新权威文件即可。相关流程在使用时读取当前版本。

“单一信源”允许保留历史版本，但必须明确哪份是当前版本、哪份只是历史记录。旧文章、旧提示词和旧交付物，都不能自动成为最新业务事实。

另外，修改源文件不会自动更新已经进入某个会话的旧内容。任务发现资料发生变化时，需要重新读取并处理差异。

三、一套可参考的工作区目录

当前 Codex 的仓库技能使用 .agents/skills/ 这一发现路径。不要把 .agent/skills/、普通 skills/ 和 .agents/skills/ 当成可以任意互换的名称。OpenAI Skill 目录说明

其他目录按实际需要建立，重点在于共享与私有资源的边界：

只有一个 Skill 使用的资源，可以放在该 Skill 内；多个 Skill 需要相同内容时，应考虑建立共享权威文件。

例如，一份只用于某种报告的模板可以放在 Skill 的 assets/ 中；多个写作流程共同依赖的品牌规范，则适合放在共享 knowledge/ 中。

output/ 保存生成结果，不承担当前业务事实的维护职责。本文约定将它与 .runtime/ 排除在 Git 提交之外；需要长期维护的内容，应转入明确的知识资产位置。

文件路径也要有统一基准。本文示例中的共享资源路径均相对于工作区根目录；Skill 内部资源相对于其自身目录。实际执行脚本时，应解析到明确路径，或设置正确的工作目录。

四、AGENTS.md：保持全局规则清晰、入口简洁

AGENTS.md 应保存 Agent 正确进入这个工作区所需的最小全局信息。

通常包括：

• 工作区用途，以及 Agent 的职责。
• 适用于多数任务的行为原则和操作边界。
• 主要目录的用途。
• 容易混淆的任务应该进入哪个 Skill。

Codex 会读取适用范围内的 AGENTS.md 指令；项目中的目录层级也会影响指令作用范围。因此，根目录适合放通用要求，确有必要时再为子目录补充局部规则。OpenAI AGENTS.md 文档

下面是一份结构示意，方括号内容需要按工作区实际情况填写：

 

工作区约定

 

用途 为[业务对象]完成[明确的任务范围]。

 

全局原则

• 业务事实以 knowledge/ 中对应的权威文件为准。
• 按当前任务和步骤读取资料，不预加载整个知识库。
• 不编造缺失事实；关键依据不足时明确说明。 - 执行范围遵循当前任务授权与工具权限。

 

任务入口 - [任务意图]：.agents/skills/task-name/SKILL.md

 

目录说明

• knowledge/：事实、方法与判断标准。
• output/：生成的交付物。
• .runtime/：运行日志、缓存与凭证。

详细的标题写法、行业分析方法、图片提示词技巧，不适合全部塞进这个文件。

这些内容通常只服务于某类任务，应该由对应 Skill 在需要时读取。

路由表也不必重复整个技能目录。简单任务可以依靠 Skill 的描述进行匹配；AGENTS.md 重点说明容易混淆的入口和工作区特有规则。

五、SKILL.md：写清楚任务怎样运行

Skill 是一类可复用任务的工作流。

它至少要让 Agent 明白：

什么时候使用、需要什么输入、依次做什么、每一步读取什么、产生什么结果，以及什么时候算完成。

下面是一份最小结构示意。名称、描述和路径中的占位内容，需要补齐后才能投入使用：

--- name: task-name description: "完成[具体任务]；当用户要求[可识别的任务意图]时使用。" ---

 

任务工作流

 

输入 任务目标、对象、必要素材、交付要求。

 

依赖 以下路径均相对于工作区根目录：

• 业务事实：knowledge/products/[事实文件].md
• 判断标准：knowledge/standards/[规范文件].md
• 输出模板：templates/[任务模板].md

 

执行步骤

1. 明确本次交付范围，检查必要输入。
2. 读取当前步骤需要的事实与规范。
3. 按要求生成结果；需要程序处理时调用对应脚本。
4. 检查事实依据、结构和本次交付要求。
5. 按本次授权保存或返回结果。

 

完成条件 约定的交付物全部完成，没有未处理的关键失败。

 

失败处理 关键资料缺失时说明缺失项。 执行失败时保留已完成结果，记录失败步骤。 重试前确认已有结果，避免重复执行。

真实 Skill 应进一步明确关键步骤的输入、输出和校验标准，而不是只写“认真分析”“高质量完成”。

例如，“读取产品资料后写文章”仍然过于模糊。可以改为：

“从指定产品文件中提取适用对象、核心功能和使用边界，形成事实摘要；正文中的产品表述必须能够对应到这些依据。”

但也不需要把完整的写作方法复制进 Skill。Skill 规定什么时候使用方法、使用后要得到什么；方法本身由 Knowledge 维护。

一个 Skill 可以使用另一个独立 Skill 的工作流，但这不等于创建了多个 Agent。是否有多个独立运行的 Agent，是另一项系统设计。

六、Knowledge、Script、Template 和 Schema 怎样配合

Knowledge：维护事实与判断依据。

知识文件应围绕相对独立、能够单独使用的主题组织。

例如：

knowledge/products/product-a.md

knowledge/methods/audience-analysis.md

knowledge/methods/title-writing.md

knowledge/standards/content-quality.md

这些文件可以分别更新，也可以被不同 Skill 复用。

判断是否需要拆分，可以看三个问题：不同部分是否由不同流程使用，是否独立更新，执行时是否通常只需要其中一部分。

也不要为了分层，把一个完整方法拆成大量只有几句话的小文件。拆分的目的，是让读取和维护更准确。

Knowledge 内部可以包含方法步骤。例如“判断信息来源质量”的五个检查步骤，仍然属于知识。整个任务先研究、再写作、再交付的顺序，则应由 Skill 管理。

Script：完成可以程序化的操作。

适合脚本处理的内容包括计算、去重、格式转换、字段校验、文件生成和接口调用。

脚本应有清楚的输入参数、输出位置、成功标志和错误信息，让上层流程能够判断结果。

业务假设不能只藏在代码里。例如“缺失值统一按零处理”，会影响结果含义，应该在相应方法或流程中明确说明。

如果脚本调用图片生成模型，脚本可以规范请求、保存文件和处理错误，但不能因此推导出图片内容和质量具有确定性。

Template：规定输出骨架。

模板可以规定标题、章节、字段和占位符。它告诉 Agent 结果采用什么结构。

怎样把各部分写好，仍由知识规范决定。

Schema：验证机器需要的数据结构。

Schema 可以检查字段是否存在、类型是否正确、取值是否在允许范围内。

它无法单独证明业务事实真实，也不能替代内容质量判断。

因此，“结构校验通过”和“任务质量合格”应当分别检查。

七、把目录结构连接成运行流程

Markdown 文件本身不会自动执行。真正读取文件、理解步骤、调用工具的是运行中的 Agent。

一条完整任务可以按下面的流程运行：

接收用户任务

↓

应用工作区规则，明确交付范围

↓

选择匹配的 Skill

↓

检查必要输入与依赖

↓

执行当前步骤

├── 按需读取 Knowledge

├── 使用 Template 或 Schema

└── 调用 Script 或其他工具

↓ 检查步骤结果

├── 成功：进入下一步

└── 失败：记录原因，按流程处理

↓

核对本次交付要求

↓

保存或返回结果

这里有三个需要写清楚的控制点。

首先，执行范围来自当前任务。

“修改正文”“完成图文”“保存本地”“提交草稿箱”是不同的交付要求。

Skill 可以提供默认流程，但不能把用户明确排除的步骤重新加回来。已有明确授权的步骤，也不应反复要求用户确认。

其次，步骤之间通过明确结果衔接。

例如，研究步骤应交出事实摘要及来源；写作步骤使用摘要生成正文；配图步骤根据正文确定画面和提示词。

如果只有“继续下一步”，没有中间结果约定，后续步骤就容易重新猜测前面的判断。

最后，失败应当定位到具体步骤。

如果正文已完成、图片生成失败，应报告当前完成情况和失败节点。重试时从适当位置继续，不必把整篇正文重新生成。

对于需要跨会话恢复的长任务，可以额外保存任务编号、步骤状态、产物位置和错误记录。这些属于运行状态，不应混入业务知识文件。

八、代入案例：一个小红书内容工作区怎样设计

下面用一个小红书工作区示例，把前面的结构连接起来。

原示例已经包含写作 Skill、标题与正文知识文件、图片提示词文件，以及独立的图片生成 Skill。不过，其中部分文件仍为空，目录拼写与引用路径也需要统一。

产品信息放在产品事实文件中；目标读者、内容框架、标题、正文和图片提示词方法分别维护；write-xhs 组织写作流程；图片生成 Skill 负责生图任务及其脚本调用。

假设收到这样一条演示任务：

根据指定产品资料，为新手用户写一篇小红书笔记，配一张封面和四张内页，保存到本地。

这条任务可以按以下顺序执行：

步骤	本步读取或使用的资源	本步产出
明确范围	当前任务要求	一篇笔记、五张图片、本地保存
理解产品与读者	product-a.md 、audience.md	事实摘要、目标读者与内容角度
确定内容结构	content-framework.md	论述顺序与内容提纲
写标题和正文	title.md 、body.md、笔记模板	与事实摘要一致的完整笔记
设计配图	已完成正文、image-prompt.md	一张封面与四张内页的提示词
生成图片	图片生成 Skill 及其脚本	生成结果、文件位置或错误信息
核对交付	本次要求、文本与生成结果	完成情况及本地产物位置

按需加载在这里有很具体的含义：

分析产品时，先读取产品与读者资料；写正文时，再读取内容结构和写作方法；进入配图环节后，才需要加载图片提示词方法和生图流程。

如果用户只要求写正文，流程就不进入图片生成阶段。

单一信源也有具体落点：

假设产品适用范围发生变化，应更新 product-a.md。标题、正文和图片提示词都从这份当前事实出发，不应各自保存一份独立的产品政策。

这里还要区分“文件存在”和“能力可用”。

空的知识文件无法提供方法；脚本文件存在也不代表参数、凭证和依赖已经准备完成。完成目录整理后，需要用一条真实任务验证路径、输入、执行和交付是否衔接。

九、新建、长期使用和存量治理，分别怎样应用这套标准

这套工作区架构标准，我已经整理成一条 Skill。它可以用于新工作区创建，也可以用于日常校准和已有工作区治理。

新建 Agent：先加载标准，再设计工作区。

建议按照以下顺序进行：

读取工作区架构标准 Skill     

↓ 

明确 Agent 的职责与任务范围     

↓ 

设计目录、任务入口和事实源     

↓ 

创建最小可用工作流     

↓ 

用真实任务验证     

↓ 

根据需要逐步扩展

这样可以在创建之初，就明确哪些内容进入 AGENTS.md，哪些属于 Skill，哪些应独立维护为知识文件。

这里的“学习标准”，指让 Agent 读取并遵循这套规则。要让后续工作持续遵循，还需要把相关入口和约束保留在可再次加载的文件中，不能只依赖最初那次聊天。

长期使用：用同一套标准定期校准。

工作区使用一段时间后，可能出现全局规则变长、多个 Skill 重复知识、旧路径残留、临时做法固化等问题。

此时可以检查：

• AGENTS.md 是否混入了大量单项任务细节。
• Skill 是否写清输入、依赖、完成条件和失败处理。
• 相同事实或方法是否被多处独立维护。
• 是否仍然按任务读取资料，还是每次都加载大量无关内容。
• 新增文件是否有明确职责和调用入口。

校准应围绕发现的问题调整，保留已经有效的结构和能力。

已有 Agent：进行一次规范化治理。

对已经使用一段时间的 Agent，可以先检查当前工作区，形成一份职责与依赖清单。

随后按确定的调整范围处理：

发现的问题	调整方向
全局文件堆积详细方法	将可独立维护的方法提取到 Knowledge
多个 Skill 复制同一份规则	确定权威文件，其他位置改为引用
知识文件控制整个任务流程	将全局编排移入对应 Skill
脚本隐藏重要业务假设	在对应事实、方法或流程中明确依据
路径失效、文件为空	修正依赖，补齐实际需要的内容
修改后无法恢复	保留必要备份与变更记录

调整目录或文件位置时，还需要同步修正引用。否则，人看到的结构变整齐了，Agent 的执行入口却可能失效。

治理完成后，应当用有代表性的真实任务验证，而不是只检查目录名称是否符合规范。

十、怎样验收一个工作区是否设计合理

可以直接用下面这些问题检查：

检查项	应当能够给出的答案
任务从哪里进入？	有明确的 Skill 匹配依据或路由
当前步骤读取什么？	有具体资源路径与使用目的
事实冲突时依据哪份？	有明确的当前权威来源
下一步接收什么？	有清楚的中间结果约定
什么情况下算完成？	能对应本次任务的交付范围
失败后怎样继续？	能定位失败步骤，避免盲目重复执行
修改一个事实影响哪里？	能追踪使用它的流程与资源

创建工作区时，可以先选一个高频任务，把入口、知识、执行和交付完整连接起来。等这条流程稳定后，再按相同边界增加新的能力。

老梁AI电商，专注帮电商企业建立可落地的 AI 能力体系——从 AI 内容生产到私有知识库、岗位 Agent。