【2026 最新】Cursor Plugin 教學：6 步打包 Rules、Skills、MCP、Hooks

Cursor Plugin 教學最容易卡住的，不是 JSON 少一個逗號，而是把 Rule、Skill、MCP、Hook 與兩種 Plugin 格式混成同一件事：檔案看起來都放進去了，Cursor 卻可能沒載入，甚至在你以為「有安全閘門」時讓失敗的 Hook 直接放行。

這篇專為第一次替自己或團隊打包 Cursor 工作流的讀者寫。你不需要先懂擴充套件開發；我們會從選型、目錄、四個元件一路做到本機 symlink、權限審查、A/B 驗收與 Marketplace 發布，並把每一步的「通過證據」說清楚。

先說結論：Plugin 不是一大包提示詞，而是一份可安裝的工作合約

先記住本文的錨點：Cursor Plugin ＝ Manifest（清單）＋ Rules／Skills（做事方法）＋ MCP（外部工具）＋ Hooks（事件閘門）＋驗收證據。前四項決定 Agent 能怎麼工作，最後一項才證明它真的照你的預期工作。

截至 2026 年 8 月 23 日，官方同時支援兩種格式。根目錄的 plugin.json 是可跨相容客戶端使用的 Agent Plugin，核心範圍是 Skills 與 MCP；要把 Rules、Hooks 與 Cursor 變數一起封裝，則要用 .cursor-plugin/plugin.json 的 Cursor Plugin。兩者不只是 manifest 位置不同，能力範圍也不同。想先理解跨 Agent 標準，可以搭配 Agent Plugins v1 教學。

Cursor Plugin 教學先分流：什麼時候根本不必做 Plugin？

• 只想提醒一條專案慣例：用 Rule。它像貼在工作桌前的作業守則，會進入模型上下文，但不是確定性的安全控制。
• 想重跑一套有起訖的流程：用 Skill。它像 SOP，預設可由 Agent 判斷何時使用，也能用 /skill-name 手動叫用。
• 想讓 Agent 查文件或操作外部系統：用 MCP。它是工具插座；權限取決於 server 真正暴露的工具、憑證與網路，不取決於名字聽起來是否「唯讀」。
• 想在讀檔、改檔或執行命令前後自動把關：用 Hook。它是事件觸發的程序，可以觀察、修改或阻擋行為，也因此可能看到敏感輸入。
• 想讓團隊一次安裝、一起版本化：才用 Cursor Plugin 把上述元件裝成一組。

如果你的問題只是「怎麼寫一個好 Skill」，先讀 SKILL.md 完整教學；如果元件已經很多，則可用 Skill Router 整理觸發邊界。不要為了一條規則先養一整套發布管線。

Cursor Plugin 教學步驟 1：先搭最小、可稽核的目錄

痛點：Plugin 內的預設目錄不是專案設定常見的 .cursor/rules/。解法：先完全採用官方自動探索位置，不急著在 manifest 重複指定路徑。操作：建立下面這棵樹；驗收：每一類能力都只有一個明確入口。

workflow-kit/
├── .cursor-plugin/
│   └── plugin.json
├── rules/
│   └── verify-typescript.mdc
├── skills/
│   └── verify-change/
│       └── SKILL.md
├── hooks/
│   ├── hooks.json
│   └── guard-shell.mjs
├── mcp.json
├── README.md
└── LICENSE

現行 Cursor Plugins Reference 只要求 manifest 具備 name；實際散布時，至少再放可讀名稱、版本、描述、作者與授權。這是 Cursor Plugin manifest，不要把 Agent Plugin 的 $schema 欄位照搬進來；官方目前的 Cursor schema 會拒絕未知欄位。

{
  "name": "workflow-kit",
  "displayName": "Workflow Kit",
  "version": "0.1.0",
  "description": "A small, auditable Cursor workflow for TypeScript changes.",
  "author": { "name": "Your Team" },
  "license": "MIT"
}

這份 manifest 沒寫 rules、skills、hooks 或 mcpServers，Cursor 便按預設目錄探索。若你之後明確指定某一類路徑，該設定會取代那一類的預設探索，不是額外疊加；這是「檔案明明存在卻消失」的常見原因。

步驟 2：用 Rule 定義「遇到什麼檔案，要遵守什麼」

