dotagents

以單一 .agents 目錄集中管理多種 AI 開發工具的共用指令、Hooks、 Skills 與代理規則。

dotagents 會掃描既有設定、協助處理來源衝突，再將 .agents 連結至所選工具。 每次變更前都會建立備份，因此可安全地重複執行或復原上一次操作。

npm 套件：@hurst05/dotagents

功能特色

• 以 .agents 作為所有支援工具的單一資料來源。
• 支援全域與專案兩種管理範圍。
• 自動遷移各工具既有的 commands、hooks、skills 與規則檔案。
• 遇到同名內容時，讓使用者選擇要保留的來源。
• 顯示缺少連結、已連結與衝突項目的狀態。
• 覆寫前自動備份，並可從互動式介面復原上一次變更。
• 在平台支援時使用相對符號連結，讓專案目錄搬移後仍可使用。

快速開始

使用 Node.js 18 以上版本執行：

npx @hurst05/dotagents

啟動後依序：

1. 選擇「全域」或「專案」工作區。
2. 選擇要管理的 AI 工具；預設選取 Claude、Codex 與 Gemini。
3. 檢查待變更項目與衝突。
4. 套用變更，或先保留既有衝突項目。

若要管理其他工具，請在第一層選擇 Other，再從展開的清單選取 Factory、 Cursor、OpenCode、GitHub 或 Ampcode。

之後可再次執行相同指令，以檢視狀態、修復連結、調整工具清單，或選擇 Undo last change 復原上一次操作。

管理範圍

| 範圍 | 單一資料來源 | 影響範圍 | | --- | --- | --- | | 全域 | ~/.agents | 使用者家目錄下的所有專案 | | 專案 | <專案>/.agents | 執行指令時所在的專案 |

全域範圍會管理規則檔、commands、hooks 與 skills。專案範圍只管理 commands、hooks 與 skills；專案根目錄中的 AGENTS.md、CLAUDE.md、 GEMINI.md 仍由專案自行維護。

.agents 目錄

dotagents 會依需要建立以下結構：

.agents/
├── AGENTS.md
├── CLAUDE.md        # 選用：覆寫 Claude 的規則
├── GEMINI.md        # 選用：覆寫 Gemini 的規則
├── commands/
├── hooks/
├── skills/
└── backup/

• 若沒有 AGENTS.md，全域套用時會建立一份初始檔案。
• Claude 優先使用 .agents/CLAUDE.md，不存在時改用 .agents/AGENTS.md。
• Gemini 優先使用 .agents/GEMINI.md，不存在時改用 .agents/AGENTS.md。
• 新增或移除覆寫檔後，請重新執行 dotagents 以更新連結。
• 每個 skill 都必須包含 SKILL.md，且 frontmatter 至少要有合法的 name 與 description。

支援工具

全域範圍

• Claude
  • 規則：~/.claude/CLAUDE.md
  • Commands：~/.claude/commands
  • Hooks：~/.claude/hooks
  • Skills：~/.claude/skills
• Factory
  • 規則：~/.factory/AGENTS.md
  • Commands：~/.factory/commands
  • Hooks：~/.factory/hooks
  • Skills：~/.factory/skills
• Codex
  • 規則：~/.codex/AGENTS.md
  • Commands：~/.codex/prompts
  • Skills：~/.codex/skills
• Cursor
  • Commands：~/.cursor/commands
  • Skills：~/.cursor/skills
• OpenCode
  • 規則：~/.config/opencode/AGENTS.md
  • Commands：~/.config/opencode/commands
  • Skills：~/.config/opencode/skills
• Gemini
  • 規則：~/.gemini/GEMINI.md
  • Commands：~/.gemini/commands
  • Skills：~/.gemini/skills
• GitHub Copilot
  • Skills：~/.copilot/skills
• Ampcode
  • 規則：~/.config/amp/AGENTS.md

專案範圍

專案範圍使用相同的工具目錄名稱，但都位於目前專案內。OpenCode 使用 .opencode，GitHub Copilot 的 skills 使用 .github/skills。Ampcode 目前 沒有專案範圍的連結項目。

各內容皆連回 <專案>/.agents：

• commands：Claude、Factory、Codex、Cursor、OpenCode 與 Gemini。
• hooks：Claude 與 Factory。
• skills：Claude、Factory、Codex、Cursor、OpenCode、Gemini 與 GitHub Copilot。

遷移、衝突與備份

首次套用時，dotagents 會先從所選工具掃描既有內容：

• 唯一來源會自動複製到 .agents。
• 多個來源具有同名內容時，介面會要求選擇其中一個來源。
• 既有目標不是正確的符號連結時，可選擇覆寫或保持原狀。

所有實際變更都會先寫入：

.agents/backup/<時間戳記>/

備份目錄內含 manifest.json，用來記錄被移動的既有路徑與新建立的路徑。 互動式介面的 Undo last change 會使用最新一份備份還原，並為該次復原再建立 一份備份。

[!NOTE] Windows 建立檔案符號連結時，可能需要啟用「開發人員模式」或使用具有 足夠權限的終端機。

本機開發

開發環境使用 Bun 1.3 以上版本。

# 安裝相依套件
bun install

# 以原始碼啟動 CLI
bun run dev

# 型別檢查
bun run type-check

# 執行測試
bun test

# 建置 dist/cli.js
bun run build

授權

MIT