多 Agent 工具并存维护总结

本文记录如何让 Codex、OpenClaw 项目 Agent、OpenCode、Claude Code 在同一台机器和同一个项目工作区内并存，同时保持最低维护成本。

总原则

全局层只放个人通用默认值；项目层只放项目事实和项目工作流。每类内容尽量只有一个真实来源，其它工具通过薄适配复用它，避免复制正文或用多个软链暴露同一批 skills。

核心规则：

• 一个项目主指令入口：优先使用 AGENTS.md。

• 一个项目 skill 内容来源：优先维护在 .agents/skills/。

• Claude Code 用 CLAUDE.md 做规则桥接；如需项目 skills，保留 .claude/skills/ 作为兼容入口。

• .claude/skills 直接软链到 .agents/skills，不维护第二份正文。

• OpenCode 不额外软链全局 AGENTS.md 或 skills；项目内用目录级软链让 .claude/skills 指向 .agents/skills，避免被当成第二份项目 skills。

• OpenClaw 项目 Agent 如果使用 Codex runtime，则跟随 Codex 的项目入口规则。

全局层

全局层适合放个人偏好、通用 skills、工具默认配置，不适合放某个项目的业务规则。

工具	常见全局位置	建议
Codex	~/.codex/AGENTS.md、~/.codex/skills/、~/.codex/config.toml	保留个人通用规则和通用 skills
OpenClaw	~/.openclaw/	每个项目 Agent 可有独立 agent dir / Codex home；不要把项目规则复制到 OpenClaw 全局配置
OpenCode	~/.config/opencode/	避免用软链把 Codex 或 Claude 的全局入口重复暴露给 OpenCode
Claude Code	~/.claude/CLAUDE.md、~/.claude/skills/	可放 Claude Code 专用全局规则；如果与 Codex skills 共享，要确保 OpenCode 不会从多个路径扫到同名 skill

全局层的最低维护成本做法：

• 通用个人 skills 只保留一个 canonical 目录。

• 不同时把同一目录软链到 ~/.config/opencode/skills 和 ~/.claude/skills，除非确认 OpenCode 不会重复扫描。

• 项目规则不要写进全局文件；否则其它项目会继承不该继承的约束。

项目层

项目层适合放项目专属规则、项目 skills、项目检查命令和项目工作流。

工具	项目指令入口	项目 skills	建议
Codex	AGENTS.md	.agents/skills/ + Codex 可见 roots	以 AGENTS.md 作为主入口
OpenClaw 项目 Agent	通常跟随其 runtime；Codex runtime 读 AGENTS.md	通常跟随其 runtime 可见 roots	确认 workspace 指向项目根目录，避免另起一套项目规则
OpenCode	AGENTS.md，兼容其它入口	.agents/skills/	优先消费 .agents/skills/；保留全局 ~/.claude/skills，不要常规禁用 Claude Code skills
Claude Code	CLAUDE.md	.claude/skills -> ../.agents/skills	CLAUDE.md 桥接 AGENTS.md，skills 通过目录软链复用 .agents/skills/

推荐项目结构：

<project-root>/
  AGENTS.md
  CLAUDE.md
  .agents/
    skills/
      <project-skill>/
        SKILL.md
  .claude/
    skills -> ../.agents/skills

推荐 CLAUDE.md 内容：

@AGENTS.md

这能让 Claude Code 读取项目规则；.claude/skills 目录软链则让 Claude Code 发现项目 skills，但它只是兼容入口，不是新的维护源。

不要把 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 作为常规启动方式。这个开关会同时排除全局 ~/.claude/skills，适合临时排障，不适合希望 OpenCode 继续使用全局 Claude skills 的机器。

不推荐的结构

避免这些做法：

• 在项目里同时手写维护 .agents/skills/<name> 和 .claude/skills/<name> 两份正文。

• 项目需要 Claude Code skills 时却删除 .claude/skills/。

• OpenCode 已经报 duplicate skill name 时，仍保留会暴露同名 skill 的全局软链或项目级复制目录。

• 在项目里新增 .opencode/skills 来复制已有项目 skills。

• 在全局 OpenCode 目录软链 AGENTS.md 或 skills 到 Codex / Claude 的目录。

• 把项目规则复制到 CLAUDE.md、OpenCode 全局规则、OpenClaw 全局配置里。

这些结构短期看起来方便，但会带来两个问题：

• 同一工具从多个路径发现同名 skill，触发 duplicate skill name。

• 多份规则内容开始漂移，导致不同 Agent 在同一项目中行为不一致。

维护规则

• 项目行为规则：只改项目根 AGENTS.md。

• 长篇执行细则：放项目内文档目录，例如 docs/agent/*。

• 稳定、重复的项目工作流：放 .agents/skills/<skill-name>/SKILL.md。

• Claude Code 兼容：CLAUDE.md 桥接规则；.claude/skills 软链到 .agents/skills。

• OpenCode 兼容：优先靠 AGENTS.md 和 .agents/skills/；保留全局 ~/.claude/skills，不要为了解决项目重复而常规设置 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1。

• OpenClaw 项目 Agent：先确认它的 workspace、runtime、agent dir，再判断它会读取哪套项目入口。

一句话版本

全局层放个人默认值；项目层用 AGENTS.md 统一项目规则，用 .agents/skills/ 维护项目 skills，用 .claude/skills -> ../.agents/skills 作为 Claude Code 的本地兼容入口；OpenCode 继续读取全局 ~/.claude/skills，项目重复问题优先通过目录级软链解决；OpenClaw 跟随实际 runtime 的项目入口。