# DD Pipeline — Claude Code 自動化開發流程

可攜式 Claude Code 設定庫，透過 `install-dd-pipeline.sh` 安裝到 `~/.claude/` 全域。

## 安裝 / 更新

```bash
./install-dd-pipeline.sh                    # 首次安裝
./install-dd-pipeline.sh --force            # 更新：差異檔覆蓋（內容相同不重寫）；全域 CLAUDE.md 跳過詢問直接覆蓋（先備份）
./install-dd-pipeline.sh --check            # 只檢查環境
./install-dd-pipeline.sh --uninstall --yes  # 免確認解除安裝（自動化；非互動環境的詢問一律採預設值）
```

> 從舊版（全量部署 / 分桶時期）升級、既有專案升級到 8 步迴圈：見 [UPGRADING.md](UPGRADING.md)。

環境檢查（步驟 1 / `--check`）除必要工具外含**可選項 ffmpeg**：tech-diagram-gif 的
GIF 匯出用，缺少時警示並附安裝指令（brew / apt），該 skill 退化交付 SVG。
只偵測提示、不代裝系統套件。

## 部署清單（使用率盤點制）

repo 只保留**有實證使用紀錄**的元件（2026-08-04 盤點留存 9 skills、4 agents、
dd-init、workflow-review；2026-08-10 新增自製 tech-diagram-gif，實證來源為當次
對話的完整管線驗證），全部預設部署；清單定義在 `install-dd-pipeline.sh` 頂部的
`PROMOTED_*` 陣列。

- 歷次盤點刪除（git 歷史可回溯）：deprecated 桶（全歷史 0 次使用的 34 skills /
  17 agents / 6 dd 指令 / 13 NS commands）與 misc 桶（SRE 備援性質但零實際調用的
  11 skills / 5 NS commands）均於 2026-08-04 刪除；取回方式
  `git checkout pre-prune-2026-08-04 -- skills/<名字>` 後加回陣列

## 目錄結構

- `skills/` — 10 個 Skills（每個子目錄含 SKILL.md 定義檔，全數部署；writing-great-skills 為 vendored 自 mattpocock/skills 的 skill 撰寫參考、tech-diagram-gif 的風格規範 vendored 自 fireworks-tech-graph）
- `agents/` — 4 個 Agents（code-simplifier、code-reviewer 官方備份 + senior-devops、security-auditor）
- `commands/` — 1 個 dd-* 指令（dd-init，.md 平面檔） + 1 個命名空間 command 目錄（workflow-review）
- `templates/global/` — 全域 CLAUDE.md 模板（經互動比對部署到 `~/.claude/CLAUDE.md`）
- `scripts/` — 輔助腳本（部署清單由 `install-dd-pipeline.sh` 頂部的 `DD_SCRIPTS` 陣列決定，部署到 `~/.claude/scripts/`；含 check-claude-md.sh pre-commit gate 與本 repo 自用的 `githooks/`，後者不部署）
- `diagrams/` — 兩份 README 嵌的 6 張 GIF（使用流程、8 步迴圈、大工作怎麼跑 × 中英），另有 tech-diagram-gif
  各風格的示範 GIF（2026-09-07 加入）；每張的來源與重出方式見 `diagrams/src/CLAUDE.md`
  （改來源再重出，勿手改 GIF）。
  三層架構圖於 2026-08-31 移除 — 它畫的是目錄清單而非架構，資訊都在
  `DD_PIPELINE_ARCHITECTURE.md` 的文字版裡，還多一份圖要維護
- `install-dd-pipeline.sh` — 安裝腳本（部署到 ~/.claude/；唯一安裝路線，分享亦同）

## 新增 Skill 步驟

1. 在 `skills/<skill-name>/` 建立 `SKILL.md`
2. 在 `install-dd-pipeline.sh` 的 `PROMOTED_SKILLS` 陣列加入名稱，並**同批**同步：兩份 README 的
   Promoted Skills 表格與標題數字、README 安裝步驟裡的「N 個 promoted Skills」、本檔「目錄結構」
   那行的總數。CI 的「數字宣稱一致性」會擋，漏改要等 push 才發現
