cowork-plugin-customizer

Original source / Raw SKILL.md

---
name: cowork-plugin-customizer
description: >
  Customize or personalize a Claude Code plugin for a specific organization's tools and workflows.
  Use when users want to customize a plugin, replace tool placeholders, or configure MCP servers for a plugin.
  This skill requires Cowork mode with mounted plugin directories and will not work in remote or standard CLI sessions.
compatibility: Requires Cowork desktop app environment with access to mounted plugin directories (mnt/.local-plugins, mnt/.plugins).
---

# Cowork Plugin Customization

Adapt a generic plugin template to a specific organization by replacing customization points with actual tool names, configuring MCP servers, and applying organization-specific customizations.

> **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."

## Overview

Generic plugins mark customization points with a `~~` prefix. Any line or value starting with `~~` is a placeholder that should be replaced during customization (e.g., `~~Jira` → `Asana`, `~~your-team-channel` → `#engineering`). To find all customization points in a plugin, use:

```bash
grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'
```

> **Important**: Never change the name of the plugin or skill being customized. Only replace `~~`-prefixed placeholder values and update content — 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 learning about the organization and its tools.

The process:
1. **Gather context** — use knowledge MCPs to learn what tools and processes the organization uses
2. **Create todo list** — grep for `~~\w` to find all customization points and build a todo list
3. **Complete todo items** — apply gathered context, falling back to user questions when unclear
4. **Search for useful MCPs** — find and connect MCPs for identified tools

If an answer cannot be found via knowledge MCPs or user input, leave the customization point unchanged for a future customization cycle.

## Customization Workflow

### Phase 1: Gather Context from Knowledge MCPs

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

**What to gather:**
- Tool names for each `~~`-prefixed placeholder
- 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 from Customization Points

Run `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'` to find all customization points. Group them by theme and create a todo list with user-friendly descriptions that focus on learning about the organization:

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

### Phase 3: Complete Todo Items

Work through each item using Phase 1 context.

**If knowledge MCPs provided a clear answer**: Apply directly without confirmation.

**Otherwise**: Use AskUserQuestion. Don't assume "industry standard" defaults are correct — if knowledge MCPs didn't provide 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. **Customization point replacements**: `~~Jira` → `Asana`, `~~your-org-channel` → `#engineering`
2. **URL pattern updates**: `tickets.example.com/your-team/123` → `app.asana.com/0/PROJECT_ID/TASK_ID`
3. **Organization-specific values**: Workspace IDs, project names, team identifiers

If user doesn't know or skips, leave the `~~`-prefixed value unchanged.

### Phase 4: Search for Useful MCPs

After all customization points have been resolved, connect MCPs for the tools that were identified. 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 OAuth
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.

**Note:** First-party integrations (Gmail, Google Calendar, Google Drive) are connected at the user level and don't need plugin `.mcp.json` entries.

## 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`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/search-strategies.md

```markdown
# Knowledge MCP Search Strategies

Query patterns for gathering organizational context during plugin customization.

## Finding Tool Names

**Source control:**
- Search: "GitHub" OR "GitLab" OR "Bitbucket"
- Search: "pull request" OR "merge request"
- Look for: repository links, CI/CD mentions

**Project management:**
- Search: "Asana" OR "Jira" OR "Linear" OR "Monday"
- Search: "sprint" AND "tickets"
- Look for: task links, project board mentions

**Chat:**
- Search: "Slack" OR "Teams" OR "Discord"
- Look for: channel mentions, integration discussions

**Analytics:**
- Search: "Datadog" OR "Grafana" OR "Mixpanel"
- Search: "monitoring" OR "observability"
- Look for: dashboard links, alert configurations

**Design:**
- Search: "Figma" OR "Sketch" OR "Adobe XD"
- Look for: design file links, handoff discussions

**CRM:**
- Search: "Salesforce" OR "HubSpot"
- Look for: deal mentions, customer record links

## Finding Organization Values

**Workspace/project IDs:**
- Search for existing integrations or bookmarked links
- Look for admin/setup documentation

**Team conventions:**
- Search: "story points" OR "estimation"
- Search: "workflow" OR "ticket status"
- Look for engineering process docs

**Channel/team names:**
- Search: "standup" OR "engineering" OR "releases"
- Look for channel naming patterns

## When Knowledge MCPs Are Unavailable

If no knowledge MCPs are configured, skip automatic discovery and proceed directly to AskUserQuestion for all categories. 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.

```

