1. 公司内部定制开发为什么需要 SKILL 规范团队里用 Codex 做内部定制开发最容易出现的问题不是模型不够聪明而是每个人喂给它的上下文都不一样。同一个「生成数据库迁移脚本」的需求A 同事得到的是符合公司规范的 Alembic 脚本B 同事拿到的却是一份裸 SQLC 同事甚至让 Codex 直接改了生产库连接串。这种不一致在个人项目里无所谓但在公司内部定制开发场景下就是实打实的返工和事故来源。SKILL 规范要解决的就是这件事。它把「公司内部约定俗成的做法」从老员工脑子里、从散落的 Wiki 页面里抽成 Codex 能直接读取的模块化文件夹。你可以把它理解成给 Codex 发的员工手册它本身很聪明缺的不是通用编程能力而是「我们公司具体怎么做」这类流程性知识。SKILL 就是把这部分知识以最小 token 成本注入进去的载体。这篇面向的是需要统一 AI 编码行为的研发团队。我会给出可复制的 SKILL 目录骨架、config.toml配置片段、Codex 接入 TaoToken 统一 Key/API 通道的settings.json示例以及规范生效后的验证动作和检查清单。整套东西落地后团队里任何人跑 Codex触发的都是同一套内部规范。2. TaoToken 前置统一 Key 与 API 通道在写 SKILL 之前先把通道统一掉。团队里如果每个人各自申请 Key、各自配 endpointSKILL 规范再细也会被环境差异冲掉。TaoToken 在这里的作用是提供一个统一的 API 入口让 Codex 的请求走同一条通道Key 由团队集中管理。你需要先拿到一个可用的 API Key。登录控制台后在 API Keys 页面创建建议按团队或项目维度建 Key方便后续做用量区分和轮换。创建入口在这里API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 之后Codex 侧要配的就是两样东西模型通道endpoint key和 SKILL 加载路径。前者决定请求发到哪后者决定 Codex 能读到哪些内部规范。接入文档里有各客户端的完整字段说明配之前建议扫一眼接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite这里有个容易踩的坑很多人把 Key 直接写进项目仓库的配置文件里然后提交上去了。正确做法是把 Key 放进环境变量配置文件里只引用变量名。下面第三节的配置片段我会按这个方式来写。3. 可复制的 SKILL 目录骨架与配置3.1 SKILL 目录骨架先建一个团队级的 skills 根目录每个 SKILL 一个子文件夹目录名必须和 SKILL 的 name 完全一致只用小写字母、数字和连字符。下面是一个内部定制开发场景的骨架包含两个示例 SKILLteam-skills/ ├── db-migration/ │ ├── SKILL.md │ ├── agents/ │ │ └── openai.yaml │ ├── scripts/ │ │ └── gen_migration.py │ └── references/ │ └── schema-conventions.md └── api-handler/ ├── SKILL.md ├── agents/ │ └── openai.yaml └── references/ └── error-codes.mdSKILL.md是必需的由 YAML frontmatter 和 Markdown 正文组成。frontmatter 里只放name和description两个字段其中description是 Codex 判断「何时触发这个 SKILL」的唯一依据所以必须同时写清「做什么」和「什么时候用」。正文只在触发后才加载所以「何时使用」这类信息千万别写在正文里。一个db-migration的SKILL.md示例--- name: db-migration description: 生成符合公司规范的数据库迁移脚本。当 Codex 需要为内部项目创建或修改数据库表结构、编写 Alembic 迁移、或处理 schema 变更时使用。 --- # 数据库迁移规范 ## 快速开始 生成迁移脚本时先读取 references/schema-conventions.md 确认命名与字段约定。 ## 命名规则 - 表名使用小写下划线复数形式 - 迁移文件由 scripts/gen_migration.py 生成不要手写文件名 ## 进阶 - 字段类型映射见 references/schema-conventions.md - 涉及数据回填时必须拆成独立迁移文件注意正文用的是祈使语气直接告诉 Codex 怎么做而不是解释「为什么」。上下文窗口是公共资源每一句都要经得起「Codex 真的需要这段吗」的追问。3.2 config.toml 配置片段Codex 的模型通道配置放在config.toml里。下面这段把 endpoint 指向 TaoToken 的统一入口Key 从环境变量读取# ~/.codex/config.toml model claude-sonnet-4-5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [skills] # 团队级 SKILL 根目录Codex 会扫描其下每个子文件夹 paths [/opt/team-skills]env_key指定的是环境变量名不是 Key 本身。在 shell 里这样设置export TAOTOKEN_API_KEYsk-你的团队Key如果团队用统一的开发容器或 CI 环境把这条写进镜像的 entrypoint 或 CI 的 secret 注入里别写进仓库。3.3 settings.json 示例部分客户端比如 VS Code 侧的 Codex 插件走的是settings.json。字段名和config.toml不同但语义一致{ codex.provider: taotoken, codex.baseUrl: https://taotoken.net/api, codex.apiKeyEnv: TAOTOKEN_API_KEY, codex.model: claude-sonnet-4-5, codex.skills.paths: [/opt/team-skills] }同样apiKeyEnv指向环境变量名。两套配置可以共存取决于团队成员用哪种客户端。4. 验证请求与规范生效配完之后别急着写业务代码先做三步验证。第一步验证通道通不通。用 curl 直接打一次 API确认 Key 和 endpoint 没问题curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到模型输出就说明通道正常。如果返回 401检查环境变量有没有在当前 shell 生效返回 404 一般是 base_url 多写或少写了路径段。第二步验证 SKILL 被加载。在 Codex 里发一个明确会触发db-migration的请求比如「帮我给 users 表加一个 last_login_at 字段生成迁移脚本」。观察 Codex 是否按SKILL.md里的命名规则输出以及是否引用了references/schema-conventions.md。如果它完全没提规范说明 skills 路径没被扫到。第三步验证触发边界。发一个不该触发该 SKILL 的请求比如「解释一下什么是数据库索引」确认 Codex 不会强行套用迁移规范。触发过宽和触发过窄都是问题前者浪费上下文后者让规范形同虚设。想快速对比不同模型在同一 SKILL 下的表现可以直接在模型对话里试模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite5. 本篇常见错排查SKILL 不触发。九成是description写得太泛。像「帮助处理数据库相关任务」这种描述Codex 无法判断具体何时该用。改成「当 Codex 需要为内部项目创建或修改数据库表结构、编写 Alembic 迁移时使用」把触发场景写具体。触发了但没读 references。检查SKILL.md正文里有没有明确写出「何时读取哪个文件」。渐进披露的关键是主文档只留核心流程细节文件要在正文里给出明确的读取条件否则 Codex 不知道什么时候该去翻。目录名和 name 不一致。这是硬性规则skill-name文件夹里的name字段必须完全相同。不一致时校验脚本会直接报错。Key 泄漏。如果发现 Key 被提交进仓库第一时间去控制台轮换别只删 commit。轮换入口还是 API Keys 页面。上下文被撑爆。单个SKILL.md建议控制在 500 行以内。超了就拆到references/主文档只保留导航和选择规则。多领域、多框架的 SKILL 按领域或供应商拆分文件用到哪个读哪个。agents/openai.yaml 和 SKILL.md 不同步。更新 SKILL 后要重新生成 UI 元数据否则列表里显示的还是旧描述。用生成脚本重新跑一遍即可。6. 把规范沉淀成团队资产SKILL 规范真正的价值不在第一次写完而在迭代。团队里谁用 Codex 踩了坑就把那条经验补进对应的SKILL.md或references/下次所有人自动继承。这比在群里发「记得迁移脚本要拆数据回填」有效得多。长期跑编码任务和 Agent 的团队建议把通道也固定下来用 Coding Plan 统一管理用量和配额避免每个人各自为战Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite落地顺序建议是先统一 Key 和 endpoint再建一个最小 SKILL 跑通触发然后按团队实际踩坑逐个补规范。别一上来就写十几个 SKILL先让一个真正生效比铺一堆没人用的模板强。