Agent System Prompt Architect：用 Skill 给 Codex 写系统提示词的配置骨架

1. 为什么 Agent 的 System Prompt 总是写不好如果你正在用 Codex 或 Claude Code 这类编码 Agent 搭自己的 Agent 项目大概率遇到过这个场景让 AI 帮你写一个 Agent 的 System Prompt结果它根据项目名硬编了一个角色把工具能力写成根本不存在的 API输出一大段又长又重复的提示词还把你随口说的偏好变成了固定流程。跑起来之后 Agent 行为飘忽你回头改提示词改完更乱。这个问题的根子不在模型能力而在于「让 AI 写提示词」这件事本身缺少约束。Agent System Prompt Architect 就是一个专门解决这个问题的 Skill它把「怎么写系统提示词」变成一套可加载、可复用、可审查的流程让 Codex 在生成 System Prompt 时遵循固定骨架而不是自由发挥。它适合三类人正在做 AI Agent 的开发者、需要批量产出提示词的提示词工程师、以及用 Codex / Claude Code 做自动化工作流的人。我试过直接让 Codex 写 system prompt十次里有八次需要大改。后来把生成逻辑封装成 Skill加载之后 Codex 的输出结构稳定了很多。下面我把这套 Skill 的目录结构、config.toml 骨架、系统提示词模板以及在 Codex 里加载并验证 Agent 行为一致性的完整步骤拆开讲你可以直接照着配。2. TaoToken 前置给 Codex 接上稳定的模型通道Codex 本身是客户端真正干活的是背后的模型。如果你在本地跑 Codex 时遇到请求不稳定、模型切换麻烦、或者想统一管理多个 Agent 项目的调用额度可以先把模型接入层换成 TaoToken。它的作用是提供一个兼容 OpenAI 接口规范的统一入口Codex、Claude Code 这类工具都能通过它调用模型省去每个项目单独配 Key 的麻烦。接入方式很简单先到控制台创建一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完 Key 之后Codex 的配置里把 base_url 指向https://taotoken.net/api模型名按你实际要用的填。这里注意一点API 地址不要加 UTM 参数只有网页端链接才带。如果你还没决定用哪个模型可以先去模型对话页面试一下效果模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite对于长期跑编码 Agent 的场景比如你要反复生成、迭代 System Prompt用 Coding Plan 会更划算额度按周期走不用每次单独算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档在这里里面有不同客户端的配置示例Codex 和 Claude Code 都有对应说明接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite配好之后Codex 发出的请求就会走 TaoToken 的通道后面加载 Skill、验证 Agent 行为都在这个基础上进行。3. Skill 目录结构与 config.toml 骨架Agent System Prompt Architect 的核心设计思路是名称只作为标签不直接当角色稳定事实和判断标准优先工具能力和真实工具规格分离默认输出 system prompt领域适配用 checklistprompt 技术按需选择写完后用 evaluation 清单压缩和审查。这套思路落到文件上就是一个标准的 Skill 目录。3.1 目录结构在 Codex 的 skills 目录下新建agent-system-prompt-architect结构如下skills/ └── agent-system-prompt-architect/ ├── SKILL.md ├── agents/ │ └── openai.yaml └── references/ ├── system-prompt-template.md ├── evaluation-checklist.md └── domain-adapters.mdSKILL.md是入口描述这个 Skill 什么时候被触发、做什么。agents/openai.yaml定义 Agent 的元信息。references/放模板和清单Codex 在生成时会按需读取。3.2 SKILL.md 骨架--- name: agent-system-prompt-architect description: 为 AI Agent 生成可部署的 System Prompt遵循固定骨架避免角色臆造和工具能力幻觉。 --- # Agent System Prompt Architect 当用户要求为某个 Agent 编写或重构 System Prompt 时按以下流程执行 1. 读取 references/system-prompt-template.md 作为输出骨架 2. 根据领域读取 references/domain-adapters.md 中的 checklist 3. 生成初稿后用 references/evaluation-checklist.md 自查 4. 输出前压缩重复段落确保工具能力与真实规格一致 禁止事项 - 不得根据项目名直接推断角色 - 不得编造未在上下文中出现的工具 API - 不得把用户偏好写成固定流程3.3 config.toml 骨架Codex 的配置文件里需要注册这个 Skill并指定模型通道。下面是一个可用的骨架[model] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o [skills] enabled true paths [skills/agent-system-prompt-architect] [skills.agent-system-prompt-architect] trigger system prompt auto_load_references true max_reference_tokens 4000api_key_env指向环境变量不要把 Key 明文写进文件。trigger是触发词当你在对话里提到 system prompt 相关需求时Codex 会自动加载这个 Skill。auto_load_references控制是否自动读取 references 下的模板。3.4 系统提示词模板references/system-prompt-template.md是生成 System Prompt 的骨架结构如下# Role [标签式角色不展开臆造] # Capabilities [只列真实存在的工具能力格式工具名 - 用途] # Constraints [硬性边界如不得调用未授权接口] # Decision Criteria [判断标准如证据优先级、输出格式选择] # Output Format [默认输出结构] # Evaluation [自查清单生成后逐条核对]这个模板的关键在于把「角色」和「能力」分开。角色只是一个标签真正约束 Agent 行为的是 Capabilities 和 Decision Criteria。很多提示词写崩就是因为把角色写得太具体模型开始按角色脑补能力。4. 在 Codex 中加载 Skill 并验证 Agent 行为一致性配置写完接下来是加载和验证。这一步的目标是确认 Skill 被正确触发并且生成的 System Prompt 在不同请求下行为一致。4.1 设置环境变量并启动先把 API Key 写进环境变量避免明文暴露export TAOTOKEN_API_KEY你的Key然后进入项目目录启动 Codexcd your-agent-project codex --config config.toml启动后Codex 会读取 config.toml加载 skills 目录下的 Skill。你可以在对话里输入/skills查看已加载的 Skill 列表确认agent-system-prompt-architect在列。4.2 触发 Skill 生成 System Prompt在 Codex 对话里输入类似这样的请求帮我为这个项目写一个 Agent 的 System Prompt项目是一个代码审查助手能读取 git diff、调用静态分析工具、输出审查意见。如果 Skill 触发成功Codex 会先读取模板和 checklist然后按骨架输出。你可以观察输出结构是否包含 Role、Capabilities、Constraints、Decision Criteria、Output Format、Evaluation 这几个部分。如果输出还是一大段自由文本说明 Skill 没被触发检查 config.toml 里的 trigger 和 paths 是否正确。4.3 验证行为一致性生成完 System Prompt 后把它作为新 Agent 的系统提示跑几个测试请求看行为是否稳定。比如请审查这段代码的潜在问题 def add(a, b): return a b观察 Agent 是否按 Output Format 输出是否引用了真实工具能力是否在证据不足时明确说明。如果 Agent 开始编造工具调用说明 Capabilities 部分写得太宽泛回到模板收紧。4.4 用 evaluation 清单自查references/evaluation-checklist.md是生成后的审查清单逐条核对检查项通过标准角色是否标签化没有根据项目名臆造具体人设工具能力是否真实每个工具都能在项目里找到对应实现提示词是否重复没有大段重复表述偏好是否被写成流程用户偏好只作为参考不是硬性步骤输出格式是否明确有默认结构且可被测试验证这张表建议每次生成后都过一遍尤其是工具能力那一项幻觉 API 是最常见的问题。5. 本篇常见错排查配置和验证过程中有几个坑比较集中我整理成排查表遇到问题直接对照。5.1 Skill 不触发现象输入 system prompt 相关请求Codex 没有读取模板直接自由输出。排查顺序先确认config.toml里[skills]的enabled是 true再确认paths指向的目录存在且包含SKILL.md最后检查trigger关键词是否和你输入的内容匹配。如果 trigger 设的是system prompt你输入「写个提示词」可能不触发改成包含触发词的表述即可。5.2 模型请求失败现象Codex 启动后请求报错提示连接或鉴权问题。排查确认base_url是https://taotoken.net/api不要带多余路径确认TAOTOKEN_API_KEY环境变量已设置且没有多余空格确认模型名在 TaoToken 支持的列表里。如果还是失败去接入文档对照客户端的配置示例或者到 API Keys 页面确认 Key 状态正常。5.3 生成的 System Prompt 仍然很长现象Skill 触发了但输出还是很长、重复。原因通常是references/system-prompt-template.md里的 Evaluation 部分没被严格执行。解决办法是在 SKILL.md 里把「输出前压缩重复段落」写成硬性步骤并在 evaluation-checklist 里加一条「总长度不超过 X 字」。另外max_reference_tokens设太大也会让模型把模板全文照抄适当调小。5.4 Agent 行为不一致现象同一个 System Prompt不同请求下输出格式差异大。这通常是 Decision Criteria 写得太模糊。比如只写「输出审查意见」没写「按严重程度排序每条包含位置、问题、建议」。回到模板把判断标准写成可验证的条目再跑测试请求对比。5.5 工具能力幻觉现象Agent 调用了项目里不存在的工具。这是最需要警惕的问题。Capabilities 部分必须只列真实工具格式统一为「工具名 - 用途」。如果项目工具多可以在references/domain-adapters.md里按领域分 checklist生成时只加载相关部分减少模型脑补空间。6. 把 Skill 用进你的 Agent 工作流这套配置跑通之后你可以把它固化进日常流程每次新建 Agent 项目先让 Codex 加载 Skill 生成 System Prompt再用 evaluation 清单自查最后跑测试请求验证行为。生成和验证都走 TaoToken 的通道Key 统一管理不用每个项目单独配。如果你主要做长期编码和 Agent 迭代建议用 Coding Plan额度按周期走适合反复生成和调优的场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你还在选模型或者想先手动试一下不同模型生成 System Prompt 的效果去模型对话页面直接对比模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite配置过程中遇到接入问题先查接入文档大部分客户端配置都有现成示例接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后提醒一句Skill 的价值不在于让 AI 一次写出完美提示词而在于把「写提示词」这件事变成有骨架、有清单、可复查的流程。你每次生成后过一遍 evaluation 清单积累几轮自己的领域 checklist 会越来越准Agent 行为也会越来越稳。