项目级 Skill 跨 Agent 共用的解决方案

不同 Agent 客户端对项目级 Skill 的存放目录约定各异，例如 .codex、.claude、.workbuddy 等。可以用软链接统一管理，让同一份 Skill 在多个 Agent 客户端中同时生效。

方案概述

核心做法是"一份 Skill 源文件 + 多个客户端目录软链接"。Skill 只维护一份，各客户端仍从各自约定的目录发现它，避免复制多份后内容不一致。

最终目录结构如下：

bash 复制代码

project/
├── agent-skills/
│   └── my-skill/
│       └── SKILL.md
├── .codex/skills/my-skill      -> ../../agent-skills/my-skill
├── .claude/skills/my-skill     -> ../../agent-skills/my-skill
├── .workbuddy/skills/my-skill  -> ../../agent-skills/my-skill
├── .trae/skills/my-skill       -> ../../agent-skills/my-skill
└── .zcode/skills/my-skill      -> ../../agent-skills/my-skill

约定如下：

agent-skills/ 是唯一真实内容目录。
各客户端约定目录中只放软链接，不复制 Skill 内容。
每个 Skill 独立创建链接，不直接链接整个 skills 目录，方便按客户端控制启用范围。
使用相对路径，避免仓库更换电脑、磁盘或克隆目录后链接失效。

Skill 维护人员操作步骤

维护 Skill

在 agent-skills 目录下新增或维护项目级 Skill。若 Skill 已存在，直接进入下一步。

本方案默认以 agent-skills 作为 Skill 的源目录。如需调整目录名，下文命令中的路径也要同步替换。

创建软链接

切换到项目根目录，执行下列命令，为 agent-skills 下所有包含 SKILL.md 的 Skill 批量创建软链接。命令会自动创建 .codex、.claude、.workbuddy、.trae、.zcode、.codebuddy 和 .qoder 的 skills 目录。

后续新增 Skill 后，需要再次执行命令。若需支持其他客户端，在客户端目录列表中继续补充即可。

macOS / Linux

bash 复制代码

for skill_dir in agent-skills/*/; do [ -f "$skill_dir/SKILL.md" ] || continue; skill_name="${skill_dir%/}"; skill_name="${skill_name##*/}"; for client in .codex .claude .workbuddy .trae .zcode .codebuddy .qoder; do mkdir -p "$client/skills"; link="$client/skills/$skill_name"; [ -e "$link" ] || [ -L "$link" ] || ln -s "../../agent-skills/$skill_name" "$link"; done; done

Windows PowerShell

执行前，需要以管理员身份运行命令行工具，或开启 Windows"开发者模式"：设置 → 系统 → 开发者选项 → 开发人员模式。

powershell 复制代码

$clients=@(".codex",".claude",".workbuddy",".trae",".zcode",".codebuddy",".qoder"); Get-ChildItem ".\agent-skills" -Directory | Where-Object {Test-Path (Join-Path $_.FullName "SKILL.md")} | ForEach-Object {$skillName=$_.Name; foreach($client in $clients){$skillsDir="$client\skills"; $linkPath="$skillsDir\$skillName"; New-Item -ItemType Directory -Force $skillsDir | Out-Null; $existing=Get-Item -LiteralPath $linkPath -Force -ErrorAction SilentlyContinue; if(-not $existing){cmd /c mklink /D "$linkPath" "..\..\agent-skills\$skillName"}}}

提交代码

将 agent-skills/ 源目录和批量生成的客户端软链接目录一并提交到 Git 远程仓库。

Skill 使用人员操作步骤

开启软链接功能

macOS 用户可以跳过此步。Windows 用户需要先完成一次性配置：

打开"设置 → 系统 → 开发者选项"，启用"开发人员模式"。
配置 Git：

bash 复制代码

git config --global core.symlinks true
git config --get core.symlinks

第二条命令应输出 true。

拉取并使用

正常克隆或拉取远程仓库，然后新建 Agent 会话，通过对话触发 Skill。

其他方案

也可以将 Skill 分别复制到各客户端目录，再通过脚本和 Git 钩子自动同步。但这种方式需要维护额外的同步机制，复杂度高于软链接方案，因此不作为首选。