这个系列写到第七篇后台已经有不少人开始问同一个问题AGENTS.md 越写越长项目一多根本维护不过来团队里几个人都在用 Codex但完全是各跑各的小A 的 Agent 会写规范的提交信息小B 的 Agent 连项目的目录约定都不知道。所以这篇专门聊 Agent Skills把工作流封装这件事讲透怎么把一个团队的隐性经验固化下来怎么在不同项目里复用同一套能力以及怎么通过 Git 把这套东西变成整个团队共享的资产。Agent Skills 不是什么高深莫测的东西本质上就是把“针对某一类任务的完整处理流程”打包成一个可以重复加载的单元。以前你得在每次对话里反复叮嘱模型“先看这个、再跑那个、输出格式按这样来”现在你只需要把这一整套规则、脚本、模板都塞进一个技能包里让 Codex 按需加载。对于已经在日常用 Codex 的开发者、前端后端工程师以及想给团队统一 AI 工作方式的技术负责人来说这篇就是你最需要的那份落地参考。1. 先搞清楚Agent Skills到底是什么1.1 从配置文件到技能封装Codex的能力进化早期用 Codex 基本就是一个对话式代码助手你在终端里问它问题它给你改代码后来 Codex 进化成了可以自主调用工具、执行命令、处理多文件变更的 Agent。这时候问题也来了要让 Agent 干活符合预期你得把大量规则塞进 AGENTS.md 或者项目说明里比如“提交信息必须遵循 Conventional Commits”“Python 代码必须用 ruff 检查”“不要修改 tests 目录下的文件”。这些规则放多了以后每次 Agent 启动都要读一遍上下文越来越臃肿而且规则之间经常打架。更麻烦的是团队里每个人的 AGENTS.md 写法都不一样根本没法统一。我一度在项目根目录放了快三百行说明结果 Agent 响应速度肉眼可见地变慢还经常抓错重点。Agent Skills 解决的就是这个问题把任务说明、处理步骤、执行脚本、资源模板统一装进一个有结构的目录里平时不占用上下文只有任务匹配时才按需加载。这个变化就像厨房里的冰箱一样以前食材全堆在格子里做一道菜要翻半天现在每道菜配好的料包单独放着要做哪个菜就取哪个包。Agent Skills 就是那个“料包”是 Codex 从“配置驱动的助手”走向“任务能力驱动”的关键一步。1.2 Agent Skills和普通配置、插件有哪些本质区别很多人刚开始容易把 Agent Skills 和 AGENTS.md、MCP 插件搞混其实三者的定位完全不同。我整理了一个对比表这样你一眼就能看出差别能力形态核心载体加载方式典型用途项目说明 AGENTS.mdMarkdown 文件每次会话全量加载定义项目级静态规则、约定Agent SkillsSKILL.md scripts resources按任务意图匹配后加载封装完整工作流指令与工具结合MCP 插件 / 外部工具外部服务或命令行通过工具协议调用接入第三方数据源、系统 API三者不是替代关系而是配合关系。AGENTS.md 放的应该是“任何时候都不该违反的底线规则”比如“严禁提交密钥文件”Agent Skills 放的是“针对某个场景的处理流程”比如“如何为一个新服务生成完整的脚手架代码”。Skill 和纯文本指令最大的区别是它自带可执行脚本和模板资源。指令只能让模型知道该做什么而 Skill 可以真正让模型调用 Python 脚本去解析复杂的变更集、按模板生成结构化文档。我见过不少人把技能写成一堆自然语言描述模型执行得歪歪扭扭最后发现加一个脚本几秒钟就解决了。另一个关键点是按需加载。普通配置每轮对话都会消耗上下文而技能只在匹配到特定任务时才被完整读取。对于一个有多套流程的团队来说这种设计带来的 token 节省和响应提速是实打实的。2. 工作流封装把团队经验变成代码2.1 技能包的标准结构从SKILL.md到scripts一个标准技能包就是一个目录内部结构有约定但不复杂。我经常用的是这样的布局code-review-skill/ ├── SKILL.md ├── scripts/ │ ├── collect_changes.py │ └── severity.py └── resources/ ├── templates/ │ └── review_report.md.j2 └── examples/ └── report_sample.mdSKILL.md是技能包的心脏Agent 靠它来判断“这个技能适不适用于当前任务”也靠它来获取完整执行步骤。文件头部是元信息通常包含技能名称、用途描述以及可选的权限声明。名称要像一个函数名一样简洁描述则要包含足够的触发信号。一段合格的元信息长这样--- name: code-review description: 当用户要求对当前 Git 分支、某次提交或某个 PR 进行代码审查code review / 评审 / 看一下改动时使用。重点检查逻辑错误、安全隐患、性能问题和代码风格。 ---正文部分则需要把流程写清楚。不是告诉 Agent“认真审查”这种空话而是要像给新人写 SOP 一样说明每一步的输入、动作、产出。我习惯按“任务背景 - 执行步骤 - 输出格式”三段来写步骤里尽量用祈使句比如“先运行 ... 再打开文件逐个检查 ...”。脚本目录里的脚本要遵循“小而可靠”原则。不要依赖冷门第三方库能用标准库就绝不要引入额外依赖因为技能是要在团队里共享的别人机器的环境你不可控。我踩过一个大坑技能里用了某个本地装好但队友没装的包队友一跑直接报错。2.2 一个实际可用的Code Review技能包示例与其讲半天理论不如直接贴一个我实际在用的技能包。这个包解决的事情是每次要审查改动时不再需要反复告诉 Codex“先看 diff 再提交 review”而是一句“帮我 review 一下当前分支”就能触发完整工作流。SKILL.md的正文部分如下# Code Review 技能 ## 任务背景 当用户需要对本仓库当前分支的改动进行代码审查时使用本技能。 适用于 PR 审查、提交前自测、发布前检查等场景。 ## 执行步骤 1. 运行 git diff main...HEAD --stat 获取变更文件列表和增删行数。 2. 运行 git diff main...HEAD 获取完整 diff 内容。 3. 按以下顺序审查每个变更文件 - 安全是否存在命令注入、硬编码密钥、SQL 拼接等风险 - 逻辑是否存在空指针、边界溢出、错误被吞掉等问题 - 性能是否存在循环内重复查询、大对象未释放等隐患 - 风格是否违反仓库已有 lint 规则和命名约定。 4. 对每个问题生成一条结构化记录严重等级分为 blocker / major / minor / nit。 5. 调用 scripts/severity.py 对全部记录做统计汇总。 ## 输出格式 输出 Markdown 报告包含 - 变更概览文件数、插入行数、删除行数 - 问题清单按严重程度从高到低排列 - 汇总建议优先处理哪几个 blocker哪些问题可以直接提交。配合的severity.py也很简单就是把 SKILL.md 里的问题记录按优先级排序。核心思想是让模型把精力放在判断问题上把统计排序这种确定性工作交给脚本各司其职。有了这个技能包以后我每个 PR 的自审环节快了非常多。以前要自己点开 diff 一页页翻现在只要运行 Codex 的 exec 模式让技能按流程走一遍几秒钟就能拿到一份结构化报告再人工确认一遍阻塞项就行。2.3 封装时的三个决策点粒度、触发条件、副作用控制封装的决策直接决定技能好不好用。我总结出三个最关键的取舍点。第一个是粒度。一个技能最好只负责一件完整的事不要想着做一个“万能审查技能”把所有场景都包进去。粒度太粗技能内部步骤会很长描述之间容易自相矛盾Agent 执行到后半段经常忘了前面说了什么。粒度过细也不行会导致技能库爆炸每个技能都只覆盖一点点场景匹配成本反而更高。第二个是触发条件。这完全写在 description 里。描述写得越具体越不容易误触发。我之前把“jira-ticket”技能的 description 写得过于宽泛“处理 Jira 相关任务”结果用户聊到“这周 Jira 上还有几个任务没解决”这种无关话题时技能也被触发了白白占用了大量上下文。后来把描述改成“当用户需要根据当前代码变更生成一条 Jira 任务描述或更新已有 ticket 时使用”误触率立刻降了下来。第三个是副作用控制。技能里尽量不要包含自动执行破坏性命令的步骤比如强制覆盖文件、批量删除、无确认的 git push。我在技能里明确写了“如果涉及删除文件或修改共享分支必须先向用户说明风险并等待确认”。这是团队共享技能库时最重要的安全底线不然后果很可怕。3. 复用一套技能多场景干活3.1 技能目录规划全局还是项目级聊完封装来聊复用。技能放对了地方复用才谈得上。Codex 的技能目录大致有三个层级全局技能目录、项目技能目录、以及内联技能。全局技能适合那些不管在哪个项目里都需要的通用能力比如 code-review、commit-message、changelog 这类项目技能则放那些和当前仓库强相关的内容比如“本项目特有的环境搭建流程”或“这个微服务的新增接口规范”。Codex 加载技能时一般有优先级顺序项目级技能会覆盖掉同名的全局技能。这个机制很重要意味着你可以在全局放一套默认约定在具体项目里用项目级技能覆盖它。举例来说全局的 commit-message 技能遵循 Conventional Commits但某个老项目要求传统格式那就在那个项目里放一个同名技能覆盖即可不用改全局配置。我经常在项目根目录下放一个专门的技能目录结构类似.concodex/ └── skills/ ├── api-design/ │ └── SKILL.md └── deployment-check/ └── SKILL.md3.2 技能升级与版本管理技能不像普通代码改了以后很容易出现“昨天还能正常触发今天就死活不生效”的情况。原因是技能内容会被 Codex 做一定程度的索引或缓存更新 SKILL.md 之后如果没有触发重新加载Agent 可能依然按旧版本执行。我的做法是像管理代码库一样管理技能库具体分三步。第一步所有技能都放进 Git 仓库不允许直接在生产环境目录里手工改文件。每次修改都走一次 commitcommit message 里写清楚变更内容。第二步给关键技能加版本号比如在 SKILL.md 的元信息里增加version: 1.2.0字段同时在文档里维护一个简单的 changelog。第三步做破坏性升级时不要原地改直接把旧技能目录归档新建一个名字带-v2或明确标识的新技能等运行稳定后再处理旧的。之所以要这么谨慎是因为技能一旦被团队共享改动的影响面就是所有同事的 Codex 实例。你要是悄悄把 code-review 的步骤改了而不告诉任何人他们在跑审查的时候输出风格突然变了会以为是 Codex 出了 bug。3.3 技能膨胀10个还是100个技能库建到一定规模你会发现自己维护的是另一个“项目”。我见过有人一口气写了四五十个技能结果 Codex 每次都要在大量技能的 description 里做匹配调用慢不说偶尔还会张冠李戴。技能数量我建议控制在精而不是多。一个团队三到五个高频技能已经能覆盖大部分日常工作超过十五个就该开始做审计了。一个简单实用的办法是每个月跑一次技能命中统计看哪些技能在真实对话里被触发过。从没触发过的要么删除要么合并进相近技能。还有命名规范团队里最好统一成“动词 对象”的格式比如generate-commit-message、review-pull-request、setup-microservice。命名规范的作用是让人和 Agent 都能快速判断这个技能是干什么的避免两个描述相似的技能互相打架。4. 团队共享从个人技能到组织资产4.1 Git仓库分发最直接的方案技能复用的最高层级是团队共享。一个人写技能包自己用价值很有限当它变成团队统一的执行标准时价值才会指数级上升。操作上一个独立的技能仓库是最直接的方案整个团队的技能文件都放在同一个 Git 仓库里大家 clone 到本地然后通过配置文件指定技能目录的加载路径。具体流程大概是这样的创建一个私有仓库team-codex-skills里面几个业务模块分别对应不同团队或不同能力域。每个子目录下都放一个README.md说明这个模块里有哪些技能、分别解决什么问题。团队成员 clone 该仓库到固定路径比如~/.codex/team-skills/。在 Codex 的配置中把这个路径加进技能检索目录。后续的技能变更全部走 Git提 PR - 评审 - 合并 - 成员拉取更新。这套流程跑通之后新成员入职当天只要 clone 一下技能库他的 Codex 行为就会立刻和团队老手站在同一水平线上。这是团队共享技能库最大的短期收益我强烈建议所有维护 Codex 团队协作方式的组织优先做这件事。我当初上线这个方案的时候团队里两个后端和一个前端都觉得太折腾了。结果跑了一个月之后没人愿意退回以前的方式因为以前互相 review 代码时要私聊半天确认对方的规范现在 Agent 生成的东西风格都是统一的等于少了一整层的沟通成本。4.2 从仓库到Registry大团队的进阶玩法几个人的小团队一个 Git 仓库就够了如果团队规模到了几十上百人或者跨了好几个项目组那就需要考虑更工程化的方案。我在实践里参考了类似 npm 私有仓库的思路给技能建立一个简单的台账。每个技能目录里增加一个manifest.json登记技能名、版本、负责人、适用仓库、依赖脚本等信息。这样配合一个极简的发布脚本就能实现开发者在本地写完技能 - 推送到内部 Git 服务 - 自动化脚本读取 manifest 并发布 - 其他人通过固定命令下拉最新技能索引。一个简化的 manifest 长这样{ name: jira-ticket, version: 1.3.0, owner: backend-team, description: 根据 git diff 生成 Jira ticket 草稿, files: [ SKILL.md, scripts/parse_diff.py, resources/templates/ticket.md ] }这个方案的好处是明确谁是技能的负责人坏处是搭建和维护成本有所上升。如果团队没有专门的人愿意管这套基础设施我建议还是继续用 Git 仓库直连的方式不要硬上 Registry。工具不是越复杂越好能跑起来且有人维护才是第一位的。4.3 共享之后的团队协作规则技能库建起来之后最大的风险往往不是技术而是协作秩序。做过开源维护的人都知道没有明确 ownership 的仓库最终都会变成一堆无人维护的孤儿文件。技能共享必须强调几个规则。第一每个技能都要有明确的 owner可以是个人或小团队owner 负责这个技能的变更评审和问题响应。第二任何人提技能改动 PR 时必须在描述里写清楚影响范围改了哪些触发条件输出格式有没有变化老技能是继续兼容还是废弃第三评审者重点审查的不是代码格式而是技能描述是否容易误触发、脚本是否包含危险操作、步骤是否有歧义。我见过最成功的团队案例是有一个“技能护法”角色这个人不一定是技术负责人但必须是使用 Codex 最频繁、踩坑最多的人。他负责维护技能库的整体结构、定期清理僵尸技能、规范新技能的合入标准。没有这么个角色技能库会很快就变成第二个“无人维护的 wiki”。5. 实操一步步搭建团队技能库5.1 基础环境准备进入实操环节。先说基础环境这一整套流程我假设你的电脑上已经装好 Codex 的命令行工具。装好之后先在终端里验证一下codex --version能正常输出版本号就没问题接下来确认登录状态。Codex 需要登录授权才能调用模型接口你跑了下面这条命令就知道是否已认证codex login如果提示没有 token 或登录过期重新走一遍登录流程就好。接着建一个技能库的骨架目录。我的习惯是在用户主目录下搞一个统一的组织避免每个项目里都散落着技能的副本mkdir -p ~/.codex/team-skills/code-review mkdir -p ~/.codex/team-skills/jira-ticket mkdir -p ~/.codex/team-skills/commit-message然后检查一下 Codex 的现有配置文件看看能不能指定额外的技能加载目录。不同版本的配置字段不完全一样但思路相通就是让 Codex 除了项目内的技能目录之外多扫描一个团队技能路径。5.2 从零写一个技能自动生成Jira标题我挑一个团队里最容易复用的技能来做演示根据当前 Git 分支的改动生成 Jira 任务标题。这个技能在正规一点的团队里几乎全员都需要因为 Jira 标题风格统一这件事靠人规定一百遍都不如 Agent 自动生成一遍有效。先建目录写 SKILL.mdmkdir -p ~/.codex/team-skills/jira-ticket/scriptsSKILL.md的内容--- name: jira-ticket description: 当用户需要根据代码改动生成 Jira 任务标题或任务描述时使用。适用于开始一个新任务、提交 PR、同步进度等场景。 --- # Jira Ticket 生成技能 ## 任务背景 根据用户的代码变更生成符合团队规范的一条 Jira ticket 草稿。 ## 执行步骤 1. 运行 git diff main...HEAD --stat 查看当前分支变更概要。 2. 运行 git diff main...HEAD 获取完整 diff。 3. 分析 diff 中的关键变更类型feature、bugfix、refactor、docs、test。 4. 提取受影响的核心模块与函数名不要复制大段代码。 5. 调用 scripts/summarize_diff.py 输出一条简短的一行摘要。 6. 按模板生成 ticket 标题与描述。 ## 输出格式 - 标题[模块名] 一句话说明变更意图 - 描述包含背景、改动内容、影响范围、测试建议总字数控制在 300 字以内。再写一个辅助脚本scripts/summarize_diff.py。这个脚本不需要多复杂核心是统计 diff 里改了哪些文件、大概增减了多少行帮助 Agent 快速抓住变更重心#!/usr/bin/env python3 import re import subprocess import sys def get_diff(): result subprocess.run( [git, diff, main...HEAD, --stat], capture_outputTrue, textTrue ) return result.stdout def summarize(stat_output: str): files [] total_add, total_del 0, 0 for line in stat_output.splitlines(): match re.search(r(\S)\s\|\s(\d)\s([-]), line) if match: files.append(match.group(1)) total_add sum(1 for c in match.group(3) if c ) total_del sum(1 for c in match.group(3) if c -) return { files: files[:20], total_files: len(files), additions: total_add, deletions: total_del, } if __name__ __main__: data summarize(get_diff()) print(变更文件数:, data[total_files]) print(文件列表:, , .join(data[files])) print(新增行数:, data[additions], 删除行数:, data[deletions])第一次跑完这个技能后团队里原来那个 Jira 标题总要改三遍的同事现在已经完全交给 Agent 来处理了只需要在生成结果上微调一下措辞。5.3 验证技能是否真的生效写完技能最怕的就是“没效果”。你兴冲冲地调用了技能Codex 却表现得完全没有读过 SKILL.md 一样该怎么答还怎么答。我遇到过这种情况排查后发现是技能描述没写好匹配阶段直接被模型忽略了。验证技能是否被加载我是这么做的。第一步用显式方式让 Agent 使用技能比如在对话里直接说“用 jira-ticket 技能生成一下这个分支的 ticket”观察输出格式是否符合 SKILL.md 的要求。第二步用隐式方式测试触发比如换个说法“这个分支要做啥帮我总结一张 Jira 单子”看看技能能不能被自动匹配到。第三步打开 Codex 的调试输出确认技能加载日志里有你要的那个技能名。如果显式调用有效但隐式触发无效那就是 description 写得不够贴合自然表达如果显式调用都无效优先怀疑技能目录路径有没有配对或者 SKILL.md 的格式有没有问题。格式这东西看着简单但少一个标点、多一个空行解析脚本不认就白搭所以写完后先用编辑器把 frontmatter 的缩进和冒号检查一遍。6. 常见问题与排查技巧实录6.1 高频报错速查表实战里最怕的就是各种报错我把团队里遇到过的几个高频问题整理成了一张速查表你可以直接对照处理。报错信息常见原因处理建议codex auth token is unavailable未登录或登录凭证过期运行codex login重新认证然后重启终端会话cc switch local proxy failed while handling codex endpoint /responses本机网络通道或本地配置工具异常导致请求没有到达 Codex 服务先检查本机网络出口是否稳定退出或重置本地代理类配置工具后重试同时确认登录状态未失效codex exceeded retry limit, last status: 429 too many requests请求频率过高触发了限流或当前账号配额不足降低并发任务数等一段时间自动退避检查是否把多个任务同时丢给 Codexthe gpt-5.6-sol model is not supported when using codex with a chatgpt acc当前账号类型与所选模型不匹配换用该账号支持的模型或在 API 账号环境下使用对应模型Codex 窗口打开异常 / 登录页加载不出来安装包异常或网络访问不稳定从官方渠道重新下载安装包切换稳定网络后重试cc switch local proxy failed那个报错刚开始很唬人我观察下来大部分情况不是 Codex 本身挂了而是本机网络链路在中间出了问题。把本地网络环境恢复干净、确认代理类服务状态正常之后再重试请求就能顺利到达服务端了。6.2 模型接入与参数调整经验社区里现在很流行直接把 Codex 接到各种第三方模型上跑比如通过修改模型提供方配置把 base_url 指向第三方 API换用兼容 OpenAI 接口的模型。这条路社区里确实有人跑通配置思路是在 Codex 的配置文件里增加一个模型提供方然后把默认模型切到目标模型名。我这里提醒一句这类配置不是官方标准玩法兼容性取决于第三方模型的接口实现水平改完以后要先小范围验证再团队推广。所谓小范围就是自己拿一个不重要的仓库试上几天确认生成质量稳定、没有奇怪的格式错乱再考虑纳入团队技能库。如果你只是调 Codex 自身的行为更稳妥的做法是调整运行参数尤其是把模型温度调低一点。像代码审查、提交信息生成这类对确定性要求高的技能温度设到 0.1 到 0.2 之间输出结果会规范很多不容易出现随机发挥的情况。这不算什么高深技巧但实际效果非常明显。6.3 团队落地时容易踩的几个坑最后分享几个团队落地时最容易踩的坑都是我亲眼见过的。第一个坑是技能库建好之后没人维护。建库那天大家热情高涨一人提了四五个技能过了仨月再看仓库已经半年没新 commit 了技能描述和实际工作流早就脱节。所以前面说的“技能护法”角色真不是可有可无的。不是说要设一个全职岗位而是必须指定具体的人来负责回答技能使用问题、清理无效技能、推动迭代更新。第二个坑是描述写得太泛。这种情况最容易出现在有人想“覆盖更多场景”的时候description 写得越大越全结果就是什么场景都能沾一点边什么场景都执行不精准。正确写法是限定触发条件里尽量说清前置条件哪些情况下不要用这个技能。一个技能宁可少触发也不要乱触发。第三个坑是脚本环境不一致。我前面强调过技能脚本不要依赖冷门库但有些团队还是会在共享技能里写一个需要 pandas 的脚本结果换了台机器就崩溃。如果依赖无法避免我建议把技能运行环境做成容器或锁文件固定版本让所有人在同一个环境里跑。我个人在实际操作中的体会是Agent Skills 真正的门槛不是语法也不是目录结构而是团队愿不愿意把各自脑袋里的隐性知识写出来、共享出去。技术上的东西几分钟就能学会难的是打破“我的工作方式不想让别人知道”这种心理惯性。所以搭建整套技能体系的时候别急着铺量先挑一个最高频、最能让所有人感觉到效率提升的工作流封装成第一个技能跑通之后再逐步扩展。有了第一个正反馈后面的推进会自然很多。