agent-scripts：用 symlink 把多仓库技能同步给 Codex 和 Claude

一个仓库解决两种客户端的技能发现差异

Peter Steinberger 的 agent-scripts 是一个个人工具仓库，但它暴露了一个普遍问题：Codex 和 Claude Code 对技能目录的扫描规则完全不同。Codex 能递归扫描嵌套目录，所以它可以直接链接整个 `skills/` 根目录。Claude Code 只加载 `~/.claude/skills/<name>/SKILL.md`，而且只认一层目录，不扫描分类子文件夹。这个差异在 README 里写得很清楚，还标注了「verified on 2.1.197」。如果你同时用两个客户端，又维护多个仓库的技能，每次新增技能都要手动为每个客户端建立链接，这很容易出错。agent-scripts 的核心价值就是把这个过程自动化，用 symlink 而不是复制文件来保持单一事实来源。

sync-skills 的镜像机制：链接、冲突、清理

`scripts/sync-skills` 是这套工具的核心。它读取本仓库的 `skills/` 目录，以及其他仓库（比如 `../agent-skills`）中的技能，然后为每个客户端建立不同的链接结构。对 Codex，它创建整个根目录的链接，比如 `~/.codex/skills/agent-scripts -> ~/Projects/agent-scripts/skills`。对 Claude，它为每个技能单独建链接，形成一个扁平镜像。脚本还会处理冲突：当多个来源有同名技能时，优先级是 agent-scripts > manager > codex-local，被跳过的重复项会打印出来。它还会清理失效的链接，保证镜像状态与源目录一致。这个设计的关键是 idempotent，重复运行不会产生副作用，只输出变化。

AGENTS.MD 的指针式共享，而不是复制

除了技能，agent-scripts 还管理全局的代理指令。`AGENTS.MD` 是共享的硬规则文件，`sync-skills` 会把它链接到三个位置：`~/.codex/AGENTS.md`、`~/.claude/CLAUDE.md` 和 `~/.claude/AGENTS.md`。下游仓库不应该复制这些规则，而是用一个指针文件，内容只有一行：`READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing).`。这样做的优点是规则更新时只需要改一处，所有仓库自动跟随。但这也意味着下游仓库必须能访问那个绝对路径，如果路径变了，所有指针都会失效。README 明确说「skip if missing」，这是一个务实的降级策略，但也说明这个方案假设所有仓库都在同一台机器的同一路径下。

验证脚本与本地钩子：把质量检查放进 git

`scripts/validate-skills` 检查每个 `skills/*/SKILL.md` 的 YAML front matter，要求必须有 `name` 和 `description` 字段。README 建议用 `git config core.hooksPath hooks` 把它作为本地钩子运行。这意味着每次提交前，技能文件都会被验证，格式错误会直接阻止提交。这个机制很轻量，但依赖开发者主动配置，因为 `core.hooksPath` 是本地配置，不会随仓库自动传播。如果你克隆了这个仓库，但没有设置 hooksPath，验证就不会生效。另外，`scripts/docs-list.ts` 强制 `docs/` 下的文档必须有 `summary` 和 `read_when` 字段，这为文档维护设定了最低标准。

browser-tools.ts：一个依赖少的 Chrome 调试助手

`scripts/browser-tools.ts` 是一个独立的 Chrome DevTools 辅助工具，用 TypeScript 写成，可以用 `bun build` 编译成二进制。它提供 `start --profile`、`nav <url>`、`eval '<js>'`、`screenshot`、`console`、`network`、`search --content` 等命令。这个脚本和技能同步没有直接关系，但它展示了 agent-scripts 的另一个原则：helper 脚本要依赖少、可移植。README 强调「Keep scripts dependency-free and portable; no repo-specific imports or path aliases」。这保证了脚本可以在不同仓库之间复制，而不需要修改。但这也意味着它只能提供最基础的功能，如果你需要复杂的浏览器自动化，这个工具可能不够。

一个明显的局限：依赖绝对路径和 symlink 支持

agent-scripts 的整个同步策略建立在 symlink 之上，这有两个前提。第一，你的文件系统必须支持 symlink，这在 macOS 和 Linux 上没问题，但在 Windows 上可能需要管理员权限，而且 Git 默认配置可能不处理 symlink。第二，所有链接都指向 `~/Projects/agent-scripts/` 这样的绝对路径，如果你移动了仓库位置，所有链接都会失效。脚本会清理失效链接，但不会自动重建到新路径，你需要重新运行 `sync-skills` 并更新路径。此外，这个工具是个人化的，README 里明确写着「Peter's local workspaces」，所以它没有考虑多用户协作的场景。如果你在一个团队里使用，每个成员都需要手动配置相同的路径结构。

替代方案：手动链接、复制工具或专用技能管理器

如果你不想用 agent-scripts，最直接的替代是手动创建 symlink。对于少量技能，这完全可行，但会随着技能数量增长变得繁琐。另一个方案是使用像 `stow` 这样的通用 symlink 管理器，它可以管理点文件和目录链接，但需要你自己定义每个客户端的布局规则，agent-scripts 已经把 Codex 和 Claude 的差异封装好了。还有一种思路是放弃 symlink，直接用复制脚本把技能文件拷贝到 `~/.claude/skills/`，但这会破坏「单一事实来源」的原则，因为复制后源文件和目标文件会分叉。agent-scripts 选择了 symlink，这是它的核心取舍，也是它与通用工具的主要区别。

维护成本与许可证

agent-scripts 的维护成本集中在两个地方。一是技能本身的内容，每次新增或修改技能后需要运行 `validate-skills` 验证，并运行 `sync-skills` 更新镜像。二是脚本本身的演进，比如 Claude Code 的版本更新可能改变扫描规则，README 里就提到了「verified on 2.1.197」，这意味着如果 Claude Code 更新后行为变化，`sync-skills` 的逻辑可能需要调整。项目采用 MIT 许可证，你可以自由使用和修改，但如果你修改了脚本，就需要自己跟进上游的更新。仓库的最近一次提交是 2026 年 7 月，说明作者仍在维护，但你不能假设它会永远保持活跃。

编辑结论

agent-scripts 适合那些已经在多个仓库中维护 AI 代理技能、并且愿意接受 symlink 方案的开发者。它解决的是真实痛点：Codex 扫描嵌套目录，Claude Code 只读一层目录，两者对技能布局的要求完全相反。如果你只用一个 AI 客户端，或者你的技能都集中在单一仓库，这套脚本就是多余的开销。采用前先确认你的操作系统支持 symlink，并且你愿意让 `sync-skills` 管理 `~/.codex/skills` 和 `~/.claude/skills` 下的文件。还要验证 `AGENTS.MD` 的指针式引用在你的下游仓库中不会破坏其他工具链。MIT 许可意味着你可以随意修改，但如果你改了 `sync-skills` 的行为，就必须自己维护与未来上游版本的兼容性。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes