cowork-plugin-customizer

Anthropic ｜ 設定與維護 ｜ 原文 ｜ Apache-2.0

依組織的工具和流程客製化 plugin，替換佔位符並連接 MCP

---
name: cowork-plugin-customizer
description: >
  針對特定組織的工具和工作流程，客製化 Claude Code plugin。
  Use when: customize plugin, set up plugin, configure plugin, tailor plugin, adjust plugin settings,
  customize plugin connectors, customize plugin skill, tweak plugin, modify plugin configuration.
compatibility: Requires Cowork desktop app environment with access to mounted plugin directories (mnt/.local-plugins, mnt/.plugins).
---

# Cowork Plugin 客製化

針對特定組織客製化 plugin：可以是第一次把通用的 plugin 範本設定好，也可以是微調、改進已經設定過的 plugin。

> **找到 plugin**：要找 plugin 的原始檔，執行 `find mnt/.local-plugins mnt/.plugins -type d -name "*<plugin-name>*"` 找出 plugin 目錄，然後先讀它的檔案、搞懂結構，再動手修改。如果找不到 plugin 目錄，使用者很可能是在遠端容器裡進行這段對話。這時要中止，並告訴他們：「Customizing plugins is currently only available in the desktop app's Cowork mode.」

## 判斷客製化模式

找到 plugin 之後，檢查有沒有 `~~` 開頭的佔位符：`grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'`

> **預設規則**：如果有 `~~` 佔位符，除非使用者明確要求客製化 plugin 的某個特定部分，否則預設走**通用 plugin 設定**。

**1. 通用 plugin 設定**：plugin 裡有 `~~` 開頭的佔位符。這些是範本中需要換成真實值的客製化點（例如 `~~Jira` → `Asana`、`~~your-team-channel` → `#engineering`）。

**2. 限定範圍的客製化**：沒有 `~~` 佔位符，而且使用者要求客製化 plugin 的某個特定部分（例如「customize the connectors」「update the standup skill」「change the ticket tool」）。讀 plugin 的檔案找出相關的段落，只專注在那些地方。不要掃描整個 plugin，也不要拿不相關的客製化項目來問。

> **舊式 `commands/` 目錄**：有些 plugin 會附 `commands/` 目錄。Cowork UI 現在把這些和 skill 一起呈現成單一的「Skills」概念，所以客製化時，`commands/*.md` 檔案要和 `skills/*/SKILL.md` 檔案用同樣的方式處理。

**3. 一般客製化**：沒有 `~~` 佔位符，而且使用者想大範圍修改 plugin。讀 plugin 的檔案了解目前的設定，再問使用者想改什麼。

> **重要**：絕對不要改被客製化的 plugin 或 skill 的名稱。不要重新命名目錄、檔案，或 plugin／skill 的 name 欄位。

> **非技術性的輸出**：所有面向使用者的輸出（待辦清單項目、問題、摘要）都必須用平實、非技術性的語言寫。絕對不要向使用者提到 `~~` 前綴、佔位符或客製化點。一切都用 plugin 的功能和組織的工具來描述。

## 客製化工作流程

### 階段 0：收集使用者意圖（僅限限定範圍和一般客製化）

對於**限定範圍的客製化**和**一般客製化**（不含通用 plugin 設定），檢查使用者在提出要求的同時，有沒有附上自由格式的背景說明（例如「customize the standup skill — we do async standups in #eng-updates every morning」）。

- **如果使用者有提供背景**：記下來，用它預先填好階段 3 的答案，使用者已經回答過的問題就跳過不問。
- **如果使用者沒有提供背景**：繼續之前，先用 AskUserQuestion 問一個開放式問題。問題要依使用者要求客製化的內容調整，例如「What changes do you have in mind for the brief skill?」或「What would you like to change about how this plugin works?」保持簡短，並針對他們的要求。

  使用他們的回答（如果有的話）作為後續階段的額外背景。

### 階段 1：從知識類 MCP 收集背景

用公司內部的知識類 MCP 蒐集和客製化範圍相關的資訊。各類別的詳細查詢模式請見 `references/search-strategies.md`。

**要收集什麼**（範圍限縮到相關的部分）：

- 組織使用的工具名稱和服務
- 組織的流程和工作流程
- 團隊慣例（命名、狀態、估點尺度）
- 設定值（workspace ID、專案名稱、團隊識別碼）

**要搜尋的來源：**

1. **聊天／Slack MCP**：工具的提及、整合、工作流程討論
2. **文件 MCP**：新人訓練文件、工具指南、設定說明
3. **Email MCP**：授權通知、管理員郵件、設定邀請

把所有發現記下來，供階段 3 使用。

### 階段 2：建立待辦清單

建立一份要做的修改的待辦清單，範圍要適當：

- **限定範圍的客製化**：只列和使用者問到的那個特定段落相關的項目。
- **通用 plugin 設定**：執行 `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'` 找出所有佔位符客製化點。依主題分組。
- **一般客製化**：讀 plugin 的檔案，了解目前的設定，並根據使用者的要求，找出需要改什麼。

用對使用者友善、聚焦在 plugin 用途的描述：

- **好**：「Learn how standup prep works at Company」
- **不好**：「Replace placeholders in skills/standup-prep/SKILL.md」

### 階段 3：完成待辦項目

用階段 0 和階段 1 的背景逐項處理。

**如果使用者的自由格式輸入（階段 0）或知識類 MCP（階段 1）已經給出明確的答案**：直接套用，不用確認。

**否則**：使用 AskUserQuestion。不要假設「業界標準」的預設值是對的，如果使用者的輸入和知識類 MCP 都沒有給出具體答案，就問。注意：AskUserQuestion 一定會附一個 Skip 按鈕和一個讓人填自訂答案的文字輸入框，所以不要把 `None` 或 `Other` 放進選項。

**修改的類型：**

1. **佔位符替換**（通用設定）：`~~Jira` → `Asana`、`~~your-org-channel` → `#engineering`
2. **內容更新**：修改指示、skill、工作流程或參考資料，讓它們符合組織
3. **URL 格式更新**：`tickets.example.com/your-team/123` → `app.asana.com/0/PROJECT_ID/TASK_ID`
4. **設定值**：workspace ID、專案名稱、團隊識別碼

如果使用者不知道或跳過，就保持原值不變（通用設定的話，就保留 `~~` 開頭的佔位符）。

### 階段 4：搜尋有用的 MCP

客製化項目都處理完之後，為已經找出或更動的工具連接 MCP。完整流程、類別對關鍵字的對照表和設定檔格式，請見 `references/mcp-servers.md`。

針對客製化過程中找出的每個工具：

1. 搜尋 registry：用 `references/mcp-servers.md` 裡的類別關鍵字執行 `search_mcp_registry(keywords=[...])`，如果已經知道具體的工具名稱，就直接搜它
2. 如果尚未連接：執行 `suggest_connectors(directoryUuids=["chosen-uuid"])`，由使用者完成驗證
3. 更新 plugin 的 MCP 設定檔（先檢查 `plugin.json` 有沒有自訂位置，否則用根目錄的 `.mcp.json`）

把所有 MCP 的結果收集起來，一起放在摘要輸出裡呈現（見下方），不要在這個階段一個一個地呈現 MCP。

## 打包 Plugin

所有客製化都套用完之後，把 plugin 打包成 `.plugin` 檔交給使用者：

1. **把 plugin 目錄壓成 zip**（排除 `setup/`，因為它已經用不到了）：
   ```bash
   cd /path/to/plugin && zip -r /tmp/plugin-name.plugin . -x "setup/*" && cp /tmp/plugin-name.plugin /path/to/outputs/plugin-name.plugin
   ```
2. **把檔案以 `.plugin` 副檔名呈現給使用者**，讓他們可以直接安裝。（呈現 .plugin 檔案時，使用者會看到豐富的預覽，可以瀏覽 plugin 的檔案，並按一個按鈕接受這些客製化。）

> **重要**：一定要先在 `/tmp/` 建立 zip，再複製到 outputs 資料夾。直接寫進 outputs 資料夾可能會因為權限問題失敗，還會留下暫存檔。

> **命名**：`.plugin` 檔要使用原本的 plugin 目錄名稱（例如 plugin 目錄是 `coder`，輸出檔就該是 `coder.plugin`）。客製化過程中不要重新命名 plugin 或它的檔案，只替換佔位符的值和更新內容。

## 摘要輸出

客製化完成後，向使用者呈現一份依來源分組、說明學到什麼的摘要。一定要包含 MCP 的段落，說明設定過程中連接了哪些 MCP，以及使用者還該連接哪些：

```markdown
## From searching Slack

- You use Asana for project management
- Sprint cycles are 2 weeks

## From searching documents

- Story points use T-shirt sizes

## From your answers

- Ticket statuses are: Backlog, In Progress, In Review, Done
```

