昨天把產線抽成了 CLI，人跟 CI 都能用了。接下來兩天處理最後一種使用者：AI agent。

今天先談要打包的是什麼、有哪幾種包法，以及最後選擇的 Claude Code plugin 長什麼樣子；明天再實際把它做出來，並說明怎麼上架、怎麼私下分享給別人。

CLI 已經能用，問題是能不能用好

CLI 裝好之後，agent 其實已經「能」用它了。Claude Code 有 Bash tool，npx auto-manual-gen probe 誰都打得出來。

但「能用」不等於「用好」。為了讓 agent 產出的手冊品質穩定，這條產線在很多地方額外提供了上下文：說明工作流程與指令用法的 prompt、畫面與元件的說明文件、寫作規則，還有已經審過的章節當作範例。少了這些，agent 只能看一眼畫面、憑印象寫 selector。

在範例專案裡，這些上下文散在 agent/ 資料夾和每次手動下的 prompt 裡，換到別人的專案就都不存在了。所以它們也應該跟 CLI 一起打包，讓新的使用者 (或 agent) 裝好就能用，不用自己另外準備。

把 prompt 包成 skill

現在常見的做法，是把這類 prompt 包裝成 skill，跟著工具一起發給使用者，使用者不用自己維護。一個 skill 就是一個資料夾，裡面有一份 SKILL.md：

