Improve plugin customizer for scoped and general customization (#54)

* Improve plugin customizer to support scoped and general customization

- Add three customization modes: scoped (specific section), generic
  (template setup with ~~ placeholders), and general (tweaking existing)
- Add Phase 0 for gathering user intent before diving into customization
- Clarify MCP server type descriptions (SSE/HTTP transport labels)
- Document directory entries without URLs (name-based matching)
- Update component-schemas.md with consistent MCP terminology

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* remove note about 1p connectors

* Address PR review: keyword-style "use when" and default to placeholder track

Rewrite skill description's "use when" guidance as keyword phrases instead
of logical clauses for better matching. Default to generic plugin setup mode
when ~~placeholders exist, even if user requested scoped customization, to
prevent incomplete plugin configuration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Remove server type selection guide from component schemas

MCP server type details are unnecessary for plugin authors and add noise
to the reference doc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Soften placeholder default rule to respect explicit user intent

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Bump cowork-plugin-management version to 0.2.2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: lee-weisberger

cowork-plugin-management/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-plugin-management",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Create, customize, and manage plugins tailored to your organization's tools and workflows. Configure MCP servers, adjust plugin behavior, and adapt templates to match how your team works.",
   "author": {
     "name": "Anthropic"

cowork-plugin-management/skills/cowork-plugin-customizer/SKILL.md

@@ -1,46 +1,51 @@
 ---
 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.
+  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, customize plugin command, 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
 
-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.
+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."
 
-## Overview
+## Determining the Customization Mode
 
-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:
+After locating the plugin, check for `~~`-prefixed placeholders: `grep -rn '~~\w' /path/to/plugin --include='*.md' --include='*.json'`
 
-```bash
-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`).
 
-> **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.
+**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 command", "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.
 
-> **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.
+**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.
 
-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
+> **Important**: Never change the name of the plugin or skill being customized. Do not rename directories, files, or the plugin/skill name fields.
 
-If an answer cannot be found via knowledge MCPs or user input, leave the customization point unchanged for a future customization cycle.
+> **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 command — 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 command?" 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. See `references/search-strategies.md` for detailed query patterns by category.
+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:**
-- Tool names for each `~~`-prefixed placeholder
+**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)
@@ -52,42 +57,47 @@ Use company-internal knowledge MCPs to collect information. See `references/sear
 
 Record all findings for use in Phase 3.
 
-### Phase 2: Create Todo List from Customization Points
+### Phase 2: Create Todo List
+
+Build a todo list of changes to make, scoped appropriately:
 
-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:
+- **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 commands/standup-prep.md"
 
 ### Phase 3: Complete Todo Items
 
-Work through each item using Phase 1 context.
+Work through each item using context from Phase 0 and Phase 1.
 
-**If knowledge MCPs provided a clear answer**: Apply directly without confirmation.
+**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 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.
+**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. **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
+1. **Placeholder replacements** (generic setup): `~~Jira` → `Asana`, `~~your-org-channel` → `#engineering`
+2. **Content updates**: Modifying instructions, commands, 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 `~~`-prefixed value unchanged.
+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 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.
+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 OAuth
+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.
 
-**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:

cowork-plugin-management/skills/cowork-plugin-customizer/references/mcp-servers.md

@@ -86,4 +86,6 @@ Both wrapped and unwrapped formats are supported:
 
 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.
+### Directory Entries Without a URL
+
+Some directory entries have no `url` because the endpoint is dynamic — the admin provides it when connecting the server. These servers can still be referenced in the plugin's MCP config by **name**: if the MCP server name in the config matches the directory entry name, it is treated the same as a URL match.

cowork-plugin-management/skills/create-cowork-plugin/references/component-schemas.md

@@ -294,7 +294,7 @@ Decisions: `approve`, `block`, `ask_user` (ask for confirmation).
 }
 ```
 
-**SSE** (hosted with OAuth):
+**SSE** (remote server, server-sent events transport):
 ```json
 {
   "mcpServers": {
@@ -306,7 +306,7 @@ Decisions: `approve`, `block`, `ask_user` (ask for confirmation).
 }
 ```
 
-**HTTP** (REST API):
+**HTTP** (remote server, streamable HTTP transport):
 ```json
 {
   "mcpServers": {
@@ -321,14 +321,6 @@ Decisions: `approve`, `block`, `ask_user` (ask for confirmation).
 }
 ```
 
-### Server Type Selection Guide
-
-| Type | Best for | Auth method |
-|------|----------|-------------|
-| stdio | Local tools, custom servers | Environment variables |
-| SSE | Hosted cloud services | OAuth (automatic) |
-| HTTP | REST API backends | Token headers |
-
 ### Environment Variable Expansion
 
 All MCP configs support `${VAR_NAME}` substitution:
@@ -337,6 +329,10 @@ All MCP configs support `${VAR_NAME}` substitution:
 
 Document all required environment variables in the plugin README.
 
+### Directory Servers Without a URL
+
+Some MCP directory entries have no `url` because the endpoint is dynamic. Plugins can reference these servers by **name** instead — if the server name in the plugin's MCP config matches the directory entry name, it is treated the same as a URL match.
+
 ## CONNECTORS.md
 
 **Location**: Plugin root