痛點：一大篇常駐規則會擠占上下文，還可能干擾不相關任務。解法：讓 Rule 只對 TypeScript 檔案生效。操作：在 rules/verify-typescript.mdc 放入：

---
description: Require focused verification for TypeScript changes
alwaysApply: false
globs:
  - "**/*.ts"
  - "**/*.tsx"
---

When changing TypeScript:

- Run the narrowest relevant typecheck and tests.
- Inspect the final diff for unrelated edits.
- Report the exact commands run and whether they passed.

驗收：開一個只改 Markdown 的任務與一個改 .ts 的任務，比對 Agent 的已套用規則。Rule 使用 globs；不要把 Skill 的現行 paths 欄位混進來。更重要的是，Rule 是給模型看的指示，不應被當成阻擋危險命令的保證。

步驟 3：用 Skill 封裝一套可重跑的交付前檢查

痛點：每次都在 prompt 重打「看 diff、跑測試、誠實回報」，容易漏步。解法：把有開始、有結束的流程做成 Skill。操作：skills/verify-change/SKILL.md 的 name 要和父資料夾 verify-change 一致：

---
name: verify-change
description: Verify a code change before handoff. Use after implementation or when asked to check a diff.
---

# Verify change

1. Inspect `git diff --check` and `git diff`.
2. Run the narrowest relevant tests first.
3. Run the repository-required final checks.
4. Report failures honestly; do not claim a check ran if it did not.

驗收：先用 /verify-change 手動叫用，確認四步都有證據，再觀察 Agent 是否會在適當時機自行選用。若你只允許手動觸發，可在 frontmatter 加 disable-model-invocation: true。

步驟 4：MCP 先從最小資料邊界開始

痛點：一口氣接 GitHub、雲端硬碟與正式資料庫，很難判斷 Agent 到底讀寫了什麼。解法：第一版只接一個不含真實憑證的文件查詢 MCP。以下 mcp.json 使用 Context7 的遠端端點：

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

本文在 2026 年 8 月 23 日直接查詢該端點的 tools/list，當時只列出 resolve-library-id 與 query-docs，兩者都自述 readOnlyHint: true；其官方 固定 commit 的 server.json 也列出相同遠端 URL。這仍不是隔離證明：查詢文字會送往外部服務，server metadata 也是供應方自述，所以不要放 API key、客戶資料或專有程式碼。團隊若不允許外連，就先移除 mcp.json，其餘三個元件仍可測。

驗收：在 MCP Logs 確認只有預期 server 與兩個工具，送一個不含內部資訊的公開文件查詢，記錄 tool name、arguments 與網路目的地。想了解工具 schema 為何也會影響 Agent，可延伸讀 MCP Tool Search 與 lazy schema loading。

步驟 5：Hook 要同時測正常阻擋與自身故障

痛點：命令型 Hook 在 crash、timeout 或輸出無效 JSON 時，預設是 fail-open，也就是動作繼續。解法：安全關鍵的前置 Hook 明寫 failClosed: true，並把 matcher 縮到要攔的命令。

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [{
      "command": "node ./hooks/guard-shell.mjs",
      "matcher": "rm\\s+-(rf|fr)",
      "timeout": 5,
      "failClosed": true
    }]
  }
}

guard-shell.mjs 從 stdin 讀取官方定義的 JSON，檢查 command，再回傳 permission。這裡的 ./hooks/... 相對路徑沿用 官方 plugin repo 的實例；若把同一設定移到專案級 .cursor/hooks.json，工作目錄與路徑規則不同，不能直接照搬。這段只教你 Hook contract，不是完整刪除政策；它沒有涵蓋所有 shell 變體，也不能取代 sandbox、版本控制與備份。

let raw = "";
process.stdin.setEncoding("utf8");
for await (const chunk of process.stdin) raw += chunk;

const input = JSON.parse(raw);
const command = typeof input.command === "string" ? input.command : "";
const blocked = /(^|\s)rm\s+-(rf|fr)(\s|$)/.test(command);

process.stdout.write(JSON.stringify(blocked ? {
  permission: "deny",
  user_message: "Recursive force deletion is blocked by Workflow Kit.",
  agent_message: "Choose a narrower, recoverable cleanup operation."
} : { permission: "allow" }));

