auto-skill-hooks

AI 開發環境設定工具 (ai-dev)

統一的自動化設定與維護 CLI 工具，支援 macOS, Linux 與 Windows。

安裝

完整環境設定指南：如果你是第一次設定 AI 開發環境（包含 Claude Code、MCP Server、Plugin 等），請參閱 AI 開發環境設定指南。

以下僅說明 ai-dev CLI 工具本身的安裝方式。

前置需求

請先安裝 uv (Python 專案管理工具)：

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安裝 CLI 工具

從 GitHub 安裝（推薦）：

# 使用 uv
uv tool install git+https://github.com/ValorVie/custom-skills.git

# 使用 pipx
pipx install git+https://github.com/ValorVie/custom-skills.git

# 私有倉庫需要 token
uv tool install git+https://<GITHUB_TOKEN>@github.com/ValorVie/custom-skills.git

更新 CLI 工具：

uv tool upgrade ai-dev

本地開發安裝：

git clone https://github.com/ValorVie/custom-skills.git
cd custom-skills

# 一般安裝（需要更新 pyproject.toml 的 version 欄位後重新安裝才能套用程式碼變更）
uv tool install . --force

# Editable 安裝（推薦開發使用，程式碼變更立即生效）
uv tool install -e . --force

關於 -e (editable) 模式：

• 一般安裝：把源碼複製到安裝目錄，修改源碼後需要重新安裝才會生效
• Editable 安裝：建立指向專案目錄的連結，修改源碼後立即生效，不需重新安裝

開發期間建議使用 -e 模式，或直接用 uv run ai-dev <command> 從專案目錄執行。

使用方式

安裝後，可在任意目錄使用 ai-dev 指令。

# 顯示版本
ai-dev --version
ai-dev -v

# 顯示說明
ai-dev --help

首次安裝 (Install)

執行以下指令進行全新環境設定：

ai-dev install

這會自動：

1. 檢查 Node.js 與 Git。
2. 檢查 Claude Code CLI 是否已安裝（若無則顯示安裝指引）。
3. 安裝全域 NPM 工具 (openspec, gemini-cli, skills 等)。
4. 檢查 Bun 是否已安裝，若已安裝則自動安裝 Codex CLI。
5. Clone 必要的設定儲存庫到 ~/.config/（Stage 1，包含 ~/.config/custom-skills 本機 repo）。
6. Clone 已設定的自訂 repo（若有）。
7. 同步 auto-skill canonical state 到 ~/.config/ai-dev/skills/auto-skill。
8. 從 ~/.config/custom-skills 分發 Skills 與設定到各個 AI 工具的目錄；auto-skill 會先為各 target 重建 ~/.config/ai-dev/projections/<target>/auto-skill shadow，再將工具目錄投影到該 shadow，優先使用 symlink/junction，失敗才 fallback copy。
9. 顯示已安裝的 Skills 清單與重複名稱警告。
10. 顯示 npx skills 可用指令提示。

注意：Claude Code 需要使用 native 安裝方式，不再透過 NPM 安裝。

ai-dev install 預設 phase 為 tools,repos,state,targets。

可選參數

參數	說明
--only	只執行指定 phase：tools,repos,state,targets
--skip	從預設 phase 中跳過指定 phase
--target	僅分發指定目標：claude, codex, gemini, opencode, antigravity
--dry-run	只顯示執行計畫，不實際寫入

範例：

# 只建立 repo 與 canonical state，不分發到工具目錄
ai-dev install --only repos,state

# 僅分發到 Claude Code
ai-dev install --only state,targets --target claude

每日更新 (Update)

建議每天開始工作前執行，以保持環境最新：

ai-dev update

這會自動：

1. 更新 Claude Code（若已安裝）。
2. 更新全域 NPM 工具。
3. 更新已安裝的第三方 Skills（npx skills update）。
4. 更新 Codex CLI（若 Bun 已安裝）。
5. 拉取所有設定儲存庫的最新變更 (git fetch + git reset)。
6. 更新已設定的自訂 repo。
7. 同步 auto-skill canonical state（不直接變更各工具目錄的 shadow/投影）。

注意：此指令不會自動分發 Skills 到各工具目錄。如需分發，請執行 ai-dev clone。

ai-dev update 預設 phase 為 tools,repos,state。

可選參數

參數	說明
--only	只執行指定 phase：tools,repos,state
--skip	從預設 phase 中跳過指定 phase
--dry-run	只顯示執行計畫，不實際寫入

範例：

# 只更新 repo 與 canonical state，不更新工具
ai-dev update --only repos,state

# 只更新工具
ai-dev update --only tools

# 更新後分發 Skills
ai-dev update && ai-dev clone

分發 Skills (Clone)

將統一管理目錄的 Skills 分發到各 AI 工具目錄：

ai-dev clone

auto-skill 為特殊資源，採三層模型：

1. canonical state：~/.config/ai-dev/skills/auto-skill
2. per-target shadow：~/.config/ai-dev/projections/<target>/auto-skill
3. tool projection：~/.claude/skills/auto-skill、~/.codex/skills/auto-skill 等

ai-dev update 只刷新 canonical state。
ai-dev clone 會依 .clonepolicy.json 重建各 target 的 shadow，然後將工具目錄優先以 symlink（Windows 優先 junction）投影到 shadow；若平台或權限不支援才 fallback 為複製。 canonical state 與 shadow 會保留有效的 .clonepolicy.json；當 upstream auto-skill 缺少 policy 時，canonical refresh 會 fallback 使用 template policy，並以 temp rebuild 方式避免舊 state 反覆產生衝突訊息。

ai-dev clone 預設 phase 為 state,targets。

可選參數

參數	說明
--only	只執行指定 phase：state,targets
--skip	從預設 phase 中跳過指定 phase
--target	僅分發指定目標：claude, codex, gemini, opencode, antigravity
--dry-run	只顯示執行計畫，不實際寫入
--force, -f	強制覆蓋所有衝突檔案（不提示）
--skip-conflicts, -s	跳過有衝突的檔案，僅分發無衝突的檔案
--backup, -b	備份衝突檔案後再覆蓋

範例：

# 只刷新 canonical state，不做分發
ai-dev clone --only state

# 只分發到 Claude 與 Codex
ai-dev clone --target claude,codex

# 強制覆蓋所有檔案
ai-dev clone --force

# 跳過衝突檔案
ai-dev clone --skip-conflicts

# 備份後覆蓋
ai-dev clone --backup

維護 custom-skills 專案 (Maintain)

maintain 子命令專門處理 custom-skills repo 自維護流程，避免和一般使用者的 install / clone / project init 混在一起。

# 整合外部來源回開發目錄
ai-dev maintain clone

# 依 allowlist manifest 同步 project-template
ai-dev maintain template

# 只檢查 project-template 是否需要更新
ai-dev maintain template --check