3. 部署前先乾跑（新增或改寫都要）：派 subagent 照 repo 裡這份 `SKILL.md` 做一遍，逐條引用原文回報哪一句讓它卡住、
   只能用猜的、或兩句互相矛盾。skill 有分支就每條各跑一次（例如有沒有設計文件）；只讀的步驟拿實際在用的專案跑、
   不准寫檔；會寫檔或 commit 的步驟改在 scratchpad 的拋棄式 repo 真的跑，跨 session 的流程再派一個只讀專案文件的
   agent 接手做完，結果用指令核對，不看 agent 自述。2026-09-11 改寫 task-planner：只讀乾跑抓到二十多處；沙盒實跑
   又抓到只讀看不出來的，例如 gate 在目錄同時有 staged 變更與 SKIP 欠帳時只印 staged 的理由，照訊息補會漏
4. 執行 `./install-dd-pipeline.sh --force` 部署
5. 動到 description 或觸發條件時，裝好後測「會不會自己叫」—— 同一個 session 裡推論不算數，要開全新的：
   在拋棄式專案裡跑 `claude -p "<需求>" --output-format stream-json --verbose --max-budget-usd 3 --no-session-persistence
   --permission-mode dontAsk --allowedTools "Skill Read Glob Grep" --disallowedTools "Edit Write NotebookEdit Bash Agent"
   < /dev/null > out.jsonl`，正反各一個（該叫的大需求、不該叫的小改動），解析 jsonl 看有沒有 `Launching skill:`，
   並確認 `permission_denials` 是空的 —— dontAsk 沒加 `--allowedTools Skill` 會把 Skill 擋掉，只證明它「想叫」。
   prompt 存成 `<名字>.prompt.txt` 放在 jsonl 旁邊，不然事後核對不了「不含關鍵字」這種說法；每次約 US$0.4–1.6。
   這種 session 沒有寫檔工具也沒有 AskUserQuestion，只測得到「叫不叫、出不出得了草稿」，批准之後的步驟要另外在沙盒實跑。
   2026-09-11 task-planner：三個功能的需求叫起了，一行字的改動沒叫，已有進度表、說「照設計文件繼續做」也沒叫

### Skill hook 路徑規範（強制）

skill 若含 `hooks/hooks.json`，其中 `command` **必須**用可在任意 cwd 解析的路徑：

- ✅ `$HOME/.claude/skills/<skill-name>/hooks/xxx.sh`
- ❌ `./hooks/xxx.sh`（hook 以「當前工作目錄」為基準執行，換到別的專案就找不到腳本）

安裝腳本的 `validate_skill_hooks()` 會在部署前掃描所有 `hooks.json`，發現相對路徑即**中止部署**。
引入第三方 skill（vendor）時尤其注意：上游常用相對路徑，併入前先改寫（完整收編流程見下方「第三方 Skill / Agent 收編檢查清單」）。

## 新增 Agent 步驟

1. 在 `agents/` 建立 `<agent-name>.md`（frontmatter 含 `name`、`description`、`model` —
   自製 agent 用 `inherit`；官方備份（code-reviewer / code-simplifier）維持上游的 `opus`，不要改齊）
2. 在 `install-dd-pipeline.sh` 的 `PROMOTED_AGENTS` 陣列加入名稱，並**同批**同步兩份 README 的
   promoted Agents 數字與本檔「目錄結構」那行的總數（CI 的「數字宣稱一致性」會擋）
3. 執行 `./install-dd-pipeline.sh --force` 部署
4. 若 agent 被某個 wrapper skill 調用，確認該 skill 的 Task `subagent_type` 先試 `<name>:<name>`（plugin 命名空間）再 fallback `<name>`（本地）

## 新增 Command 步驟

- 平面指令：在 `commands/` 建立 `<name>.md`，並更新 `install-dd-pipeline.sh` 頂層的 `DD_COMMANDS` 陣列
- 命名空間指令：在 `commands/<namespace>/` 建立 `.md` 檔案，並更新 `install-dd-pipeline.sh` 頂層的 `NS_COMMANDS` 陣列
- 平面指令的檔名**必須 `dd-` 開頭**：CI 的陣列一致性用 `ls commands/dd-*.md` 掃，非此前綴的檔案掃不到，
  本機安裝正常、push 才紅燈，而訊息只說「陣列與實際目錄不一致」，很難聯想到是檔名前綴

## 新增 Script 步驟

