create-cowork-plugin

创建 Cowork 插件

通过引导式对话从零开始构建新插件。带领用户完成需求探索、规划、设计、实现和打包，最终交付一个可直接安装的 .plugin 文件。

概述

插件是一个自包含的目录，通过技能、Agent、钩子和 MCP 服务集成来扩展 Claude 的能力。本技能封装了完整的插件架构，以及以对话方式创建插件的五阶段工作流。

流程如下：

1. 需求探索：了解用户想要构建什么
2. 组件规划：确定需要哪些组件类型
3. 设计与澄清问题：详细说明每个组件
4. 实现：创建所有插件文件
5. 审查与打包：交付 .plugin 文件

非技术化输出：所有面向用户的对话都使用通俗易懂的语言。除非用户主动询问，否则不要暴露文件路径、目录结构或 schema 字段等实现细节。一律从插件将要实现的功能出发进行描述。

插件架构

目录结构

每个插件都遵循以下布局：

plugin-name/
├── .claude-plugin/
│   └── plugin.json           # Required: plugin manifest
├── skills/                   # Skills (subdirectories with SKILL.md)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── agents/                   # Subagent definitions (.md files)
├── .mcp.json                 # MCP server definitions
└── README.md                 # Plugin documentation

旧版 commands/ 格式：较早的插件可能包含 commands/ 目录，其中是单文件 .md 斜杠命令。该格式仍然可用，但新插件应改用 skills/*/SKILL.md。Cowork 界面会把两者统一呈现为“技能”这一概念，并且技能格式通过 references/ 支持渐进式披露。

规则：

• .claude-plugin/plugin.json 始终是必需的
• 组件目录（skills/、agents/）放在插件根目录下，而不是放在 .claude-plugin/ 内部
• 只为插件实际使用的组件创建目录
• 所有目录和文件名均使用 kebab-case

plugin.json 清单

位于 .claude-plugin/plugin.json。唯一必填字段是 name。

{
  "name": "plugin-name",
  "version": "0.1.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name"
  }
}

名称规则： kebab-case，小写字母加连字符，不含空格或特殊字符。 版本： 采用 semver 格式（MAJOR.MINOR.PATCH）。从 0.1.0 开始。

可选字段：homepage、repository、license、keywords。

可以指定自定义组件路径（这是对自动发现机制的补充，而非替代）：

{
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

组件 Schema

每种组件类型的详细 schema 位于 references/component-schemas.md。概要如下：

组件	位置	格式
技能	skills/*/SKILL.md	Markdown + YAML frontmatter
MCP 服务	.mcp.json	JSON
Agent（在 Cowork 中较少使用）	agents/*.md	Markdown + YAML frontmatter
钩子（在 Cowork 中很少使用）	hooks/hooks.json	JSON
命令（旧版）	commands/*.md	Markdown + YAML frontmatter

该 schema 与 Claude Code 的插件系统共用，但你创建的是面向 Claude Cowork 的插件，Cowork 是一款用于知识工作的桌面应用。 Cowork 用户通常会觉得技能最有用。新插件应使用 skills/*/SKILL.md 进行脚手架搭建，除非用户明确需要旧版单文件格式，否则不要创建 commands/。

带有 ~~ 占位符的可定制插件

默认不要使用或询问此模式。 只有当用户明确表示希望插件的使用者来自其组织之外时，才引入 ~~ 占位符。 如果用户似乎想对外分发插件，可以提及这是一个可选项，但不要主动使用 AskUserQuestion 询问此事。

当插件需要与公司之外的其他人共享时，其中某些部分可能需要根据个人用户进行调整。 你可能需要按类别而非具体产品来引用外部工具（例如用"项目跟踪工具"代替"Jira"）。 需要共享时，请使用通用表述，并用两个波浪号标记这些需要自定义的内容，例如 在 ~~项目跟踪工具 中创建一个问题。 如果使用了任何工具类别，请在插件根目录下编写 CONNECTORS.md 文件，用于说明：

# Connectors

## How tool references work

Plugin files use `~~category` as a placeholder for whatever tool the user
connects in that category. Plugins are tool-agnostic — they describe
workflows in terms of categories rather than specific products.

## Connectors for this plugin

| Category        | Placeholder         | Options                         |
| --------------- | ------------------- | ------------------------------- |
| Chat            | `~~chat`            | Slack, Microsoft Teams, Discord |
| Project tracker | `~~project tracker` | Linear, Asana, Jira             |

${CLAUDE_PLUGIN_ROOT} 变量

在钩子和 MCP 配置中，所有插件内部的路径引用都使用 ${CLAUDE_PLUGIN_ROOT}。切勿硬编码绝对路径。

引导式工作流

当你需要向用户提问时，请使用 AskUserQuestion。不要假设"行业标准"的默认值是正确的。注意：AskUserQuestion 始终包含一个跳过按钮和一个用于自定义答案的自由文本输入框，因此不要将 None 或 Other 作为选项。

阶段 1：需求探索

目标：了解用户想要构建什么以及原因。

提问（仅询问不清楚的内容——如果用户的初始请求已经回答了某些问题，则跳过这些问题）：

• 这个插件应该做什么？它解决什么问题？
• 谁会使用它，在什么场景下使用？
• 它是否需要与任何外部工具或服务集成？
• 是否有可以参考的类似插件或工作流？

在继续之前，总结你的理解并请用户确认。

输出：清晰说明插件的目的和范围。

阶段 2：组件规划

目标：确定插件需要哪些组件类型。

根据需求探索阶段的回答，确定以下内容：