### references/mcp-servers.md

```markdown
# MCP Discovery and Connection

How to find and connect MCPs during plugin customization.

## Available Tools

### `search_mcp_registry`
Search the MCP directory for available connectors.

**Input:** `{ "keywords": ["array", "of", "search", "terms"] }`

**Output:** Up to 10 results, each with:
- `name`: MCP display name
- `description`: One-liner description
- `tools`: List of tool names the MCP provides
- `url`: MCP endpoint URL (use this in `.mcp.json`)
- `directoryUuid`: UUID for use with suggest_connectors
- `connected`: Boolean - whether user has this MCP connected

### `suggest_connectors`
Display Connect buttons to let users install/connect MCPs.

**Input:** `{ "directoryUuids": ["uuid1", "uuid2"] }`

**Output:** Renders UI with Connect buttons for each MCP

## Category-to-Keywords Mapping

| Category | Search Keywords |
|----------|-----------------|
| `project-management` | `["asana", "jira", "linear", "monday", "tasks"]` |
| `software-coding` | `["github", "gitlab", "bitbucket", "code"]` |
| `chat` | `["slack", "teams", "discord"]` |
| `documents` | `["google docs", "notion", "confluence"]` |
| `calendar` | `["google calendar", "calendar"]` |
| `email` | `["gmail", "outlook", "email"]` |
| `design-graphics` | `["figma", "sketch", "design"]` |
| `analytics-bi` | `["datadog", "grafana", "analytics"]` |
| `crm` | `["salesforce", "hubspot", "crm"]` |
| `wiki-knowledge-base` | `["notion", "confluence", "outline", "wiki"]` |
| `data-warehouse` | `["bigquery", "snowflake", "redshift"]` |
| `conversation-intelligence` | `["gong", "chorus", "call recording"]` |

## Workflow

1. **Find customization point**: Look for `~~`-prefixed values (e.g., `~~Jira`)
2. **Check earlier phase findings**: Did you already learn which tool they use?
   - **Yes**: Search for that specific tool to get its `url`, skip to step 5
   - **No**: Continue to step 3
3. **Search**: Call `search_mcp_registry` with mapped keywords
4. **Present choices and ask user**: Show all results, ask which they use
5. **Connect if needed**: If not connected, call `suggest_connectors`
6. **Update MCP config**: Add config using the `url` from search results

## Updating Plugin MCP Configuration

### Finding the Config File

1. **Check `plugin.json`** for an `mcpServers` field:
   ```json
   {
     "name": "my-plugin",
     "mcpServers": "./config/servers.json"
   }
   ```
   If present, edit the file at that path.

2. **If no `mcpServers` field**, use `.mcp.json` at the plugin root (default).

3. **If `mcpServers` points only to `.mcpb` files** (bundled servers), create a new `.mcp.json` at the plugin root.

### Config File Format

Both wrapped and unwrapped formats are supported:

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
```

Use the `url` field from `search_mcp_registry` results.

**Note:** First-party integrations (Gmail, Google Calendar, Google Drive) are connected at the user level and don't need plugin `.mcp.json` entries.

```

### examples/customized-mcp.json

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "asana": {
      "type": "sse",
      "url": "https://mcp.asana.com/sse"
    },
    "slack": {
      "type": "http",
      "url": "https://slack.mcp.claude.com/mcp"
    },
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    "datadog": {
      "type": "http",
      "url": "https://api.datadoghq.com/mcp",
      "headers": {
        "DD-API-KEY": "${DATADOG_API_KEY}",
        "DD-APPLICATION-KEY": "${DATADOG_APP_KEY}"
      }
    }
  },
  "recommendedCategories": [
    "source-control",
    "project-management",
    "chat",
    "documents",
    "wiki-knowledge-base",
    "design-graphics",
    "analytics-bi"
  ]
}

```