1. 在 `scripts/` 建立 `<name>.sh`（必須通過 `shellcheck -S warning`，且可在 macOS bash 3.2 執行）
2. 加入 `install-dd-pipeline.sh` 頂層的 `DD_SCRIPTS` 陣列 —— 漏加的話 `create_scripts()` 不會部署它，
   使用者機器上 `~/.claude/scripts/` 根本沒這支腳本（gate 就住在這一層）。CI 的
   「陣列與目錄一致性」有第五組 `DD_SCRIPTS ↔ scripts/*.sh` 會擋
3. 加進 `.github/workflows/ci.yml` 的 ShellCheck 檔案清單 —— **那份清單是逐檔寫死的**，沒加等於完全不檢查。
   同批更新 `DD_PIPELINE_ARCHITECTURE.md` CI 防線表裡寫死的「shellcheck（warning 級，N 支腳本）」
4. 執行 `./install-dd-pipeline.sh --force` 部署

> `scripts/githooks/` 是本 repo 自用、不部署，也不在 `scripts/*.sh` 這個 glob 內。
> 撰寫腳本本身的規矩（bash 3.2 相容、變數緊貼全形字要寫 `${var}`、改了 gate 要故意改壞一行驗證）
> 見 `scripts/CLAUDE.md`「此層慣例」，那份是腳本內容的單一維護來源；這一節只管「怎麼讓它被部署與被檢查」。

## 核心工作法：8 步開發迴圈

骨幹是經實際專案實戰驗證的功能段落迴圈
（定義於 `templates/global/CLAUDE.md` §3.9，專案具體版由 `/dd-init` 蓋章）：

```
實作+測試 → commit → code-simplifier → code-review → 再測(curl/playwright) → commit
  → 沉澱本輪所學 → 評分&修正
```

第 7、8 步的細則（範圍怎麼算、發現怎麼分類、何時可跳過）見全域模板 §3.9。
本 repo 是這兩步的 dogfood 來源：2026-08-31 先在這裡實跑 4 次，抓到 2 個真錯誤
（`diagrams/src/CLAUDE.md` 漏寫 `gen_usage.py` 不產 html、第 8 步條文自己用了
在該時機為空的 `git diff --cached`），驗證可行後才推進全域模板與 `/dd-init`。

要跨好幾段的工作由 `task-planner` 拆成段落與小任務：小任務只走步驟 1、2，全部 commit 完，整段才跑 3–8，
進度表連同規則區塊照抄進專案的設計文件。照抄進去的那份不會跟著 skill 更新 ——
改了 `skills/task-planner/SKILL.md` 的規則區塊，已經在用的專案手上仍是舊版。

搭配巢狀 CLAUDE.md 堆疊維護（依賴 `claude-md-management` plugin，安裝腳本管理），
並由 **pre-commit gate 強制**（block 版）：`scripts/check-claude-md.sh` 部署到
`~/.claude/scripts/`，`/dd-init` 掛進專案 `.git/hooks/pre-commit`（專案設有
`core.hooksPath` 時改掛該目錄，見下方「開發本 repo」）— 改碼目錄缺
CLAUDE.md 或未同批更新即擋 commit；檢查點 commit 逃生口 `SKIP_DOC_CHECK=1`。
SKIP 不是豁免：段落起點以來跳過、還沒補 CLAUDE.md 的目錄，之後的正常 commit
（就算沒改程式碼）一樣擋；細節見 `scripts/CLAUDE.md`。

> **舊 DD Pipeline（已刪除）**：`/dd-start → /dd-arch → /dd-approve → /dd-dev → /dd-test`
> 多階段流程於 2026-07-23 依使用率盤點（全歷史 0 次使用）封存、2026-08-04 刪除，
> 檔案與舊版 dd-init 見 git 歷史（如 `git show pre-prune-2026-08-04:commands/dd-dev.md`）。

## 開發本 repo

- clone 後啟用 CLAUDE.md gate（dogfood，本 repo 吃自己的 pre-commit）：
  ```bash
  git config core.hooksPath scripts/githooks
  ```
  （`core.hooksPath` 設定後 `.git/hooks/` 會被 git 忽略；`/dd-init` Phase 3
  會偵測此設定並改掛到 hooksPath 目錄，兩者不衝突）
- gate 規則與逃生口（`SKIP_DOC_CHECK=1`）同各專案：改 `.sh` 等程式碼檔時，
  該目錄的 CLAUDE.md 必須同批更新