• Skills——是否需要 Claude 按需加载的专业知识，或用户主动发起的操作？（领域专业知识、参考模式、工作流指南、部署/配置/分析/审查操作）
• MCP 服务——是否需要集成外部服务？（数据库、API、SaaS 工具）
• Agents（不常用）——是否存在自主的多步骤任务？（验证、生成、分析）
• Hooks（很少用）——是否应在特定事件发生时自动执行某些操作？（执行策略、加载上下文、验证操作）

展示组件规划表，并包含你决定不创建的组件类型：

| Component | Count | Purpose |
|-----------|-------|---------|
| Skills    | 3     | Domain knowledge for X, /do-thing, /check-thing |
| Agents    | 0     | Not needed |
| Hooks     | 1     | Validate writes |
| MCP       | 1     | Connect to service Y |

在继续之前，获得用户的确认或调整意见。

输出：确认后的待创建组件列表。

阶段 3：设计与澄清问题

目标：详细说明每个组件。在实现之前解决所有歧义。

针对计划中的每种组件类型，提出有针对性的设计问题。按组件类型分组呈现问题。等待回答后再继续。

Skills：

• 哪些用户查询应触发该 Skill？
• 它涵盖哪些知识领域？
• 是否需要包含用于详细内容的参考文件？
• 如果该 Skill 代表用户发起的操作：它接受哪些参数，需要哪些工具？（Read、Write、Bash、Grep 等）

Agents：

• 每个 Agent 应主动触发，还是仅在被请求时触发？
• 它需要哪些工具？
• 输出格式应该是什么？

Hooks：

• 哪些事件？（PreToolUse、PostToolUse、Stop、SessionStart 等）
• 行为是什么：验证、阻止、修改，还是添加上下文？
• 基于提示词（由大模型驱动）还是基于命令（确定性脚本）？

MCP 服务：

• 服务类型是什么？（本地使用 stdio，带 OAuth 的托管服务使用 SSE，REST API 使用 HTTP）
• 采用何种身份验证方式？
• 应暴露哪些工具？

如果用户表示“你认为最好的方案即可”，请提供具体建议，并获得明确确认。

输出：为每个组件提供详细说明。

阶段 4：实现

目标：遵循最佳实践创建所有插件文件。

操作顺序：

1. 创建插件目录结构
2. 创建 plugin.json 清单文件
3. 创建每个组件（具体格式参见 references/component-schemas.md）
4. 创建记录该插件的 README.md

实现指南：

• Skills 采用渐进式披露：精简的 SKILL.md 正文（少于 3,000 词），详细内容放在 references/ 中。Frontmatter 的 description 必须使用第三人称，并包含具体的触发短语。Skill 正文是写给 Claude 的指令，而不是发给用户的消息，应以关于该做什么的指令形式编写。
• Agents 需要一个带有 <example> 代码块的 description，用于展示触发条件，并在 Markdown 正文中提供系统提示词。
• Hooks 配置放在 hooks/hooks.json 中。脚本路径使用 ${CLAUDE_PLUGIN_ROOT}。复杂逻辑优先使用基于提示词的 Hooks。
• MCP 配置放在插件根目录的 .mcp.json 中。本地服务路径使用 ${CLAUDE_PLUGIN_ROOT}。在 README 中记录所需的环境变量。

阶段 5：审查与打包

目标：交付完成的插件。

1. 总结已创建的内容：列出每个组件及其用途

2. 询问用户是否需要任何调整

3. 运行 claude plugin validate <path-to-plugin-json> 检查插件结构。如果该命令不可用（例如在 Cowork 内运行时），请手动验证结构：

   • .claude-plugin/plugin.json 存在，且包含有效的 JSON，至少有一个 name 字段
   • name 字段为 kebab-case（仅包含小写字母、数字和连字符）
   • 插件引用的所有组件目录（commands/、skills/、agents/、hooks/）确实存在，并包含预期格式的文件：commands/skills/agents 使用 .md，hooks 使用 .json
   • 每个 Skill 子目录都包含 SKILL.md
   • 以与 CLI 验证器相同的方式报告通过和未通过的项目

   在继续之前修复所有错误。

4. 打包为 .plugin 文件：

cd /path/to/plugin-dir && zip -r /tmp/plugin-name.plugin . -x "*.DS_Store" && cp /tmp/plugin-name.plugin /path/to/outputs/plugin-name.plugin

重要：务必先在 /tmp/ 中创建 zip 文件，然后再复制到输出文件夹。直接写入输出文件夹可能因权限问题而失败。

命名：.plugin 文件使用 plugin.json 中的插件名称（例如，如果名称为 code-reviewer，则输出 code-reviewer.plugin）。

.plugin 文件将以富预览形式显示在聊天中，用户可以在其中浏览文件，并通过点击按钮接受该插件。

最佳实践

• 从小处着手：从最小可行的组件集合开始。一个设计精良的技能，比五个半成品组件更有用。
• 技能的渐进式披露：核心知识放在 SKILL.md 中，详细参考资料放在 references/ 中，可运行的示例放在 examples/ 中。
• 清晰的触发短语：技能描述应包含用户可能会说的具体短语。Agent 描述应包含 <example> 代码块。
• 技能面向 Claude：技能正文应写成供 Claude 遵循的指令，而不是供用户阅读的文档。
• 祈使句写作风格：在技能中使用动词开头的指令（"解析配置文件"，而不是"你应该解析配置文件"）。
• 可移植性：插件内部路径始终使用 ${CLAUDE_PLUGIN_ROOT}，切勿使用硬编码路径。
• 安全性：凭据使用环境变量，远程服务使用 HTTPS，工具访问遵循最小权限原则。

附加资源

• references/component-schemas.md — 每种组件类型的详细格式规范（技能、Agent、钩子、MCP、旧版命令、CONNECTORS.md）
• references/example-plugins.md — 三个不同复杂度级别的完整示例插件结构