---
name: manifest-authoring
description: 撰寫或修改 auto-manual-gen 的 manifest（manifest/*.yaml）時使用。說明可用的動詞、schema 與驗證迴圈。
---

（內文：工作迴圈、動詞表、各種錯誤碼該怎麼處理……）

平常只有 description 會放進 context，agent 判斷「現在用得到」，才會把內文載入。所以可以準備很多份 skill，不用擔心全部塞爆 context。

skill 有兩種用法：

• 知識型：由模型自己判斷什麼時候載入，例如上面的 manifest-authoring。
• 進入點型：由人用斜線指令觸發，例如 /add-chapter。Day 17 每次手動貼給 agent 的那段「新增一章、跑通就停下來給人 review」，就可以直接變成它的內文。

SKILL.md 已經是跨工具的格式了 (Agent Skills 開放標準)，Codex、GitHub Copilot、Cursor、Gemini CLI 等工具都讀得懂。

哪些能打包，哪些不能

不過，前面提到的上下文，其實可以分成兩種：

1. 跟工具有關的知識

   不管用在哪個產品都一樣。例如 manifest 有哪些動詞、工作迴圈、看到哪個錯誤碼該怎麼處理，還有正文的基本骨架與寫作規則。

2. 跟產品有關的知識

   每個產品都不一樣。例如畫面上有哪些 testid (TESTID.md)、要點哪裡才到得了某個畫面 (UI-MAP.md)、「toast 3 秒後會自動消失」這類行為 (QUIRKS.md)，以及已經審過、拿來當範例的章節。

第一種可以直接寫成 skill，跟著工具一起發；第二種沒辦法事先寫好發給別人，只能留在使用者自己的 repo 裡。所以還需要一個 skill，專門教 agent 在使用者的專案裡把這幾份文件建起來：用 probe 探勘畫面、整理成草稿，交給人審。

寫作規則比較特別：工具帶一份預設版本，使用者的專案裡有自己的 agent/STYLE.md，就以專案的為準。

三種包法

skill 寫好之後，接下來就是要思考：要怎麼交給別人？大致有三種做法。

在比較之前先說清楚：CLI 加上 skill，整條流程就能完整運作。除此之外，這條產線還用到兩種讓 agent 用得更穩的元件，有的話加分、沒有也能跑：

• subagent：把探勘、寫正文這類工作交給另一個 agent，例如 probe 的輸出很長，交給 subagent 探勘，只把結論帶回來，主線的 context 就不會被塞滿。
• hook：在特定事件自動執行指令，例如改了 manifest 就自動跑 validate。add-chapter 這類流程本身就會驗證，hook 補的是流程以外的修改：使用者隨口叫 agent 改一下某章的截圖範圍，沒有觸發任何 skill，hook 也保證一定會驗。

三種包法的差別之一，就是能不能把這兩種元件一起帶上。

1. 單純的 skills 資料夾

最簡單的做法，是直接把 skill 放進產品 repo 的 .claude/skills/，跟程式碼一起 commit：

my-electron-app/
└── .claude/
    ├── skills/          manifest-authoring/  doc-writing/  add-chapter/ ...
    ├── agents/          explorer.md               # subagent 另外放
    └── settings.json    # hook 另外寫在這裡

同事 clone 下來就有，不需要安裝任何東西。只給自己用的話，也可以放在 ~/.claude/skills/。

缺點是每個 repo 一份，有兩個產品在用，就要複製兩份。

所以，如果產品不多，其實這應該是最方便快速的。

2. 跟著 npm 套件一起發

第二種做法，是把 skills 放進 auto-manual-gen 這個 npm 套件裡，再提供一個指令把它們複製到專案的 .claude/skills/。Playwright 的 playwright-cli install --skills 就是這個模式。

分享方式就跟 CLI 一樣：昨天的 .tgz 或公司內部的 registry。

它最大的好處是 skill 的版本跟 CLI 鎖在一起：裝的是哪一版 CLI，拿到的就是對應那一版的 skill，不會出現 skill 教的指令、CLI 還不支援的狀況。缺點是升級 CLI 之後要記得重跑一次安裝指令。

另外，這類指令通常只負責複製 skill：subagent 是 .claude/agents/ 底下的檔案、hook 是寫在 .claude/settings.json 裡的設定，想要的話得由使用者自己複製、自己改設定。要讓安裝指令連這些都處理，就得去合併使用者既有的設定檔、處理升級與移除，等於自己重做一套套件管理，所以多半就只發 skill。

3. 做成 Claude Code plugin

第三種做法，是把 skills、subagent、hook 全部包成一個 Claude Code plugin，透過 marketplace 安裝：

/plugin marketplace add CK642509/auto-manual-gen
/plugin install manual@auto-manual-gen

plugin 是一個打包與發布的外殼，skill 只是裝在裡面的其中一種元件。它多了幾件 skills 資料夾做不到的事：

• 一次裝好全部的元件：skill、subagent、hook，以及會被加進 PATH 的執行檔。
• 一個來源：所有產品都從同一個 marketplace 安裝，有版號，用 claude plugin update 更新。
• 有 namespace：所有元件都掛在 plugin 的名字底下 (/manual:add-chapter)，不會跟使用者自己的 skill 撞名。

缺點是只有 Claude Code 認得這個外殼，而且格式還在快速變動。

怎麼選

如果只有一兩個產品要用，前兩種做法其實就夠了。CLI 加上 skill 已經能完整運作，真的想要 subagent 和 hook，在第一種做法裡把它們一起 commit 進 .claude/ 也行，還少了 marketplace、版號這些概念。

plugin 的價值在三件事：

1. 多個產品共用：一個來源、有版號、有更新管道，比每個 repo 各複製一份好維護。
2. hook 一起帶上：skill 的 frontmatter 其實也能寫 hooks，但它要等 skill 被觸發之後才會註冊，模型沒載入那個 skill，hook 就不存在。plugin 的 hook 則是只要 plugin 啟用就一直都在，不用使用者自己去改 settings.json。
3. namespace：不會跟使用者自己的 skill 撞名。

這個系列選了 plugin，一方面是想示範完整的打包方式，另一方面是 hook 對「agent 隨手改檔」這種情況確實有用。就算沒有它，錯誤最晚也會在 CI 被擋下，只是發現得比較晚。

為什麼不包成 MCP

另一個常見的做法是包成 MCP server，不過評估之後覺得目前沒有必要。CLI 本來就必須存在，人跟 CI 都要用，agent 透過 Bash 也能直接呼叫；再包一層 MCP，只是多一個要同步的介面，而且解決不了這篇開頭的問題：agent 缺的是怎麼用好的知識。Playwright 也是同樣的思路，除了 MCP 之外另外推出 playwright-cli，用 skill 教 agent 怎麼用，還更省 token。

plugin 的格式

⚠️ 這篇文章是 2026 年 10 月寫的，對照的是 Claude Code v2.1.286 的 plugin 格式。plugin 的格式變化很快 (今年 1 月的 v2.1.3，commands/ 才剛被併進 skills)。如果你讀到這篇的時候格式又變了，細節請以官方文件為準，並用 claude plugin validate 檢查。前面三種包法的取捨比較不容易過期。

一個 plugin 就是一個資料夾，各個元件依照慣例放在固定的位置：

plugin/
├── .claude-plugin/
│   └── plugin.json   # 這個 plugin 的名稱、版本、說明
├── skills/           # skill，一個資料夾一份 SKILL.md
├── agents/           # subagent，一個檔案一個
├── hooks/
│   └── hooks.json    # 在特定時機自動執行的指令
└── bin/              # 執行檔，plugin 啟用期間會被加進 PATH

• plugin.json：最重要的是 name，所有元件都會掛在這個名字底下。plugin 叫 manual 的話，skills/add-chapter/ 就會變成 /manual:add-chapter。
• skills/：格式跟前面介紹的 SKILL.md 完全一樣，frontmatter 決定它是知識型還是進入點型。早期的 plugin 教學會把斜線指令放在 commands/，現在官方文件已經把它標為舊格式，一律寫成 skill 就好。
• agents/：subagent 有自己的 context，可以指定它能用哪些工具、預先載入哪些 skill。適合處理會產生大量中間資料的工作，例如探勘畫面。
• hooks/：在特定時機自動執行的指令，例如「每次寫入檔案之後跑一次 validate」，失敗時可以把錯誤交回給 agent。只要 plugin 是啟用狀態，hook 就一直有效。
• bin/：裡面的執行檔會被加進 Bash tool 的 PATH，agent 可以直接用名字呼叫。

小結

今天整理了要打包什麼，以及怎麼包：

• CLI 讓 agent「能用」，skill 讓 agent「用好」。
• 工具的知識包成 skill 跟著發；產品的知識留在使用者的 repo，由 skill 教 agent 建起來。
• 包法由簡單到完整：skills 資料夾、npm 套件、plugin。一兩個產品用資料夾就夠，多個產品共用才需要 plugin。

明天就把這條產線的 plugin 實際做出來，並說明怎麼上架與私下分享。