- 記段落起點、取範圍都用 repo 這份：`scripts/check-claude-md.sh --start-segment` /
  `--segment-base`（全域模板寫的是 `~/.claude/scripts/` 那份）。本 repo 的 hook 跑 repo 這份，
  其他專案的 hook 跑部署那份；安裝腳本不帶 `--force` 也會覆蓋部署那份，gate 還沒驗證完
  別跑安裝，驗證完 commit 後再重跑，其他專案才會用到新版
- 架構總覽（分層、部署清單、安裝行為保證、CI 防線）見 `DD_PIPELINE_ARCHITECTURE.md`

## 注意事項

- 所有回應和註解使用繁體中文
- Commit message 使用繁體中文
- 此專案是 source of truth，全域 ~/.claude/ 的內容由安裝腳本從此專案部署
- 修改 skills / agents / commands / **scripts** 後務必同步更新 install-dd-pipeline.sh 的部署陣列
  （`PROMOTED_SKILLS`、`PROMOTED_AGENTS`、`DD_COMMANDS`、`NS_COMMANDS`、`DD_SCRIPTS`；五組 CI 都會擋不一致）
- skill / command frontmatter 的 `allowed-tools` 是**該輪的免確認預授權**，不是工具白名單。
  官方文件：「It does not restrict which tools are available: every tool remains callable」，
  要真的拿掉工具得用 `disallowed-tools`，而且預授權在使用者下一則訊息後就失效。
  所以漏列**不會**讓步驟執行不出來，只會多一次權限詢問；只有當該 skill 內文寫著
  「不詢問，直接執行」時才構成矛盾，嚴重度是 minor。2026-09-12 稽核時 4 個 agent 同時誤判過
- README 有英文（`README.md`，GitHub 預設顯示）與繁中（`README.zh-TW.md`）兩份，**內容須同批更新**。
  CI 對兩份都驗數字宣稱與 Promoted Skills 表格，正規式為語言無關（`.github/workflows/ci.yml`）。
  CHANGELOG.md 與 UPGRADING.md 維持純繁中，英文 README 連向它們時須標註 *(Traditional Chinese)*。
  README 變英文不改變本專案的註解語言 — 專案 CLAUDE.md（衝突順序第 3 位）優先於
  全域模板 §1.1 程式碼註解列的「跟隨 README 語言」（第 5 位）；回應語言在 §1.1
  本就固定繁中，與 README 語言無關
- 查 `~/.claude.json`（MCP）與 `~/.claude/settings.json`（plugin 啟用狀態）務必
  真正解析 JSON，**不可用字串 grep** — 前者同時存放所有專案的 scoped 設定，純比對會把
  別的專案的設定誤判為已安裝；後者的 `enabledPlugins` 是 `{key: bool}`，**停用是
  「鍵在、值為 false」**，grep 只看得到鍵在（實測 `ralph-wiggum` 值為 `false` 卻被舊版
  回報「已啟用」）。兩者各有專屬 helper：`mcp_scope()` 與 `plugin_enabled_state()`，
  同為 jq → python3 → 退化標示無法判定
- 檢查類輸出的鐵則：**不確定就說不確定，不可退化成有把握的斷言**。`mcp_scope()`
  區分 `none`（確定沒有）／`unparseable`（檔案損毀，無從判定）／`unknown`（缺 jq
  與 python3，只有字串證據）；jq 與 python3 兩條路徑須逐項等價（型別護欄要對齊），
  否則同一台機器裝不裝 jq 會得到不同結論
- `OFFICIAL_PLUGINS` 新增項目前先確認該 plugin 的 `.claude-plugin/plugin.json`
  **有沒有 `version` 欄位** — 官方 `skill-creator` 就沒有（marketplace 與 cache 兩份都沒有）。
  缺 version 時 `install_plugins()` 改讀 `installed_plugins.json` 裡 Claude Code 自己記的值
  （它填內容雜湊，如 `85cce0381e78`）；**不可自行編版本號**，`installPath` 是用它組出
  cache 路徑，編錯會指向不存在的目錄。兩處讀取都要**型別護欄（只接受 JSON 字串）** —
  少了它 `"version": null` 會讓 jq 印 `null`、python3 印 `None`，後者繞過守衛，
  正是本檔上一條「兩路徑須逐項等價」的典型破口。代價是這類 plugin 必須先手動
  `claude plugin install <name>@claude-plugins-official` 過一次，安裝腳本才登記得起來 —
  README 兩份的「必要條件」段落須註明此限制