if (blocked) process.exitCode = 2;

驗收：fixture（固定測試輸入）只會餵 JSON，不會執行裡面的命令。先從 plugin 根目錄跑 allow／deny 兩條路徑：

printf '%s' '{"command":"rm -rf ./build","cwd":"/tmp","sandbox":false}' \
  | node hooks/guard-shell.mjs
echo $?  # 預期：2；stdout 含 permission: deny

printf '%s' '{"command":"npm test","cwd":"/tmp","sandbox":false}' \
  | node hooks/guard-shell.mjs
echo $?  # 預期：0；stdout 是 permission: allow

接著在可丟棄的 plugin 副本，把 Hook command 暫時換成會 exit 1 或等待超過 5 秒的 Node 程式，再請 Cursor 執行無害的 echo rm -rf ./build；因為 matcher 仍會命中，但 shell 只會印字，若 failClosed 正常，兩種 Hook 故障都應阻擋並留下 log。官方 Hooks 文件 的 payload schema 顯示，不同事件可能收到 prompt、檔案內容、命令、MCP 輸入或輸出；因此本文建議第三方 logger 不要原封不動保存 payload。

步驟 6：用 symlink 本機安裝，再做跨 workspace 驗收

痛點：schema 通過不等於 Cursor runtime 已載入。解法：把開發目錄 symlink 到官方本機插件位置。操作：把第一個路徑換成你機器上的絕對路徑：

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/workflow-kit \
  ~/.cursor/plugins/local/workflow-kit

接著完整重啟 Cursor，或執行 Developer: Reload Window；symlink 只讓檔案同步，不代表所有元件會 hot reload。依序到 Customize 檢查 Plugin、Rules、Skills、Hooks 與 MCP，並在 Output 查看 Hooks／MCP logs。你會在 官方 template 的固定版 validator 看到 node scripts/validate-template.mjs；這是該範本 repo 自帶的腳本，不能拿來代替 Cursor 實際載入測試。

本文的最小範例已對 2026 年 8 月 23 日取得的 cursor/plugins manifest schema 做本機驗證，並用無害 stdin fixture 跑過 Hook allow／deny；這證明 JSON、路徑約定與示範 script 的 contract，不代表你的 Cursor 版本、企業政策與每個 workspace 都已通過。真正交付前仍要做下面的 runtime A/B。

Cursor Plugin 教學怎麼驗收？做「散裝 vs 打包」A/B Test

不要先宣稱 Plugin 省了多少時間。A 組把同一份 Rule、Skill、MCP、Hook 分別安裝；B 組用 Cursor Plugin 安裝完全相同內容。固定 Cursor 版本、模型、prompt、repo commit、workspace trust（工作區信任規則）、MCP allowlist 與執行順序，從 fresh chat（全新對話）與乾淨 branch 開始。

1. 探索：四種元件在 Customize 都能找到，名稱與來源正確。
2. Rule：對符合與不符合 glob 的 fixture，套用結果符合預期。
3. Skill：/verify-change 可手動叫用，四個步驟都有實際輸出。
4. MCP：只出現核准的 server／tools；測試不含 secret，記錄 arguments 與網路目的地。
5. Hook：deny、allow、crash、timeout 四條路徑全部跑過；安全 fixture 不能只測「正常時會擋」。
6. 移除：停用或移除 B、reload，再確認元件不再出現，也沒有非預期寫檔；憑證是否仍存在要按實際儲存範圍另查。

再開第二個 workspace 重跑一次，才能抓到絕對路徑、工作目錄、project/user scope（作用範圍）與 trust policy 的差異。這套「固定條件、保存證據」的思路，也和 Agent runtime controls、AI Agent Harness 實作的驗收方式相通。

發布與更新：Public Marketplace 和 Team Marketplace 是兩條管線

公開發布時，把單一 plugin 或含 .cursor-plugin/marketplace.json 的 multi-plugin repository 放到 public Git repository，補齊 README、license、相對路徑與本機測試，再到 Cursor Marketplace Publish 提交 repo URL。官方要求公開 Marketplace plugin 開源，並人工審查 security、data handling（資料處理）與 quality。