然後呈現設定過程中已連接的 MCP，以及使用者還該連接的 MCP，並附上連接的方法。

如果階段 1 沒有可用的知識類 MCP，而且使用者至少有一個問題得手動回答，就在結尾加上一則備註：

> By the way, connecting sources like Slack or Microsoft Teams would let me find answers automatically next time you customize a plugin.

## 其他資源

- **`references/mcp-servers.md`**：MCP 探索流程、類別對關鍵字的對照、設定檔位置
- **`references/search-strategies.md`**：用來找工具名稱和組織設定值的知識類 MCP 查詢模式
- **`examples/customized-mcp.json`**：已完整設定好的 `.mcp.json` 範例

---
name: cowork-plugin-customizer
description: >
  Customize a Claude Code plugin for a specific organization's tools and workflows.
  Use when: customize plugin, set up plugin, configure plugin, tailor plugin, adjust plugin settings,
  customize plugin connectors, customize plugin skill, tweak plugin, modify plugin configuration.
compatibility: Requires Cowork desktop app environment with access to mounted plugin directories (mnt/.local-plugins, mnt/.plugins).
---

# Cowork Plugin Customization

Customize a plugin for a specific organization — either by setting up a generic plugin template for the first time, or by tweaking and refining an already-configured plugin.

> **Finding the plugin**: To find the plugin's source files, run `find mnt/.local-plugins mnt/.plugins -type d -name "*<plugin-name>*"` to locate the plugin directory, then read its files to understand its structure before making changes. If you cannot find the plugin directory, the user is likely running this conversation in a remote container. Abort and let them know: "Customizing plugins is currently only available in the desktop app's Cowork mode."

## Determining the Customization Mode

After locating the plugin, check for `~~`-prefixed placeholders: `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'`

> **Default rule**: If `~~` placeholders exist, default to **Generic plugin setup** unless the user explicitly asks to customize a specific part of the plugin.

**1. Generic plugin setup** — The plugin contains `~~`-prefixed placeholders. These are customization points in a template that need to be replaced with real values (e.g., `~~Jira` → `Asana`, `~~your-team-channel` → `#engineering`).

**2. Scoped customization** — No `~~` placeholders exist, and the user asked to customize a specific part of the plugin (e.g., "customize the connectors", "update the standup skill", "change the ticket tool"). Read the plugin files to find the relevant section(s) and focus only on those. Do not scan the entire plugin or present unrelated customization items.

> **Legacy `commands/` directories**: Some plugins include a `commands/` directory. The Cowork UI now presents these alongside skills as a single "Skills" concept, so treat `commands/*.md` files the same way you would `skills/*/SKILL.md` files when customizing.

**3. General customization** — No `~~` placeholders exist, and the user wants to modify the plugin broadly. Read the plugin's files to understand its current configuration, then ask the user what they'd like to change.

> **Important**: Never change the name of the plugin or skill being customized. Do not rename directories, files, or the plugin/skill name fields.

> **Nontechnical output**: All user-facing output (todo list items, questions, summaries) must be written in plain, nontechnical language. Never mention `~~` prefixes, placeholders, or customization points to the user. Frame everything in terms of the plugin's capabilities and the organization's tools.

## Customization Workflow

### Phase 0: Gather User Intent (scoped and general customization only)

For **scoped customization** and **general customization** (not generic plugin setup), check whether the user provided free-form context alongside their request (e.g., "customize the standup skill — we do async standups in #eng-updates every morning").

- **If the user provided context**: Record it and use it to pre-fill answers in Phase 3 — skip asking questions that the user already answered here.
- **If the user did not provide context**: Ask a single open-ended question using AskUserQuestion before proceeding. Tailor the question to what they asked to customize — e.g., "What changes do you have in mind for the brief skill?" or "What would you like to change about how this plugin works?" Keep it short and specific to their request.

  Use their response (if any) as additional context throughout the remaining phases.

### Phase 1: Gather Context from Knowledge MCPs

Use company-internal knowledge MCPs to collect information relevant to the customization scope. See `references/search-strategies.md` for detailed query patterns by category.