- `~/.claude.json` 只涵蓋官方 `user` 與 `local` 兩種 scope；`project` scope
  （專案根目錄 `.mcp.json`）不在其中，任何以此檔為據的檢查都會低報，文件須註明
- 增刪 `REQUIRED_MCP` / `OPTIONAL_MCP` 時要**手動**同步**兩份** README 的 MCP 表格 —
  CI 驗的陣列一致性只涵蓋 skills / agents / commands / scripts（`DD_SCRIPTS ↔ scripts/*.sh`
  於 2026-09-12 補上），數字宣稱只驗 skills / agents / commands；MCP 表格會靜靜過期。
  **CI 不驗、只能手動同步的區塊**（不寫總數 — 沒窮舉過，寫個數字只會變成下一個過期宣稱）：
  兩份 README 的安裝步驟清單、指令一覽、官方 Plugins、第三方 Plugin 推薦、MCP 必要表、
  MCP 可選表、前置需求段落、MCP 退化狀態表、**CLAUDE.md 維護規則那 4 條**、**「為什麼要巢狀」
  底下的 gate 對策段落**、**散文裡的「8 步／8-step」字樣**（四方只數圍欄內的編號項、
  第五方只認箭頭行與安裝腳本輸出，標題與內文的步數字樣五道防線一道都碰不到；要改步數時自己
  `grep -c '8 步' README.zh-TW.md` 與 `grep -c '8-step' README.md` 數一遍，**不要在這裡寫死數量** —
  上一版就在這個括號裡寫了「各 9 處」，跟本條自己的「不寫總數」直接打架）、
  **「核心工作法」的迴圈說明段與 task-planner 段**、**授權段的 vendored 清單**；
  以及 `DD_PIPELINE_ARCHITECTURE.md` 的元件數字、CI 防線表、授權清單、
  **「安裝腳本 N 個編號步驟」**（`print_step "n/N"` 改了要跟著改）與
  **「shellcheck（warning 級，N 支腳本）」**（ci.yml 那份清單是逐檔寫死的）。
  這兩個沒有任何檢查會擋它們過期（數字宣稱那道 CI step 是逐檔寫死 README 與根目錄
  CLAUDE.md 的，不涵蓋架構文件）。**要核對就自己數，不要在這裡抄一份**：
  `grep -oE 'print_step "[0-9]+/[0-9]+"' install-dd-pipeline.sh | sort -u` 與
  `awk '/shellcheck -S warning/,/^$/' .github/workflows/ci.yml`。
  （2026-09-12 初稿真的在這裡寫了「7 個編號步驟、4 支腳本」，跟本條自己的「不寫死數量」
  直接打架，是 simplifier 抓到的 —— 這已經是同一個坑的第二次。）
  **觸發時機**：動到部署陣列、MCP、plugin、CI step、**gate 行為**、**迴圈步數或 §3.9 文案**、
  **收編新的 vendored 元件**時，逐項巡一遍
- **安裝選項**已有 CI 防線：flag 三方對照驗「腳本 case 分支 ↔ `--help` 輸出 ↔
  兩份 README 指令範例」名稱完全一致，新增/刪除 flag 忘了同步文件會被擋。
  只驗 flag **名稱**，各 flag 的**語意描述**仍是手動維護
- 腳本開頭是 `set -e`，所以**回非 0 是正常結果**的指令單獨成行會中止整個安裝，
  而且中止點之後的步驟全部不執行、使用者只看到安裝突然結束。最常見的三個是
  `diff`（內容不同回 1）、`grep`（無匹配回 1）、`cmp`；一律補 `|| true` 或放進管線
  （管線取的是**最後一個**指令的結束狀態 — 但這只在腳本**沒有** `set -o pipefail` 時成立，
  目前 repo 的腳本都沒開；哪天有人補上，管線這條逃生口就失效，屆時只剩 `|| true`）。2026-09-12 踩過：全域 CLAUDE.md 互動選單的
  `s) 顯示完整 diff` 分支裡 `diff` 單獨成行，選 s 就中止，講好的第二次詢問永遠問不到；
  同一函式上面的 `diff "$target" "$source" | head -30` 反而沒事，正是因為在管線裡。
  `bash -n` 與 `shellcheck -S warning` 都驗不出這種錯，要靠隔離重現（帶 `set -e` 跑一次）。
  **最危險的變體是 `n=$(grep -c ...)`**：零命中時 `grep` 回 1，指令替換把這個 1 帶給賦值，
  `set -e` 當場中止，而且**連一個字都不印** — 沒有錯誤訊息、沒有半截輸出，
  看起來就跟「這段檢查跑完了、沒事」一模一樣。所以「先確認抓到東西非空、再計數」
  這個順序有承重，不可為了整理而對調（`ci.yml` §7.2 那兩道護欄即此形狀，註解已標明）
