最近一直在折腾 Agent 编程Claude Code 和 Codex 换着用越用越觉得不对劲同一套前端开发规范Claude Code 里配了一份Codex 里又要配一份等以后第三、第四个 Agent 进场光是维护这些 Skills 就能把人搞疯。于是我做了一套统一管理方案让一套 Skills 同时喂给多个 Agent改一处处处生效。这个方案不复杂核心就是“中心仓库 软链/导入 约定目录”但落地过程中踩了不少坑。今天把这套东西完整拆开讲从 Why 到 How 到踩坑记录全写清楚。无论你是刚开始玩 Claude Code 的小白还是已经在团队里推广 AI 编程的老手这套思路应该都能给你省下不少时间。先交代背景我目前主力工具是 Claude Code 和 OpenAI Codex日常会处理前端页面开发、Python 脚本、数学建模、学术文献整理这几类任务。Skills 这个概念最早是 Anthropic 在 Claude Code 里推的现在社区里已经有大量现成 skills 可抄作业。但问题也跟着来了Codex 并没有原生 Skills 机制它有自己的一套 AGENTS.md 体系。如果你想同一套指令两边都用就得自己想办法做适配不能想当然认为“复制粘贴就行”。1. 为什么需要多 Agent 统一管理 Skills1.1 Agent 各守一摊的混乱现状如果你只用一个工具比如只用 Claude Code那事情很简单把 skills 丢进~/.claude/skills就完事。但现实是很多人像我一样Claude Code 和 Codex 混着用甚至还有 OpenCode、Cline 之类的工具可能随时进场。我最初的痛苦很具体给 Claude Code 写了“前端开发 SOP”这个 skill内容包含项目目录规范、组件写法、样式约定、提交信息的格式。用了两天觉得挺好切到 Codex 干活时却发现它完全不认识这套规范。我又在 Codex 的 AGENTS.md 里重新写了一遍内容几乎一样但格式要按 AGENTS.md 的语法来。到第三次维护的时候两边内容已经出现偏差Claude Code 那边多了一条移动端样式规则Codex 这边还停留在旧版本。这种情况就像同一个岗位招了三个部门每个部门各发一本不一样的新员工手册关键是手册里面一半内容还是一样的。你问哪个是准的没人知道。1.2 Skills 到底是什么它在 Agent 工作流里扮演什么角色先说清楚概念不然后面讲方案会懵。Skills 本质上是一组“给 Agent 看的情境化指令包”它不是一个普通提示词文件而是一个带目录结构的上下文工具。一个 skill 的核心是SKILL.md这个文件最开头有一段 YAML 格式的 front matter里面写了 skill 的 name、description、以及它适合在什么场景下被触发。正文部分才是真正的指令内容通常包含操作流程、代码规范、注意事项、示例模板等。Claude Code 的工作机制是每次开始干活前Agent 会扫描 skills 目录把每个 skill 的 name 和 description 拿出来做一次语义匹配。如果你的任务描述和某个 skill 的 description 对得上它就把这个 skill 的完整内容注入到当前上下文中然后基于这套规则来执行任务。这就是为什么 description 写得好不好直接影响 skill 会不会被触发——它重要到值得你专门花时间去优化。为了最大化可复用性我建议你把 skill 当作“一个岗位的操作手册”来设计而不是“一个任务的提示词”。操作手册写清楚流程、标准和模板提示词解决的是单次任务的具体指令。前者可以跨项目复用后者换个任务就废了。2. 统一管理方案的整体架构设计2.1 核心思路中心仓库 三套接入路径我的方案核心就一句话所有 Skills 统一存放在一个独立的 Git 仓库里然后通过三种不同的接入路径分发给不同 Agent。第一种是原生目录方式Claude Code 能直接读取软链接挂载的目录这是最省事的方式。第二种是导入生成方式针对 Codex 这种没有原生 Skills 机制的 Agent写一个脚本把多个 SKILL.md 合并生成一份 AGENTS.md让它也能消费同一套规则。第三种是 CI/手动拉取方式适合团队协作场景团队成员克隆仓库后运行一个安装脚本一秒钟完成全部 Agent 的配置。为什么要用中心仓库而不是各自维护因为单一数据源是这套方案的核心原则。规则只在一个地方维护其他 Agent 通过不同形式引用或生成副本。这样改一条规范所有 Agent 下次任务立刻生效不会出现两边不一致的问题。有了这个架构再去选具体接入方案就清晰很多。我的经验是能软链就软链不能软链就生成尽量不要手动复制。2.2 建议的目录规范与命名约定统一仓库想跑起来第一件要做的事是定目录规范和命名。我目前的仓库结构长这样~/agents-super-skills/ ├── skills/ │ ├── frontend-sop/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── component-template.tsx │ ├── python-project-template/ │ │ └── SKILL.md │ ├── academic-research/ │ │ ├── SKILL.md │ │ └── prompts/ │ │ └── paper-summary.md │ └── commit-style/ │ └── SKILL.md ├── scripts/ │ ├── sync_to_claude.sh │ └── build_agents_md.py └── README.md几个规范我给到明确的约定目录名统一用小写字母加连字符不要用空格、下划线或中文。原因很简单Linux/macOS 下文件系统大小写敏感空格会带来转义麻烦下划线在某些工具里触发词解析会出问题。skill 内部统一放一个SKILL.md辅助模板放在templates/子目录公共提示词片段放在prompts/子目录。谁写的新规范不按这个来一票否决别问为什么。2.3 三种接入方案的选型对比方案选型我踩过一轮把对比结论直接放出来。方案优点缺点适用场景符号链接软链改动即时生效单一数据源Windows 下需要管理员权限或开发者模式单机多 Agent 使用跨项目复用脚本生成AGENTS.md兼容没有原生 Skills 机制的 Agent可定制格式每次修改后需要重新运行脚本Codex 等工具接入Git 子模块 安装脚本团队分发方便版本可追溯流程较重需要大家遵守操作流程多人团队统一规范我自己的实际组合是本机用软链给 Codex 用脚本生成团队里跑安装脚本。三套互不冲突也不用重复写内容。3. Claude Code 侧的接入方式与配置细节3.1 Claude Code 读取 Skills 的位置与优先级Claude Code 读取 Skills 有两个位置一个是用户级目录~/.claude/skills/它对所有项目生效另一个是项目级目录.claude/skills/只对当前项目生效。两个位置的优先级是项目级高于用户级同名 skill 会以项目级为准。这意味着两个很关键的坑第一个人通用的规范放用户级目录就够不需要每个项目复制一份第二如果你在用户级目录挂了一个frontend-sop某项目又放了一个同名的项目会默默覆盖掉用户级配置而且不会报错。排查时如果发现 skill 行为和你预期不一致优先检查是不是存在同名覆盖。3.2 用软链把共享目录挂载进 Claude Code要在用户级目录里挂载共享仓库里的 skills方法很简单。Linux/macOS 下用ln -sfnWindows 下用mklink /D需要管理员权限。mkdir -p ~/.claude/skills ln -sfn ~/agents-super-skills/skills/frontend-sop ~/.claude/skills/frontend-sop ln -sfn ~/agents-super-skills/skills/commit-style ~/.claude/skills/commit-style这里有一个非常重要的细节软链的是 skill 目录本身也就是~/agents-super-skills/skills/frontend-sop而不是它的父目录skills/。如果直接把整个 skills 目录软链过去Claude Code 很可能识别不到里面的子项目。为什么我推测它扫描时是按“目录下直接包含 SKILL.md”这个模式来发现 skill 的。如果你让它扫到的是一堆子目录它就会迷失只在某些特定工具版本下能勉强识别不能靠运气。3.3 验证 Skill 是否被正确加载挂完软链后不要急着开干先验证。在 Claude Code 交互界面里直接问它你有哪些 skills 可用请列出名称和各自用途如果它能准确列出你刚挂载的技能说明加载成功。如果它说没有优先检查软链目标是否存在、路径是否正确、目录名是否和 skill 内部声明一致。还有一个简单粗暴的验证方法在/tmp目录下建一个空项目然后要求 Claude Code 严格按frontend-sop里的规范生成一个 React 组件。如果它输出的代码符合你规范里写的组件命名、样式方式、导出写法说明整套链路是通的。空项目可以排除项目级配置干扰单独验证用户级配置的效果这个技巧做排障时特别好用。4. Codex 侧的接入方式从 SKILL.md 到 AGENTS.md4.1 Codex 没有 Skills但原生支持 AGENTS.mdCodex 没有像 Claude Code 那样的 Skills 原生机制但它有一个自己的东西叫 AGENTS.md。这个文件放在项目根目录Codex 每次在该项目下执行任务时会读取 AGENTS.md 里的内容作为行为基准作用和 Claude Code 的 skill 有七成相似。AGENTS.md 不是给单个任务的提示词而是给一个项目的全局规则集。你可以在里面写代码规范、架构约束、工作流偏好、禁区列表。Claude Code 的 skill 是按任务触发的“按需指令包”而 AGENTS.md 是常驻全局的“行为基准”。两者的触发机制不一样设计思路上要先调整。要理解这个差异可以这样类比Claude Code 的 skills 像一本本按场景打开的手册你说“帮我写前端组件”它就翻开《前端开发 SOP》你不提它就不看Codex 的 AGENTS.md 像办公室墙上贴的员工守则你只要在这个工位干活它就在那里。4.2 让同一份 SKILL.md 为 Codex 服务既然两边机制不同硬把 SKILL.md 塞给 Codex 是行不通的。我的方案是写一个转换脚本把若干 SKILL.md 合并、加工自动生成一份 AGENTS.md。这个脚本的核心逻辑其实很简单遍历统一仓库的skills/目录把每个子目录里的SKILL.md内容按一定顺序拼接到一个大文件里。但拼接的时候有讲究不能只是把所有文件首尾相连因为 AGENTS.md 的全量注入特性和 SKILL.md 的按需加载不同所有东西一股脑灌进去上下文会被不重要的信息浪费掉。所以我把 skill 内容分成了两面战略规则和操作细则。战略规则——比如代码规范核心条目、提交信息格式、命名约定这些“必须始终遵守”的内容拼到 AGENTS.md 前面作为全局约束操作细则——比如某个任务的详细步骤、依赖安装方式这类按需执行的内容保留在 SKILL.md 里通过注释或 CD 引用方式挂载让 Agent 在需要时再去看原文。做一个调整让 Codex 也能读到仓库里的原始 SKILL.md 文件。调整方式很简单在 AGENTS.md 里加一条说明遇到下述任务时先阅读~/agents-super-skills/skills/academic-research/SKILL.md并严格按其中的流程执行。Codex 接受了这个规则执行相关任务前会先读取那个文件。这样战略性指令在 AGENTS.md 里常驻操作步骤文本落到本地文件需要时再读两级配合效果很好。转换脚本我用 Python 写完整代码放在下面你可以直接复制改改#!/usr/bin/env python3 from pathlib import Path SKILLS_DIR Path.home() / agents-super-skills / skills AGENTS_MD_SOURCE Path.home() / agents-super-skills / templates / AGENTS.source.md OUTPUT_PATH Path.home() / agents-super-skills / generated / AGENTS.md GLOBAL_RULES [commit-style] def build(): lines [] lines.append(# AI Agent 行为规范) lines.append() # 先拼全局战略规则 lines.append(## 必须遵守的全局规范) lines.append() for rule_name in GLOBAL_RULES: rule_file SKILLS_DIR / rule_name / SKILL.md if rule_file.exists(): lines.append(rule_file.read_text(encodingutf-8)) lines.append() # 再从源模板拼按需引用规则 source Path(AGENTS_MD_SOURCE) if source.exists(): lines.append(## 按需加载的技能) lines.append() lines.append(source.read_text(encodingutf-8)) lines.append() OUTPUT_PATH.parent.mkdir(parentsTrue, exist_okTrue) OUTPUT_PATH.write_text(\n.join(lines), encodingutf-8) print(fAGENTS.md 已生成到 {OUTPUT_PATH}) if __name__ __main__: build()这个脚本的关键思想是“两级混合”先放全时段约束再放按需引用规则。避免了把所有 skill 的全文一股脑灌进去导致上下文膨胀的问题。按需加载这一层的模式也很固定我现在的 AGENTS.source.md 模板里维护一个规则清单长这样遇到前端页面开发、React 组件编写任务时 1. 阅读 ~/agents-super-skills/skills/frontend-sop/SKILL.md 2. 严格按其目录规范、组件写法、样式约定执行 遇到论文阅读、文献综述、学术写作任务时 1. 阅读 ~/agents-super-skills/skills/academic-research/SKILL.md 2. 严格按其信息提取格式、引用规范执行 遇到 Python 项目搭建、脚本编写任务时 1. 阅读 ~/agents-super-skills/skills/python-project-template/SKILL.md 2. 严格按其项目结构、依赖管理方式执行Codex 的路径处理通常是相对于当前工作目录或用户主目录这里的~/agents-super-skills在 Linux/macOS 下可直接生效。Windows 下建议确认 Codex 对该路径的支持情况必要时改成绝对路径。4.3 不同 Agent 之间的行为差异怎么包容Claude Code 和 Codex 虽然都读 Markdown 指令但对同一份内容的解释风格会不一样。Claude Code 擅长按步骤执行比较跟手Codex 更有“主见”有时候给的意见和你的规范不一致需要后续做一致性权衡。我实际遇到的典型情况我在 commit-style 里规定 commit message 格式为type(scope): description并明确 type 只能是feat/fix/docs/refactor/chore五种。Claude Code 会老老实实按这个格式生成 commit messageCodex 则偶尔自作主张在 description 里加“相关文件”之类的补充信息。解决方式很朴素规则文本里把正例和反例都写出来不给 Agent 发挥空间。比如必须使用以下前缀之一feat, fix, docs, refactor, chore。 反例feat(ui): 添加按钮并修改样式并调整布局不允许多个变更混在一个 commit 里 正例feat(ui): 新增移动端底部导航栏这种“正反例对照”的写法对 Claude Code 和 Codex 都有效而且非常省 tokens。与其写一大段解释不如直接告诉它什么算对、什么算错。另外建议把工具专属的差异点放到各自配置层不要污染共享仓库。比如某些命令是 Claude Code 特有的/compact就没必要写进共享 skillCodex 特有的 REV 检查命令同理。5. 实操全过程一步一步搭起统一管理5.1 初始化仓库并挂载第一个 Skill现在把完整的操作过程走一遍。先建仓库mkdir -p ~/agents-super-skills/{skills,scripts,templates} cd ~/agents-super-skills git init新建第一个 skill拿 commit-style 举例mkdir -p skills/commit-style touch skills/commit-style/SKILL.md编辑SKILL.md--- name: commit-style description: 用于生成符合规范的 git commit message。当需要提交代码时使用尤其是多人协作项目。 --- # Commit Message 规范 1. 格式type(scope): description 2. type 可选值feat, fix, docs, refactor, chore 3. scope 写改动模块名比如 ui, api, utils 4. description 用中文简洁说明本次改动做什么 反例fix: 修复bug 正例fix(api): 修复用户登录时验证码过期未提示的问题 注意 - 禁止在 message 中写修复了哪个 issue 编号以外的冗余信息 - 禁止一句话包含多个逻辑变更验证这个 skill 是否能被正确的 Agent 识别然后挂载到 Claude Codemkdir -p ~/.claude/skills ln -sfn ~/agents-super-skills/skills/commit-style ~/.claude/skills/commit-style去 Claude Code 里问一句“提交代码时 message 怎么写”看它给不给上面那套规范。给得出来挂载成功。5.2 为 Codex 生成 AGENTS.md接着跑刚才的 Python 脚本为 Codex 整理规则cd ~/agents-super-skills python3 scripts/build_agents_md.py会看到输出AGENTS.md 已生成到 ~/agents-super-skills/generated/AGENTS.md在你想让 Codex 生效的项目根目录下把生成文件复制过去cp ~/agents-super-skills/generated/AGENTS.md /path/to/your/project/AGENTS.md或者更推荐的方式是做一个软链避免复制后不同步ln -sfn ~/agents-super-skills/generated/AGENTS.md /path/to/your/project/AGENTS.md注意一点AGENTS.md 如果直接软链到项目里要保证~/agents-super-skills这个路径在所有开发者机器上保持一致。团队协作时如果路径不固定建议还是让脚本生成后落到项目内的AGENTS.md把它提交进 Git 仓库。5.3 团队分发安装脚本一次搞定如果你要带着团队一起玩这套方案建议封装一个一键安装脚本让同事克隆完仓库后跑一条命令就能完成所有配置。脚本逻辑很简单遍历skills/下的所有子目录逐个创建软链到~/.claude/skills/然后调用 Python 脚本生成 AGENTS.md最后打印操作提示提醒团队成员在各自项目里引用这个 AGENTS.md。我这里给出一个 bash 脚本的雏形#!/usr/bin/env bash set -euo pipefail SKILLS_DIR$HOME/agents-super-skills/skills CLAUDE_SKILLS_DIR$HOME/.claude/skills mkdir -p $CLAUDE_SKILLS_DIR for skill_path in $SKILLS_DIR/*; do skill_name$(basename $skill_path) ln -sfn $skill_path $CLAUDE_SKILLS_DIR/$skill_name echo linked $skill_name done python3 $HOME/agents-super-skills/scripts/build_agents_md.py echo 安装完成。 echo Claude Code 已映射 $CLAUDE_SKILLS_DIR echo AGENTS.md 已生成到 $HOME/agents-super-skills/generated/AGENTS.md把脚本保存为scripts/install.sh加执行权限团队成员克隆后直接跑。这个脚本我实测在 macOS 和 Linux 上都能跑通Windows 用户大概率需要改用mklink本质原理一样路径写法注意一下即可。6. 踩坑实录与排查技巧6.1 常见问题速查表这一路踩了不少坑整理成速查表遇到问题直接对着查。问题可能原因解决方式Claude Code 识别不到 skill软链指向了父目录而不是子目录检查软链路径确保指向包含 SKILL.md 的直接目录skill 不触发description 写得太泛或者包含多个意图重写 description让它语义清晰、场景明确同名 skill 行为异常项目级.claude/skills覆盖了用户级检查项目目录下是否有同名技能软链失效OneDrive/坚果云等网盘同步目录干扰或磁盘更换后路径变更避免把仓库放在云同步目录里改用绝对路径重建软链Codex 没按 AGENTS.md 执行AGENTS.md 不在项目根目录或文件名不正确确认文件在项目根目录且命名为 AGENTS.mdAGENTS.md 内容太长导致上下文浪费把操作细则全量拼进去了只拼全局规则操作步骤改成按需读取 SKILL.mdWindows 下软链失败默认无权限创建符号链接启用开发者模式或改用mklink /D并管理员权限运行多个 Agent 对同一指令理解不一致指令文本存在歧义没有正反例在规则中加入正例和反例缩小模型发挥空间修改 SKILL.md 后工具不生效Claude Code 内部有缓存重启会话或执行一次/clear后再测试团队里有人漏拉最新规则安装脚本不是自动执行的建议增加 git hook 或 CI 检查提交时提示更新规则包6.2 多 Agent 指令冲突怎么办最后聊一个敏感但很现实的问题当 Claude Code 和 Codex 对同一份指令理解不一致时该听谁的。我的原则是规则本身用“结构化、尽可能少的文字”描述减少解释空间。你在同一份 SKILL.md 里用列表而不是大段散文用正反例而不是形容词约束用表格而不是叙述。这样两个 Agent 对规则的解析结果都会更接近。如果冲突依然存在你要区分是规则问题还是模型行为差异。规则问题就改规则模型行为差异就接受它在各自工具的配置层做微调。比如 Claude Code 遵守得很好但 Codex 经常会多带一句无关紧要的话那就接受这个差异不要强行让两边行为完全一致。我是这么判断的共享层保持原则一致工具层允许各自风格。这既保证了多 Agent 协同时的行为基线统一又给每个工具留了足够的个性空间。和团队管理一个道理核心价值观统一具体风格无所谓。6.3 关于多 Agent 联调时第三方接口报错的排查心法在实际多 Agent 工作流里偶尔还会遇到与工具链联调有关的诡异报错。比如热搜词里有一条“cc switch local proxy failed while handling codex endpoint /responses. provider...”开头的错误这种在不同工具切换时偶发的连接异常通常和本地依赖服务、鉴权配置或 base URL 设置有关。排查时我按三步走先看配置文件里填写的端点地址是否正确再看本地服务是否正常启动在监听对应端口最后核对鉴权信息和鉴权方式是否更新。大多数问题都是这三处里的一处。两边工具调用第三方服务的模式不同切换后配置残留会互相干扰所以第一反应应是确认当前工具用的是哪套配置而不是急着改代码。这种问题反倒暴露了统一管理的一个衍生价值配置也应当像 Skills 一样集中维护而不是散落在每个工具的独立配置里。写在最后的经验之谈这套统一管理方案我跑了大概两个月最大的感受不是“省了多少配置时间”而是“团队规范终于有了单一事实来源”。新的前端规范、新的 commit 格式、新的研究流程只要在中心仓库改一次Claude Code 和 Codex 下次干活就自动按新规则来。不用挨个项目去通知不用怕有人忘更新这个确定性本身就很值钱。如果你要开始做我建议第一件事不是写脚本而是先把你手头重复配置的内容盘点一遍哪些是你希望所有 Agent 无条件遵守的哪些是按任务才需要的。想清楚这个边界方案自然就出来了。最后再分享一个小技巧统一仓库记得经常提交 commit每次改动写清楚原因这样当你发现某个 Agent 行为突然变化时翻 git log 立刻能定位是哪条规则导致的排查效率极高。