| name | cross-agents-symlink-bridge |
| description | 為 git 管控的專案建立跨 AI agent 的 hybrid bridge：repo-local `skills` 用 symlink / Junction 避免重複，`specs` 可選擇 sync 或 symlink，其餘 `.claude`、`.kiro`、`.codex` 內的設定 / 權限檔維持 real-directory + sync workflow。當使用者提到「設定 cross-agents symlinks」「初始化 agents 設定」「skills 不要重複」「保留 Claude/Codex 權限檔」「specs 要可切換 sync 或 symlink」「CLAUDE.md symlink」或要整理 cross-agent `.gitignore` 規則時使用此 skill。 |
Cross-Agents Symlink Bridge
在多 AI agent（OpenCode、Claude Code、Kiro、Codex）並存的專案中，這個 skill 採用 hybrid bridge：
.agents/skills/（workspace agent home）是共享 skill source，讓 .claude/skills、.kiro/skills、.codex/skills 指向同一份內容；repo root 不應出現獨立的 skills/（那是 ~/.config/opencode/、~/.claude/ 這類 global config home 的慣例）.agents/specs/ 同樣是 workspace-level spec source，但 .claude/.kiro/.codex 下的 specs/ 可以選擇 sync 或 symlink- 其餘設定、權限、approval、sandbox 相關檔案保持 real directory / real files，交給既有 sync flow 或各 agent 自己管理，避免再出現 whole-directory symlink 導致的權限問題
關鍵差異：Kiro / Codex vs Claude：
- Kiro：repo-local
skills/ 建議用 symlink / Junction，specs/ 可 sync 或 symlink，其他內容保持 real dir
- Codex：與 Kiro 相同；重點是不要再讓整個
.codex/ 指向 .agents/，避免權限 / runtime state 被整包接管
- Claude Code：除了
skills/ / specs/ hybrid bridge，仍需要遞迴建立 CLAUDE.md → AGENTS.md symlink，因為 Claude 只直接讀 CLAUDE.md
核心設計原則
- 只有
skills/ 預設一定是 link surface — 目標是消除 repo-local skill duplication，而不是讓整個 agent root 變成 symlink。canonical source 是 .agents/skills（與 .agents/specs 對稱），不是 repo root 的 skills/
.claude/、.kiro/、.codex/ 本身保持 real directories — 這樣權限檔、approval state、sandbox config、MCP config 才不會被 whole-directory symlink 綁架specs/ 是 mode-based surface — 使用者可明確選擇 sync（預設）、symlink 或 skip- 其他 config / permission surfaces 不由這個 skill 轉成 symlink — 它們應沿用既有 sync workflow 或各 agent 自身管理方式
.gitignore 只忽略成功建立的 generated symlink paths — 不忽略整個 agent root- CLAUDE.md 遞迴處理 — 專案內任何目錄有
AGENTS.md 就自動建立 CLAUDE.md → AGENTS.md symlink
- 雙平台腳本 — 所有操作皆有
.sh（Linux/macOS）和 .ps1（Windows）版本
操作決策樹（優先閱讀）
| 使用者措辭關鍵字 | 對應 Phase | 執行指令 |
|---|
| 「初始化」「setup」「first time」「設定 symlink bridge」 | Phase 1 | bash scripts/init.sh |
| 「specs 也要 symlink」「specs 改回 sync」「specs 可切換」 | Phase 1 | bash scripts/init.sh --specs-mode symlink / --specs-mode sync |
| 「sync」「更新 CLAUDE.md」「新增了 AGENTS.md」 | Phase 2 | bash scripts/sync-claude-md.sh |
| 「裝 hook」「pre-commit」「自動同步」 | Phase 3 | bash scripts/install-hook.sh |
若使用者只說「處理 cross-agents」而無明確指定，預設從 Phase 1 開始，並使用 --specs-mode sync。
工作流程
Phase 1：初次初始化
當使用者想在專案中初次設定 cross-agents hybrid bridge：
- 確認當前工作目錄是專案根目錄
- 執行 init 腳本：
- Linux/macOS：
bash scripts/init.sh
- Windows：
powershell -ExecutionPolicy Bypass -File scripts/init.ps1
- init 腳本會：
- 將
.claude/、.kiro/、.codex/ 正規化為 real directories
- 建立
.claude/skills、.kiro/skills、.codex/skills → .agents/skills/ 的 symlink / Junction（若 .agents/skills/ 不存在會自動建立）
- 依
--specs-mode 處理 .claude/.kiro/.codex/specs
sync（預設）：從 .agents/specs/ 同步到各 agent rootsymlink：讓各 agent 的 specs/ 指向 .agents/specs/skip：完全不碰 specs/
- 不處理其他設定 / 權限檔的 symlink 化
- 遞迴同步
CLAUDE.md → AGENTS.md
- 更新
.gitignore 的 managed symlink sections
Phase 2：CLAUDE.md 同步（手動觸發）
當使用者在現有專案中新增了 AGENTS.md，或想重新掃描：
- Linux/macOS：
bash scripts/sync-claude-md.sh
- Windows：
powershell -ExecutionPolicy Bypass -File scripts/sync-claude-md.ps1
sync 腳本支援兩種模式：
| 模式 | 觸發方式 | 行為 |
|---|
| Full scan | 直接執行，無參數 | 掃描整個 repo 所有目錄 |
| Git diff mode | --staged 參數 | 只處理 git diff --cached 中的 AGENTS.md；若本次 commit 沒有 staged AGENTS.md，仍會從目前 repo 內有效的 CLAUDE.md -> AGENTS.md symlink 狀態重建 managed .gitignore section，避免把既有 entries 洗掉 |
Full scan 會排除 .git/、node_modules/、vendor/，以及 generated .claude/、.kiro/、.codex/ 子樹，避免在 agent mirror / bridge 目錄或第三方 vendored code 內重複生成 CLAUDE.md。
Phase 3：安裝 pre-commit hook（可選）
讓 git commit 時自動確保 CLAUDE.md symlink 與 AGENTS.md 保持同步：
- Linux/macOS：
bash scripts/install-hook.sh
- Windows：
powershell -ExecutionPolicy Bypass -File scripts/install-hook.ps1
重要規則
衝突處理
| 情境 | 行為 |
|---|
.claude/、.kiro/、.codex/ 是 whole-directory symlink | 備份 symlink，自動改回 real directory，再只建立 skills/ 子路徑 symlink |
.claude/skills、.kiro/skills、.codex/skills 已是正確 symlink | 跳過，輸出 ✅ |
.claude/skills、.kiro/skills、.codex/skills 是實體目錄 | 先 backup，再建立指向 .agents/skills/ 的 symlink / Junction |
.claude/specs、.kiro/specs、.codex/specs 使用 sync mode | 保持 real directory，從 .agents/specs/ rsync / robocopy mirror |
.claude/specs、.kiro/specs、.codex/specs 使用 symlink mode | 若已有實體目錄，先 merge 回 .agents/specs/，再建立 symlink / Junction |
CLAUDE.md 已是正確 symlink | 跳過 |
CLAUDE.md 是實體檔案（有內容） | 警告並跳過，不覆蓋 |
CLAUDE.md 不存在 | 建立 symlink，並將路徑加入 .gitignore |
.gitignore 規則
- 只在 generated symlink 建立成功後才將對應路徑加入
.gitignore
skills bridge 層級：.claude/skills、.kiro/skills、.codex/skillsspecs 只有在 symlink mode 時才加入 ignore：.claude/specs、.kiro/specs、.codex/specsCLAUDE.md 層級：每個成功建立的 CLAUDE.md symlink 的相對路徑（如 docs/CLAUDE.md）- 若
.gitignore 不存在則自動建立
- 使用 獨立 managed sections 管理 bridge paths 與
CLAUDE.md paths，避免 stale entries 殘留
- managed entries 以 repo-root anchored 形式寫入（例如
/CLAUDE.md），避免 root 檔名規則誤傷 vendored CLAUDE.md
sync-claude-md --staged 若本次沒有 staged AGENTS.md，不可把 CLAUDE.md managed section 重寫為空；應從目前有效 symlink 狀態重建該 section- 若
.claude/skills、.kiro/skills、.codex/skills 曾被 git 追蹤，加入 .gitignore 不會自動 untrack；agent 應提醒使用者檢查 git status
腳本說明
| 腳本 | 平台 | 用途 |
|---|
scripts/init.sh | Linux/macOS | Hybrid 初始化（real agent roots + skills/ symlink + specs sync/symlink + CLAUDE.md 同步 + .gitignore） |
scripts/init.ps1 | Windows | 同上，使用 Junction / Robocopy |
scripts/sync-claude-md.sh | Linux/macOS | 遞迴同步 CLAUDE.md symlink，並重寫 dedicated .gitignore section |
scripts/sync-claude-md.ps1 | Windows | 同上 |
scripts/test-gitignore-idempotency.sh | Linux/macOS | 驗證 managed .gitignore sections idempotent、root anchored，且 vendor/ 不被掃描/忽略 |
scripts/install-hook.sh | Linux/macOS | 安裝 git pre-commit hook |
scripts/install-hook.ps1 | Windows | 同上 |
執行慣例
- 一律從專案根目錄執行
- agent 執行腳本後應讀取輸出，根據輸出中的 ✅/🔗/🔄/📦/⚠️/❌ 符號向使用者報告結果
- 若 init 或 sync 腳本回報任何 ❌，應向使用者說明問題並建議處理方式
常見問題處理
| 輸出符號 | 情境 | Agent 應對 |
|---|
📦 Backed up .claude | 舊版 whole-directory symlink 或不相容實體路徑 | 告知使用者 root 已改回 real dir，避免權限狀態再被整包 symlink |
🔗 Created: .claude/skills -> .agents/skills | repo-local skills bridge 建立成功 | 告知使用者 skills 不再重複複製 |
🔄 Synced: .claude/specs <= .agents/specs | specs 使用 sync mode | 告知使用者目前仍採 real-directory sync，而非 symlink |
🔗 Created: .claude/specs -> .agents/specs | specs 使用 symlink mode | 告知使用者這是明確 opt-in 行為 |
⚠️ CLAUDE.md is a real file | 子目錄已有手寫的 CLAUDE.md | 告知使用者檢查內容是否需要保留，必要時合併到 AGENTS.md |
❌ Not a git repository | --staged 模式下專案不是 git repo | 改用 full scan 模式（不加 --staged） |
與現有專案整合
- 優先檢查
skills/ 子路徑狀態（ls -la .claude/skills .kiro/skills .codex/skills）而不是 whole root
- 若 repo-local
skills/ bridge 已正確存在，無需重新執行 init
- 若 repo 曾追蹤
.claude/skills、.kiro/skills、.codex/skills，提醒使用者檢查 git status 並自行決定是否需要 untrack 既有路徑
- 若使用者只新增了
AGENTS.md，只需執行 sync-claude-md
- 若使用者只想切換
specs 策略，可重跑 init.sh --specs-mode sync|symlink|skip
- 若 repo 先前真的依賴 whole-directory
.claude/.kiro/.codex -> .agents 取得某些 local config，這些檔案在 backup 後不會自動拷回新 root；切換完成後應重新執行既有 sync flow 或人工核對需要保留的設定。