**What to gather** (scope to what's relevant):

- Tool names and services the organization uses
- Organizational processes and workflows
- Team conventions (naming, statuses, estimation scales)
- Configuration values (workspace IDs, project names, team identifiers)

**Sources to search:**

1. **Chat/Slack MCPs** — tool mentions, integrations, workflow discussions
2. **Document MCPs** — onboarding docs, tool guides, setup instructions
3. **Email MCPs** — license notifications, admin emails, setup invitations

Record all findings for use in Phase 3.

### Phase 2: Create Todo List

Build a todo list of changes to make, scoped appropriately:

- **For scoped customization**: Only include items related to the specific section the user asked about.
- **For generic plugin setup**: Run `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'` to find all placeholder customization points. Group them by theme.
- **For general customization**: Read the plugin files, understand the current config, and based on the user's request, identify what needs to change.

Use user-friendly descriptions that focus on the plugin's purpose:

- **Good**: "Learn how standup prep works at Company"
- **Bad**: "Replace placeholders in skills/standup-prep/SKILL.md"

### Phase 3: Complete Todo Items

Work through each item using context from Phase 0 and Phase 1.

**If the user's free-form input (Phase 0) or knowledge MCPs (Phase 1) provided a clear answer**: Apply directly without confirmation.

**Otherwise**: Use AskUserQuestion. Don't assume "industry standard" defaults are correct — if neither the user's input nor knowledge MCPs provided a specific answer, ask. Note: AskUserQuestion always includes a Skip button and a free-text input box for custom answers, so do not include `None` or `Other` as options.

**Types of changes:**

1. **Placeholder replacements** (generic setup): `~~Jira` → `Asana`, `~~your-org-channel` → `#engineering`
2. **Content updates**: Modifying instructions, skills, workflows, or references to match the organization
3. **URL pattern updates**: `tickets.example.com/your-team/123` → `app.asana.com/0/PROJECT_ID/TASK_ID`
4. **Configuration values**: Workspace IDs, project names, team identifiers

If user doesn't know or skips, leave the value unchanged (or the `~~`-prefixed placeholder, for generic setup).

### Phase 4: Search for Useful MCPs

After customization items have been resolved, connect MCPs for any tools that were identified or changed. See `references/mcp-servers.md` for the full workflow, category-to-keywords mapping, and config file format.

For each tool identified during customization:

1. Search the registry: `search_mcp_registry(keywords=[...])` using category keywords from `references/mcp-servers.md`, or search for the specific tool name if already known
2. If unconnected: `suggest_connectors(directoryUuids=["chosen-uuid"])` — user completes auth
3. Update the plugin's MCP config file (check `plugin.json` for custom location, otherwise `.mcp.json` at root)

Collect all MCP results and present them together in the summary output (see below) — don't present MCPs one at a time during this phase.

## Packaging the Plugin

After all customizations are applied, package the plugin as a `.plugin` file for the user:

1. **Zip the plugin directory** (excluding `setup/` since it's no longer needed):
   ```bash
   cd /path/to/plugin && zip -r /tmp/plugin-name.plugin . -x "setup/*" && cp /tmp/plugin-name.plugin /path/to/outputs/plugin-name.plugin
   ```
2. **Present the file to the user** with the `.plugin` extension so they can install it directly. (Presenting the .plugin file will show to the user as a rich preview where they can look through the plugin files, and they can accept the customization by pressing a button.)

> **Important**: Always create the zip in `/tmp/` first, then copy to the outputs folder. Writing directly to the outputs folder may fail due to permissions and leave behind temporary files.

> **Naming**: Use the original plugin directory name for the `.plugin` file (e.g., if the plugin directory is `coder`, the output file should be `coder.plugin`). Do not rename the plugin or its files during customization — only replace placeholder values and update content.

## Summary Output

After customization, present the user with a summary of what was learned grouped by source. Always include the MCPs sections showing which MCPs were connected during setup and which ones the user should still connect:

```markdown
## From searching Slack

- You use Asana for project management
- Sprint cycles are 2 weeks

## From searching documents

- Story points use T-shirt sizes

## From your answers

- Ticket statuses are: Backlog, In Progress, In Review, Done
```

Then present the MCPs that were connected during setup and any that the user should still connect, with instructions on how to connect them.

If no knowledge MCPs were available in Phase 1, and the user had to answer at least one question manually, include a note at the end:

> By the way, connecting sources like Slack or Microsoft Teams would let me find answers automatically next time you customize a plugin.

## Additional Resources

- **`references/mcp-servers.md`** — MCP discovery workflow, category-to-keywords mapping, config file locations
- **`references/search-strategies.md`** — Knowledge MCP query patterns for finding tool names and org values
- **`examples/customized-mcp.json`** — Example fully configured `.mcp.json`