人工審查不等於安全保證。官方安全頁仍要求安裝者先看原始碼；而且「Marketplace 不配送 binary」也不代表沒有可執行能力，因為 Hook、Skill script 與 stdio MCP 本來就能啟動程序。審查時至少搜尋網路連線、shell command、檔案讀寫、環境變數、token、telemetry 與動態下載依賴。

更新也要分清楚：公開 Marketplace 不會把 source push 自動送到使用者，官方會人工審查每次更新；Team Marketplace 從 GitHub import 後則可開 Auto Refresh，最多每 10 分鐘重新索引一次。version bump 是版本溝通，不是部署按鈕；已安裝端在審核後何時取得新版，官方現行頁面沒有給出足夠明確的一體適用規則，發布者應用自己的 Team／client 流程實測，不預設「一定自動升級」。

最常踩的 6 個坑

1. 混用兩種 manifest：需要 Rules／Hooks 卻做成根目錄 Agent Plugin。
2. 把專案目錄搬進 plugin：使用 .cursor/rules，而不是 plugin 預設的 rules/。
3. 指定路徑後還期待自動探索：明確欄位已取代同類預設目錄。
4. 把 Rule 當安全政策：模型指示可能被忽略；真正的 gate 要靠 Hook、sandbox、權限與外部驗收共同完成。
5. Hook 只測 deny：沒測 crash／timeout，就不知道失敗時是否放行。
6. MCP 用 @latest 或真 token 做 demo：先固定版本或使用可稽核遠端，測試憑證採最低權限，任何 secret 都不進 repo。

FAQ：Cursor Plugin 新手最常問的 8 題

1. 只有一條 Rule，也要做 Plugin 嗎？

不用。先放 project Rule 最容易維護；等到你需要整包安裝、版本與團隊散布，再升級成 Plugin。

2. Cursor Plugin 和 Agent Plugin 是同一個標準嗎？

不是。Agent Plugin 是跨相容客戶端的開放格式，現行核心是 Skills＋MCP；Cursor Plugin 是 Cursor 專屬擴充格式，才涵蓋 Rules、Hooks 等能力。

3. Skill 只能手動執行嗎？

不一定。預設可由 Agent 判斷，也能用 slash command 手動叫用；加上 disable-model-invocation: true 才把它限制成手動。

4. Hook 設定了就一定擋得住危險命令嗎？

不能這樣保證。matcher、script、shell 變體與執行環境都可能漏網；安全型 Hook 還要設 fail-closed，並測正常、故障與繞過案例。

5. 本機 stdio MCP 代表資料不會離開電腦嗎？

不代表。本機程序仍可自行連網；你要審查 command、套件版本、原始碼、憑證 scope 與實際網路流量。

6. Symlink 後會自動 hot reload 嗎？

不要把 symlink 當成全部元件的 hot reload 保證。初次安裝或元件沒有反映時，重啟 Cursor 或執行 Developer: Reload Window；hooks.json 的現行文件另稱通常會被監看並自動 reload，仍要以 Hooks log 驗證。

7. Marketplace 審查過就可以不看程式碼嗎？

不可以。Cursor 明確建議安裝前檢查開源內容；Marketplace 審查是一層治理，不是你的權限審查替代品。

8. Hooks 在本機和 Cloud Agents 都完全一樣嗎？

不一樣。官方可確認的 Cloud Hook 來源是 repo 根目錄 .cursor/hooks.json，以及 Enterprise 的 team／managed hooks；不要假設本機 Plugin 的 hooks/hooks.json 會自動進 Cloud。Cloud 只跑 command hooks，早期唯讀回合也不執行；支援清單另不含 sessionStart、sessionEnd、MCP before／after、Tab hooks 與 workspaceOpen。跨環境部署要另外封裝並驗收。

給新手的 7 個重點

1. 先選最小元件，再決定是否需要完整 Plugin。
2. Rules＋Hooks 的完整封裝使用 .cursor-plugin/plugin.json。
3. 第一版採預設目錄，避免 explicit path 取代自動探索。
4. Rule 是模型指示；Hook、MCP 與 scripts 才是主要權限審查面。
5. 安全 Hook 要 fail-closed，並測 crash／timeout。
6. schema、runtime、跨 workspace、移除後殘留要分層驗收。
7. 公開 Marketplace 與 Team Marketplace 的更新機制不能混用。