- **迴圈步數**已有 CI 兩道防線。**四方一致**（全域模板 §3.9 ↔ `/dd-init` 蓋章版 ↔
  兩份 README 清單 ↔ `dd-loop-version` 標記）只數**編號清單**；**第五方**（2026-09-04 補）
  管它看不到的兩類使用者可見文案 — ①安裝腳本印出的「N 步開發迴圈」（排除註解行，
  那裡是有日期的歷史敘述）②一行式箭頭摘要（合併續行後，箭頭 ≥3 且同時含 commit
  與 review 才認定；CHANGELOG／UPGRADING 為歷史敘述故排除）。兩次踩雷都是靜默失效
  不報錯：2026-08-31 迴圈 6→7→8 時標記停在 `6step`（舊專案跑 `/dd-init` 會被誤判為
  最新）、README 清單漏補一項；2026-09-04 在第五方範圍內抓到 9 處殘留，其中
  `DD_PIPELINE_ARCHITECTURE.md` 那處是人工逐檔翻完仍漏掉、靠檢查腳本才抓到的
- **動到 `commands/dd-init.md` 的蓋章區塊（三個反引號圍起來、開頭是 `## 開發流程` 的那一整塊）
  就必須同步跳 `dd-loop-rev`** — 兩處，用 `grep -n 'dd-loop-rev' commands/dd-init.md` 找
  （Phase 1 的判定式與蓋章標記；**不要在這裡寫行號**，2026-09-12 才因為同一份檔案加了兩行，
  讓原本寫的 `:51` 指到 code fence 起始行），外加 `UPGRADING.md` 寫死的 rev 值與 CHANGELOG 未發布區塊。
  **界線**：蓋章區塊 = 三個反引號 `markdown` 圍起來的那一整塊；Phase 0–6 的執行指示在區塊外，
  改它們不必跳 rev（用上面那個 grep 的兩個行號夾出範圍就看得出來）。Phase 1 的判定是「rev 等於現行值 → 已是現行版，跳過」，
  不跳號的話已蓋章的專案永遠拿不到這次修正，跑 `/dd-init` 還會被告知「已是最新」。
  CI 只驗 dd-init.md 檔內 rev 前後一致（種類數 == 2），**不驗「內容改了 rev 有沒有跳」**，
  UPGRADING.md 那份 CI 根本不看。2026-09-12 踩過：同一輪前面已有一個 commit 動過蓋章區塊沒跳號，
  靠 code-review 才抓到
- **新增 `.github/workflows/ci.yml` 的檢查 step 必做負面測試**：故意把被檢查的來源改壞一行，
  確認該 step 真的紅燈，再還原確認回綠。`scripts/CLAUDE.md` 只對 gate 訂了這條規矩、
  ci.yml 其他 step 沒有 — 而 2026-09-12 新增的兩道護欄，修的正是「抓 0 筆卻印綠燈」。
  同批補一列進 `DD_PIPELINE_ARCHITECTURE.md` 的 CI 防線表（沒有任何檢查會擋那張表過期）
- **subagent 回報的行號可能整組對不上，要拿它引的原文 grep 定位後才動手**：2026-09-12
  code-simplifier 對一份只有 263 行的 `README.md` 報 `README.md:323`，而它描述的內容
  逐條屬實。行號錯得離譜反而好認，錯個三五行才危險 — 一律以原文比對為準，不信行號
- `OPTIONAL_MCP` 只收 **MCP server**（會註冊進 `~/.claude.json` `mcpServers` 的東西）；
  plugin 形式的工具（如 claude-mem，`npx claude-mem install` 走 hooks + plugin 系統）
  列進去檢查會**永遠回報未安裝**，應改列 README 的「推薦第三方 Plugin」段落
- 可選 MCP 推薦名單比照使用率盤點制：上游 deprecated／改名（如 cipher → byterover-cli，
  2026-08-11 移除）或本機實際使用紀錄已斷即移除；後繼品未經實證使用不自動遞補

