1. 为什么面试官盯着 Agent Skill 不放Agent Skill 是给 AI 编码助手比如 Codex加装的一套「可复用工作手册」它把某个任务该怎么判断、按什么顺序执行、遇到什么情况该停下来写成一份模型能读懂、能自动加载的规范文件。适合谁适合已经在用 Codex 写代码、但每次都要重复交代同一套流程的人也适合准备面试、被问到「你怎么做 Agent 工程化」的开发者。我面过也旁观过不少相关岗位的面试发现一个规律候选人能背出 ReAct、能聊 Function Calling但一问「你团队里 Skill 怎么组织、怎么保证质量」很多人就卡住了。原因很简单——Prompt 是随手写的Skill 是要长期维护的工程资产两者的标准完全不同。这篇就聚焦 Codex 场景从 SKILL.md 的目录结构讲起拆 Prompt 分层和触发条件给一份能直接复制的骨架和 config.toml 配置最后演示一次 Skill 加载与调用的验证动作。全程可跟做不需要你先成为大模型专家。核心检索词先摆出来Agent Skill 是什么、SKILL.md 怎么写、Codex 怎么配置 Skill、Prompt 分层怎么设计、触发条件怎么定。这几个问题串起来就是一篇能过面试、也能落地的答案。2. 先判断这个任务值不值得封装成 Skill不是所有任务都该做成 Skill。Skill 有维护成本——要写说明、配资源、做测试、反复迭代。判断标准我总结成三条同时满足才建议投入。第一条任务里有没有「专家直觉」。熟手和新手的差距如果体现在边界判断、风险识别、优先级取舍上那就值得封装。比如「代码审查」这件事新手看语法熟手看的是「这个改动会不会破坏幂等性」「这个异常吞掉之后线上怎么排查」——这种判断就是专家直觉。第二条任务是不是足够复杂。一句话 Prompt 能说清、三步以内能完成的没必要做成 Skill。比如「把这段 JSON 格式化」就不值得。第三条任务会不会反复出现。Skill 的价值在复用。团队每周都要做的分析、审核、发布、改写、生成任务沉淀下来长期收益很高。三条都满足再动手。下面进入工程化落地。3. TaoToken 前置把模型入口和 Key 准备好Skill 写得再好也得有模型能跑。Codex 这类工具需要配置一个兼容的 API 入口我用的是 TaoToken它提供 OpenAI 兼容接口配置方式和官方 SDK 基本一致省去改代码的麻烦。你需要先拿到 API Key。打开控制台页面登录后在 API Keys 区域创建一个新 Key复制保存好——它只显示一次。地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去之后按提示操作即可。拿到 Key 之后模型对话能力可以先在网页端验证一下确认 Key 有效、模型可用再去配 Codex。模型对话入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 随便发一句「你好」看有没有正常回复。如果你打算长期用 Codex 做编码和 Agent 任务建议直接看 Coding Plan额度更划算适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 的基础地址统一用 https://taotoken.net/api 注意这个地址不带任何查询参数配置时别画蛇添足加 UTM。4. SKILL.md 骨架目录结构与 Prompt 分层4.1 目录结构长什么样一个规范的 Skill 目录我建议这样组织skills/ └── code-review/ ├── SKILL.md # 主文件触发条件、核心流程、资源导航 ├── references/ # 详细规则、领域知识 │ ├── checklist.md │ └── anti-patterns.md ├── scripts/ # 需要确定性执行的动作 │ ├── run_lint.py │ └── verify.py └── templates/ # 输出模板 └── report.md主文件只保留核心流程、触发条件和资源导航详细规则放 references/需要确定性执行的动作放 scripts/。这就是「渐进式披露」——不要把所有细节塞进 SKILL.md模型按需读取省 token 也更准。4.2 Prompt 分层的三层结构Skill 里的指令不是一坨文字要分层第一层是触发层告诉 Agent 什么条件下加载这个 Skill。第二层是流程层告诉 Agent 按什么顺序做、每步的输入输出是什么。第三层是约束层告诉 Agent 什么不能做、遇到什么情况要停下来。三层分开写好处是调试时能定位问题——是没触发、还是流程漏步、还是约束没生效。4.3 可直接复制的 SKILL.md 骨架--- name: code-review description: 对代码改动做结构化审查输出问题清单与修复建议 trigger: - 用户要求 review 代码、审查 PR、检查改动 - 涉及 diff、patch、commit 的审查请求 version: 1.0.0 --- # Code Review Skill ## 触发条件 当用户请求审查代码改动、检查 PR 或分析 diff 时启用本 Skill。 若只是询问某段代码的含义不触发。 ## 核心流程 1. 读取改动内容识别变更范围文件、函数、依赖 2. 按 references/checklist.md 逐项检查 3. 对照 references/anti-patterns.md 标记反模式 4. 运行 scripts/run_lint.py 获取静态检查结果 5. 汇总问题按严重程度排序 6. 输出报告格式见 templates/report.md ## 约束 - 不要修改代码只输出建议 - 来源不明的内容不要当成事实写进报告 - 高风险改动数据库迁移、批量删除先生成计划等确认再继续 - 缺失信息不要编造标注「需补充」 ## 资源导航 - 检查清单references/checklist.md - 反模式库references/anti-patterns.md - 静态检查脚本scripts/run_lint.py - 报告模板templates/report.md这份骨架的关键点frontmatter 里的 trigger 是给加载器看的正文里的「触发条件」是给模型看的两者呼应。流程用编号约束用列表资源用导航——模型读起来路径清晰。5. config.toml 配置让 Codex 认识你的 SkillCodex 通过 config.toml 加载 Skill 和模型配置。下面是一份可用的片段# ~/.codex/config.toml [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key model gpt-4o [skills] # Skill 根目录 root ./skills # 自动加载的 Skill 列表 enabled [code-review] [skills.code-review] path ./skills/code-review # 是否允许执行 scripts 目录下的脚本 allow_scripts true # 脚本执行超时秒 script_timeout 30几个参数说明base_url指向 TaoToken 的 API 地址api_key填你创建的那个 Key。skills.root是 Skill 存放的根目录enabled列出要启用的 Skill 名。allow_scripts控制是否允许执行脚本——涉及文件修改的 Skill 建议开启纯分析类可以关掉降低风险。配置完保存重启 Codex 让配置生效。6. 验证一次 Skill 加载与调用配置好不代表能用必须验证。分两步。第一步确认 Skill 被加载。在 Codex 里输入/skills list如果输出里能看到code-review说明加载成功。看不到就检查 config.toml 的路径和 enabled 列表。第二步触发一次真实调用。准备一个带问题的代码改动比如def get_user(user_id): result db.query(fSELECT * FROM users WHERE id {user_id}) return result然后对 Codex 说「帮我 review 这段代码的改动」。如果 Skill 正常触发你会看到它按流程走识别变更、对照 checklist、标记反模式这里应该会指出 SQL 拼接的风险、运行 lint、输出结构化报告。验证成功的标志有三个Skill 被自动加载、流程按 SKILL.md 的步骤执行、输出符合 templates/report.md 的结构。三个都满足说明 Skill 真正起作用了。如果没触发先看触发条件写得够不够明确——「review 代码」这种词要出现在 trigger 里。如果触发了但流程乱检查 SKILL.md 的流程层是不是写得太模糊。7. 本篇常见错排查错误一Skill 不触发。最常见原因是 trigger 关键词和用户实际说法对不上。用户说「看看这段代码有没有问题」你的 trigger 只写了「review」就匹配不上。解决办法是把常见同义说法都列进 trigger或者用更宽泛的语义描述。错误二加载报错skill not found。检查 config.toml 里的path是不是相对路径写错了以及enabled里的名字和目录名是否一致。目录名是code-reviewenabled 里写成codereview就会找不到。错误三脚本执行失败但没提示。这通常是脚本本身的问题——错误信息只返回了 exit code没有修复线索。按前面说的脚本输出优先用 JSON错误信息里带上「哪一步失败、怎么修」。错误四Skill 之间互相干扰。启用了多个 Skill 时如果触发条件重叠模型可能选错。解决办法是让每个 Skill 的 trigger 尽量互斥或者在 SKILL.md 里写明「本 Skill 不处理 XX 类请求」。错误五改了 SKILL.md 但没生效。Codex 一般在启动时加载 Skill改完要重启。有些版本支持热重载但别赌重启最稳。排查顺序建议先确认加载/skills list→ 再确认触发看日志→ 最后看流程执行对比 SKILL.md。一层层往下查比瞎改快得多。8. 从能跑到好用迭代与接入文档Skill 跑通只是起点。真正高质量的 Skill 是迭代出来的先不用 Skill 让 Agent 做一次真实任务记录它犯的典型错误这些失败样本就是你的评测用例然后按标准写初稿换新会话重跑评测用例效果明显更好说明 Skill 起作用了持续迭代到结果稳定。接入和排障过程中如果遇到 API 层面的问题比如鉴权失败、模型不可用可以对照接入文档排查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。文档里有完整的接口说明和错误码解释。长期做编码和 Agent 任务的话Coding Plan 的额度更适合高频调用配置一次就能持续用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说个我踩过的坑一开始我把所有规则都塞进 SKILL.md结果 token 爆了、模型还抓不住重点。后来按渐进式披露拆成主文件加 references主文件只留流程和导航效果立刻不一样。Skill 不是写得越多越好是写得越准越好。
