最近一直在折腾多Agent的工作流最大的感受是工具越用越多配置越来越散。Claude Code里配了一套Skills换个Codex又要重新建一套同一个任务在两个Agent里表现还不一样维护成本直接翻倍。今天想聊的就是怎么把Claude Code和Codex的Skills收编成一套一处维护、两边生效顺便把我踩过的坑和最终落地的方案一起整理出来。这篇文章适合谁看一是已经用Claude Code或Codex写过自动化任务的开发者二是团队里多人共用Agent、想让技能库标准化的人三是刚听说Skills但被各种零散教程绕晕的新手。内容会从机制原理讲到目录设计再到可直接抄的代码和脚本最后是问题排查尽量让不同基础的人都能跟着搭起来。1. 为什么需要一套Skills多Agent共享1.1 Skills到底是什么为什么Agent越来越依赖它先说清楚Skills这个概念的定位。它本质上是一种“可复用的技能包”里面放一个Markdown格式的说明文件告诉AI模型“在什么场景下、按什么步骤、用什么工具来完成一类任务”。比如你写一个“前端组件生成”Skill模型遇到“帮我写一个带搜索功能的表格组件”时就会自动加载这个技能包的规范而不是临时凭感觉生成代码。这个机制比单纯在对话里写提示词强在哪提示词是一次性的换个会话就丢了Skills是持久化的只要放在固定目录里每次启动Agent都能读到。而且Skills可以把一套复杂的操作流程拆成步骤、模板、脚本和检查清单让模型输出更稳定、更符合团队规范。我自己试下来的感受是没有Skills的时候Agent像是个聪明但不熟悉业务的新人每次都要重新交代规矩配好Skills之后它才真正像“老员工”。Claude Code和Codex这两款工具都在往这个方向发力。Claude Code会把Skills放在用户级或项目级目录里Codex也支持类似的技能包机制。但问题在于两边读的目录不一样支持的文件字段也有细微差别很多人就在这里开始重复造轮子了。1.2 各自独立配置的痛点在哪里一开始我也走的是“各配各”的老路在~/.claude/skills里放了一套常用的代码审查、前端开发、数据库优化技能又在~/.codex/skills里复制了一份。表面上看起来很稳妥实际用起来全是问题。第一个痛点是内容漂移。同一份“代码审查清单”我在Claude Code这边改了三条规则Codex那边还是旧的。等到某次Codex审查结果和Claude Code对不上我才发现两份配置早就分叉了。第二个痛点是维护成本翻倍。每次新增一个Skill至少要写两遍、放两个目录、记两种命名规范。如果团队里有五个人每个人再各自维护自己的副本那配置散落程度简直无法收拾。第三个痛点是体验不一致。同一个任务在两边触发效果不一样调试的时候还得先搞清楚“这次是哪个Agent在处理”非常心累。所以“一套Skills多个Agent共享”不只是一个偷懒技巧而是一个真正值得认真设计的基础设施问题。目标很明确单一来源、同步生效、可版本管理、可团队共享。1.3 统一管理的目标与适用场景统一管理的核心思路是建立一个“技能单一来源仓库”Single Source of Truth然后用符号链接或同步脚本把同一份技能包暴露给不同Agent各自约定的读取目录。这样你只需要维护一份内容Claude Code和Codex都能读到并且永远保持版本一致。这个方法不只适用于Claude Code和Codex也适用于任何支持“目录Markdown技能包”机制的Agent工具比如一些基于开源框架自建的Agent服务。适合的场景包括个人开发者同时在多个命令行Agent之间切换团队把技能库放在Git仓库里统一评审和分发需要在CI里批量校验技能包格式的工程化团队。如果你只是偶尔用一下Agent不写复杂技能包那这个方案确实有点重。但只要你的Skill数量超过三五个或者你身边有不止一个人在维护Agent配置这套方案省下的时间绝对值回票价。2. Skills机制原理与跨Agent兼容设计2.1 Claude Code的Skills机制Claude Code对Skills的支持核心就是一个目录约定它会在用户级目录~/.claude/skills/和项目级目录.claude/skills/下扫描子目录每个子目录代表一个Skill里面必须有一个SKILL.md作为入口文件。这个文件用Markdown写成顶部带一段YAML frontmatter用来声明技能名称、描述等元信息正文则是具体的操作说明。运行时Claude Code会把前端输入的描述信息交给模型做语义匹配一旦模型判断当前任务命中某个Skill就会把对应的SKILL.md内容注入上下文并允许该技能通过工具读取同目录下的附加资源文件比如模板、脚本、检查清单。这里最关键的一点是模型依赖“description”来判断什么时候该用这个技能。如果你的description写得太泛模型就会“想用又不敢用”写得太窄就漏匹配。另外Claude Code还有/skills命令可以查看当前环境里已加载的技能列表调试时可以先用这个命令确认技能有没有被正确扫描到。这个命令我几乎每次调Skills都会用比盲猜高效很多。2.2 Codex的Skills机制Codex对Skills的支持思路和Claude Code基本一致也是“目录 SKILL.md”的格式常见的扫描路径包括用户级目录~/.codex/skills/和项目级目录.codex/skills/。你同样需要给每个技能包建一个独立目录在SKILL.md里写frontmatter和正文。不过两者有个很实际的差异Codex对SKILL.md的字段解析没有Claude Code那么丰富。Claude Code可以识别name、description、allowed-tools、license等字段Codex则更强调基本的name和description。跨工具共享时如果你在frontmatter里塞了大量Claude私有字段Codex大概率会忽略它但这不会报错只会导致技能行为不符合预期。还有一个差异是上下文组织方式。Codex比较依赖AGENTS.md这类项目规则文件来约束全局行为Skills更多承担“特定任务专用流程”的角色。也就是说在Codex里Skills和项目规则是互补关系而不是替代关系。这一点在多Agent共享时要留意Skills负责“怎么做某类任务”AGENTS.md或项目配置负责“整个项目的整体约束”。2.3 两个体系之间的差异与兼容点把两边的机制放在一起对比能清楚看到兼容性的边界在哪里。我整理了一张表对比项Claude CodeCodex用户级Skills目录~/.claude/skills/~/.codex/skills/项目级Skills目录.claude/skills/.codex/skills/技能入口文件SKILL.mdSKILL.mdfrontmatter公共字段name、description等name、description等高级私有字段allowed-tools、license、version解析策略保守可能忽略技能加载命令/skills通过CLI日志或调试输出查看从表里可以看出两边的兼容基础就是“目录 SKILL.md name/description公共字段”。所以统一管理方案的设计原则就清晰了frontmatter只写公共字段复杂约束写进正文和附加文件里。这样Claude Code能完整解析Codex也不会因为未知字段出现奇怪行为。3. 统一Skills仓库的目录设计与文件规范3.1 仓库根目录结构一个理想的统一Skills仓库应该从根目录开始就是自解释的。我的推荐结构是这样~/ai-skills/ ├── README.md ├── sync.sh ├── sync.ps1 ├── lint.sh └── skills/ ├── code-review/ │ ├── SKILL.md │ ├── checklist.md │ └── scripts/ │ └── extract_diff.py ├── frontend-component/ │ ├── SKILL.md │ ├── templates/ │ │ └── component.tsx │ └── examples/ │ └── sample.md └── db-optimization/ ├── SKILL.md └── references/ └── index-patterns.md根目录的README.md不是摆设要写清楚这个仓库是什么、包含哪些技能、如何安装、如何新增技能。sync.sh和sync.ps1分别是macOS/Linux和Windows下的同步脚本负责把skills/下所有技能包链接到Claude Code和Codex的目录。lint.sh用来统一校验SKILL.md格式CI或本地提交前跑一遍。skills/目录下每个子文件夹就是一个技能包。技能包命名我建议一律用小写字母加连字符比如code-review、frontend-component不要用空格、中文或驼峰。原因很简单目录名可能出现在文件路径、脚本变量和日志里越是简单通用的命名越不容易踩坑。3.2 SKILL.md的frontmatter怎么写SKILL.md的frontmatter是整个技能包的核心因为Agent主要靠它来判断“何时触发”和“基本信息”。为了兼顾Claude Code和Codex我推荐只使用公共基础字段--- name: frontend-component description: 当用户需要生成或修改前端React组件、页面、样式文件时使用。包含组件模板、样式规范、测试文件生成等场景。 ---name字段是技能包的唯一标识最好和目录名保持一致。description字段是最关键的部分它直接决定模型能不能在合适的时机激活这个技能。写description时要注意写场景不写功能说明书。不要写“这是一个前端组件生成技能支持XXX功能”而要写“当用户需要……时使用适用于……场景”。如果你需要给某个技能加版本号、作者或许可证建议放在附加文件里比如在技能包目录里建一个meta.yaml而不是塞进SKILL.md的frontmatter。原因我前面讲过Codex对未知字段的处理比较保守与其赌工具兼容性不如在结构上彻底绕开。3.3 描述信息与触发匹配的优化技巧description的写法值得单独拿出来说因为这是“同样的技能包在不同Agent里表现差异最大”的地方。我踩过最典型的坑是把description写成了功能清单比如“支持代码审查、支持漏洞扫描、支持性能评估”结果Claude Code很容易误触发而Codex又经常漏触发。后来我总结出一套写法场景前置 需求样例 边界说明。场景前置就是开头直接说“当用户需要……时”需求样例就是列举几种用户可能的说法帮助模型建立联想边界说明就是诚实交代“不要用这个技能处理哪些情况”避免过度触发。举个例子同样是“数据库优化”技能低质量的description可能是“数据库优化工具包”合格的description大概是description: 当用户需要分析SQL慢查询、优化索引结构、设计数据库表或排查查询性能问题时使用。典型说法包括“帮我看看这条SQL为什么慢”“这个表要不要加索引”“数据库查询很卡”。这样的description既给了触发词又给了“为什么”和“什么时候不该用”的边界。模型在语义匹配时参考信息越多命中率越高。4. 落地实操从零搭建共享Skills方案4.1 初始化统一Skills仓库下面是一套可以直接照着做的步骤我默认你已经装好了Claude Code和Codex CLI且系统是macOS或Linux。Windows用户的差异我会在后面单独说。第一步创建仓库目录和基本结构mkdir -p ~/ai-skills/skills cd ~/ai-skills git init第二步创建根目录README简单说明仓库用途和用法顺手把目录结构画进去。这一步不是形式主义团队协作时它能帮新成员三分钟上手。第三步创建你的第一个技能包目录并编写SKILL.md。以“前端组件生成”技能为例mkdir -p skills/frontend-component/templates在skills/frontend-component/SKILL.md里写入--- name: frontend-component description: 当用户需要生成或修改前端React组件、页面、样式文件时使用。典型诉求包括“写一个表格组件”“加一个筛选器”“把这个弹窗改成受控组件”。 --- # 前端组件生成 ## 适用场景 - 根据需求描述生成新的React组件 - 修改已有组件的结构、样式或交互逻辑 - 生成配套的样式文件和基础测试 ## 执行步骤 1. 确认组件类型是展示组件还是容器组件是否需要状态管理。 2. 检查项目里是否已有类似组件避免重复实现。 3. 按照模板生成组件代码入口组件放在 templates/component.tsx。 4. 生成样式文件命名与组件保持一致。 5. 生成基础测试文件覆盖默认渲染和核心交互。 ## 输出要求 - 组件代码必须使用TypeScript。 - 样式文件使用CSS Modules。 - 如果需求不明确先列出问题清单不要擅自假设。第四步提交初始版本git add . git commit -m init: add frontend-component skill到这里统一仓库的雏形就有了。后面所有的新技能都按照同样的结构往里加保持“一个技能包一个目录目录内必有SKILL.md”这条铁律。4.2 用符号链接打通Claude Code与Codex仓库建好之后关键的一步是让Claude Code和Codex都能读到同一份技能包。我没有选择“复制文件过去”而是用符号链接symlink。原因很简单符号链接不复制内容只创建一个引用路径。你改了源文件两边立即生效彻底解决内容漂移问题。在macOS或Linux下先确保两边的skills目录存在然后逐个建立链接mkdir -p ~/.claude/skills mkdir -p ~/.codex/skills ln -sfn ~/ai-skills/skills/frontend-component ~/.claude/skills/frontend-component ln -sfn ~/ai-skills/skills/frontend-component ~/.codex/skills/frontend-component如果技能很多逐个敲太累直接用通配符循环for skill in ~/ai-skills/skills/*/; do name$(basename $skill) ln -sfn $skill ~/.claude/skills/$name ln -sfn $skill ~/.codex/skills/$name done注意ln -sfn里的-n参数很关键它表示把目标当作目录处理防止在已存在同名符号链接时出现嵌套链接的诡异问题。我在这上面吃过亏不加-n会导致链接套链接最终Agent扫不到技能。建立链接之后可以用下面的命令验证ls -l ~/.claude/skills/ ls -l ~/.codex/skills/如果看到类似frontend-component - /Users/yourname/ai-skills/skills/frontend-component的输出说明链接建立成功。注意检查链接目标是否存在如果源目录被移动或删除链接会变成“断链”Agent会静默跳过不会报错。4.3 一键同步脚本与Git版本管理手工每个技能敲一次链接还是不够工程化所以我把同步逻辑写成了一个脚本统一仓库里长期维护。下面是一个macOS/Linux的sync.sh版本#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) SKILLS_SOURCE$SCRIPT_DIR/skills TARGETS( $HOME/.claude/skills $HOME/.codex/skills ) FAILED0 for target in ${TARGETS[]}; do mkdir -p $target for skill in $SKILLS_SOURCE/*/; do name$(basename $skill) ln -sfn $skill $target/$name echo linked: $name - $target/$name done done if [ $FAILED -ne 0 ]; then echo sync finished with errors exit 1 fi echo sync complete这里用set -euo pipefail防止脚本在中间出错时继续往下跑保证失败时能注意到。每次新增技能包后只需要运行一次chmod x sync.sh ./sync.shWindows用户可以用PowerShell脚本$source Join-Path $PSScriptRoot skills $targets ( (Join-Path $HOME .claude\skills), (Join-Path $HOME .codex\skills) ) foreach ($target in $targets) { New-Item -ItemType Directory -Force -Path $target | Out-Null Get-ChildItem -Path $source -Directory | ForEach-Object { $link Join-Path $target $_.Name if (Test-Path $link) { Remove-Item $link -Force } New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null Write-Host linked: $($_.Name) - $link } } Write-Host sync complete然后是Git版本管理。我坚持把每个技能包作为独立提交提交信息写清楚“新增了哪个技能、为什么要加”。如果要发版可以给仓库打tag比如v1.0.0。团队协作时成员拉取仓库后执行一次./sync.sh所有技能就都到位了。想再进一步可以在仓库里加一个lint.sh用脚本校验所有SKILL.md是否包含name和description字段#!/usr/bin/env bash set -euo pipefail for file in skills/*/SKILL.md; do if ! grep -q ^name: $file; then echo missing name in $file exit 1 fi if ! grep -q ^description: $file; then echo missing description in $file exit 1 fi echo ok: $file done这个脚本放在pre-commit钩子里每次提交前自动跑一遍能拦截掉大量低级错误。4.4 在项目中启用与验证链接建好之后不用重启终端新开一个Claude Code会话输入/skills如果能看到frontend-component等技能名说明扫描成功。Codex这边可以运行codex进入交互模式然后直接问一个和技能描述吻合的问题比如“帮我生成一个带搜索功能的表格组件”观察它是否加载了对应技能。如果项目要求“技能只在特定仓库里生效”而不是全局生效可以把符号链接放到项目级目录也就是在项目根目录下建.claude/skills和.codex/skills同样是指向统一仓库里的技能目录。这种方式更适合多项目多规则的团队因为不同项目可以按需启用不同技能集。有一点要提醒项目级目录默认会被Git追踪所以要么把.claude/skills和.codex/skills加入.gitignore要么让团队成员各自执行同步脚本。我个人建议把这两个目录加入.gitignore因为技能包的真正源头是统一仓库项目里不应该再存一份副本。5. 常见问题与排查技巧实录5.1 Skill没有被识别这是最常遇到的问题。技能明明放进目录了Agent却视而不见。我的排查顺序是这样的第一检查目录层级。SKILL.md必须放在skills/skill-name/下不能直接放在skills/里也不能多包一层。比如skills/code-review/SKILL.md是对的skills/code-review/skill/SKILL.md是错的。第二检查frontmatter。用head -5 SKILL.md看一眼确认第一行是---紧接着是name和description字段然后再以---结束。缺失任何一段解析器都会跳过整个文件。第三检查链接是否健康。如果用了符号链接执行ls -l看链接指向是否存在如果指向的目录被移动过链接就会断掉Agent会静默忽略。此时重新运行同步脚本即可。第四检查用户级目录是否拼写正确。Claude Code用户级目录是小写.claudeCodex是小写.codex大小写敏感系统上写错了就完全扫不到。5.2 描述触发不准技能能被识别但该触发时不触发不该触发时乱触发八成是description写得有问题。我之前写过一个“代码审查”技能的description“代码审查工具”结果给Agent说“帮我看看这段代码”的时候它不触发说“生成代码审查报告”的时候反而偶尔触发。后来我把description改成了场景化描述“当用户需要检查代码质量、发现潜在bug、评审Pull Request或生成代码审查意见时使用。典型说法包括‘帮我review一下这段代码’‘这个PR有没有问题’。”改完之后触发率明显提升。如果发现触发过于频繁就加一句“仅适用于……场景”明确边界。还有一个经验是description不要太长但也别太短。我一般控制在50到150个汉字之间既给足语义线索又不至于让模型在匹配时被多余信息干扰。5.3 符号链接在Windows下的坑Windows默认不允许普通用户直接创建符号链接除非开启开发者模式或以管理员身份运行。我在Windows上试过New-Item -ItemType SymbolicLink时报错后来换成Junction类型就顺利了。Junction和SymbolicLink的区别在于Junction只支持目录且不需要管理员权限在部分配置下对于技能包这种纯目录场景完全够用。PowerShell脚本里用-ItemType Junction就是基于这个原因。另外Windows下不要用Remove-Item删除链接指向的源目录它可能递归删除真正的文件这一点要格外小心删链接时用Remove-Item $link只删链接本身。5.4 Agent执行中断或权限错误有时候Agent能识别技能但执行过程中报“agent execution terminated due to error”或者提示命令找不到、文件读取失败。我的排查经验是确认技能包里引用的脚本是否有执行权限。如果SKILL.md里让模型运行scripts/xxx.py请先手动执行一遍python3 skills/xxx/scripts/xxx.py --help确认无误再让Agent调用。确认技能包内文件的路径描述使用相对路径并且以技能包目录为基准。比如模板文件写templates/component.tsx不要写绝对路径因为不同机器上仓库路径不一样。确认Agent的工作目录权限。有些工具会限制只能访问项目目录内的文件如果技能文件在用户主目录深处可能会因为路径越权而失败。我还遇到过因为技能脚本里依赖的Python包没装导致的报错。处理办法是在技能包目录里放一个requirements.txt并在SKILL.md里写明“使用本技能前需要安装以下依赖”。能提前写清楚的事情千万不要留给运行时才猜。6. 个人心得与扩展建议6.1 我踩过的几个坑这个方案我已经跑了几个月踩过的坑比想象中多。最值得说的是三个。第一个是曾经把同一个技能在Claude Code和Codex里各写了一份两边内容渐渐不一致后来排查问题时才发现某条规则只在一半的Agent里生效。用统一仓库加符号链接之后这个问题彻底消失了因为物理上就只有一份文件。第二个坑是过度设计。一开始我把frontmatter塞满了version、author、allowed-tools等字段还写了自定义解析逻辑结果Codex那边表现很奇怪。后来老老实实只用name和description复杂逻辑全部写进正文反而两边都稳定。跨工具场景里克制比炫技重要。第三个坑是测试不充分。新增技能后只验证了一个Agent另一个没测结果某次紧急任务正好走到另一个Agent上才发现技能压根没被识别。现在我的习惯是任何技能变更之后两边都会各跑一次最小测试用例确认触发、加载、执行三个环节都没问题再提交。6.2 后续扩展团队共享、模板体系与自动化这套方案天然适合往团队方向扩展。你只需要把~/ai-skills换成团队共用的Git仓库再约定好命名规范和提交流程每个成员本地执行一次同步脚本就能获得完全一致的技能体验。新成员入职时跑两条命令就能把整个技能库配好不需要手动复制任何文件。进一步的话可以把技能包里的模板做得更丰富比如前端组件技能里放多种组件模板、数据库技能里放常用的索引设计样例。Skills的价值会随着模板质量和覆盖场景的增加而指数级上升。还可以考虑把lint.sh集成到CI里每次合并新技能时自动校验格式。如果你的Agent工具支持MCP也可以把一些外部数据源或内部接口封装成MCP服务把“技能包负责流程、MCP负责外部连接”结合起来。总之先把“一套Skills多Agent共享”的地基打好后面加什么扩展都会顺手很多。我自己在维护这个仓库时最大的体会是工具会变但“单一来源 自动化同步 版本管理”的思路不会过时。哪怕以后我又换了一个新的Agent工具只需要把它的技能目录加进同步脚本整个体系就能立刻复用这才是这套方案真正值钱的地方。