## 第三方 Skill / Agent 收編檢查清單（vendor intake）

> 引入任何**非自製來源**（GitHub repo、Claude marketplace、舊版安裝包）的 skill/agent 前，逐項過。**任一項不過 → 先改寫或不收**，不得直接併入部署陣列。

| # | 檢查項 | 怎麼驗 | 不過的處置 |
|---|---|---|---|
| 1 | **授權相容** | LICENSE 存在且相容（MIT/Apache 可；GPL/未標需評估）。frontmatter 若寫 `license: … LICENSE.txt`，該檔**必須同目錄存在** | 補齊 LICENSE 或移除懸空 frontmatter |
| 2 | **hook 路徑絕對化** | grep `hooks/hooks.json`，`command` 路徑須以 `/`、`$HOME/`、`~/` 或 `${CLAUDE_PLUGIN_ROOT}` 開頭（validator 會先剝掉 `bash`/`node` 等直譯器前綴再判斷）；相對路徑（`./`）不合格。詳見上方「Skill hook 路徑規範」 | 併入前改寫（`validate_skill_hooks()` 也會擋） |
| 3 | **事實驗證（不只 CLI）** | 任何靠名稱推論不出來的東西都要實跑證實：`npm install` / CLI args / 套件名（`npm view <pkg>` 或官方 README），以及**路徑算式、編碼規則、目錄命名**（實際跑一次拿真實輸出對照）。2026-09-12 踩過：self-improving-agent 五處 `%2F` 編碼算出的記憶體目錄從來不存在，收編時沒人跑過一次 | 無法證實 → 不收 |
| 4 | **runtime 依賴** | 讀 SKILL.md / scripts，確認是否需 Python / Node / 全域 binary | 需額外 runtime → 違反「不塞二進制」，不收或改純設定 |
| 5 | **跨平台冪等** | 無硬編碼絕對路徑、無單一 OS 假設，重跑安裝結果一致；設定與狀態分離 | 不冪等 → 改寫 |
| 6 | **撞名 / 重疊** | 與既有 skill 比 `description`，功能不重複、命名不衝突（避免污染如下節「殘留清理」所述） | 重疊 → 評估取代或不收 |
| 7 | **納管** | 全過後：加進 `install-dd-pipeline.sh` 的 `PROMOTED_*` 部署陣列 → 跑 `--force` → 納入 source of truth | — |

> **典型踩雷**（實際評估）：某第三方 UI/UX skill 號稱 9 萬星但建立僅半年、forks 為整數 → 採用度存疑；且需 `npm -g` binary + Python runtime → 第 3、4 項直接擋下。

> **只借概念、不抄檔案時**（本表第 2、4、5 項不適用，授權仍要處理）：歸屬範圍**精確到段落／項目**，
> 不可整節掛名。2026-09-07 `tech-diagram-gif` 借鏡 diagram-design（MIT）時，LICENSE.txt 把整節
> 「產出前檢查清單」掛到對方名下 — 實際只有四項 remove-test 是借的，其餘來自本 skill 與
> fireworks-tech-graph，同時構成**過度歸屬**（掛了不是人家的）與**不足歸屬**（漏掉真的借的硬閘門 1）。
> 判準：能逐條指出「哪一段來自誰」才算寫對；寫不出來就是範圍還沒想清楚。commit b28c22c 已修。

## 殘留清理（手動）

`install-dd-pipeline.sh` 只「部署」`BUILTIN_SKILLS`，**不會清掉**外部來源（如 tresor、舊版安裝包）放進 `~/.claude/skills/` 的殘留。已知會污染目錄的型態：

| 類型 | 範例 | 風險 |
|---|---|---|
| 安裝包 zip | `~/.claude/skills/*.zip` | 純垃圾，不會載入但佔空間 |
| 分類子目錄 | `~/.claude/skills/{communication,development,documentation,git,security}/` | 內含同名 skill（如 `code-reviewer`、`security-auditor`），與 DD wrapper 撞名 |

排查指令：

```bash
find ~/.claude/skills -maxdepth 1 -name '*.zip'                    # 查 zip 殘留（zsh 下 glob 無匹配會直接報錯，故用 find）
ls -d ~/.claude/skills/{communication,development,documentation,git,security} 2>/dev/null  # 查分類目錄殘留
```

確認非 DD pipeline 內容後手動 `rm` / `rm -rf` 清掉。