create-cowork-plugin

Cowork プラグインの作成

ガイド付きの会話を通じて、新しいプラグインをゼロから作成します。要件の把握、計画、設計、実装、パッケージ化までユーザーを案内し、最後にインストール可能な .plugin ファイルを提供します。

概要

プラグインは、スキル、エージェント、フック、MCP サーバー連携によって Claude の機能を拡張する、自己完結型のディレクトリです。このスキルには、プラグインのアーキテクチャ全体と、会話を通じてプラグインを作成するための5段階のワークフローがまとめられています。

手順：

1. 要件の把握 — ユーザーが何を作りたいのかを理解します
2. コンポーネントの計画 — 必要なコンポーネントの種類を判断します
3. 設計と確認の質問 — 各コンポーネントの詳細を決定します
4. 実装 — プラグインのすべてのファイルを作成します
5. レビューとパッケージ化 — .plugin ファイルを提供します

技術的な詳細を避けた出力：ユーザー向けの会話はすべて平易な言葉で行ってください。ユーザーから求められない限り、ファイルパス、ディレクトリ構造、スキーマフィールドなどの実装の詳細は明かさないでください。プラグインでできることを中心に説明してください。

プラグインのアーキテクチャ

ディレクトリ構造

すべてのプラグインは次の構成に従います。

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/ 形式：古いプラグインには、単一ファイルの .md スラッシュコマンドを格納する commands/ ディレクトリが含まれている場合があります。この形式も引き続き機能しますが、新しいプラグインでは skills/*/SKILL.md を使用してください。Cowork の UI ではどちらも単一の「スキル」として表示され、スキル形式では references/ を使った段階的な情報開示が可能です。

ルール：

• .claude-plugin/plugin.json は常に必要です
• コンポーネントのディレクトリ（skills/、agents/）は、.claude-plugin/ の内側ではなく、プラグインのルートに配置します
• プラグインが実際に使用するコンポーネントのディレクトリのみを作成します
• すべてのディレクトリ名とファイル名にはケバブケースを使用します

plugin.json マニフェスト

.claude-plugin/plugin.json に配置します。必須フィールドは name のみです。

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

名前のルール： ケバブケースを使用し、小文字とハイフンのみで構成します。スペースや特殊文字は使用できません。 バージョン： 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"
}

コンポーネントのスキーマ

各コンポーネントの種類の詳細なスキーマは references/component-schemas.md にあります。概要：

コンポーネント	場所	形式
スキル	skills/*/SKILL.md	Markdown + YAML フロントマター
MCP サーバー	.mcp.json	JSON
エージェント（Cowork ではあまり使われません）	agents/*.md	Markdown + YAML フロントマター
フック（Cowork ではほとんど使われません）	hooks/hooks.json	JSON
コマンド（従来形式）	commands/*.md	Markdown + YAML フロントマター

このスキーマは Claude Code のプラグインシステムと共通ですが、ここで作成するのは、ナレッジワーク向けのデスクトップアプリである Claude Cowork 用のプラグインです。 Cowork ユーザーにとっては、通常、スキルが最も役立ちます。新しいプラグインは skills/*/SKILL.md でひな形を作成してください。ユーザーが従来の単一ファイル形式を明示的に必要としている場合を除き、commands/ は作成しないでください。

~~プレースホルダーを使用したカスタマイズ可能なプラグイン

デフォルトでは、このパターンを使用したり、質問したりしないでください。 ユーザーが、組織外の人にもプラグインを使ってもらいたいと明確に述べた場合にのみ、~~プレースホルダーを導入してください。 ユーザーがプラグインを外部に配布したいようであれば、この方法も選択肢の一つとして紹介できますが、AskUserQuestionを使ってこちらから質問してはいけません。

社外の人と共有することを目的としたプラグインでは、個々のユーザーに合わせて調整が必要な箇所がある場合があります。 特定の製品（たとえば「Jira」）ではなく、カテゴリ名（たとえば「プロジェクト管理ツール」）で外部ツールを参照する必要があるかもしれません。 共有が必要な場合は、汎用的な表現を使い、create an issue in ~~project trackerのようにチルダ2つを付けて、カスタマイズが必要な箇所を示してください。 ツールのカテゴリを使用した場合は、プラグインのルートに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には必ずSkipボタンと自由記述用の入力欄が含まれるため、選択肢にNoneやOtherを含めないでください。

フェーズ1：要件の確認

目標：ユーザーが何を、なぜ作りたいのかを把握します。

質問してください（不明な点に限り、ユーザーの最初の依頼ですでに回答されている質問は省略してください）。

• このプラグインで何ができるようにしますか？ どのような問題を解決しますか？
• 誰が、どのような状況で使用しますか？
• 外部のツールやサービスと連携しますか？
• 参考にできる類似のプラグインやワークフローはありますか？

把握した内容を要約し、次に進む前に確認してください。

出力：プラグインの目的と範囲を明確に示した説明。

フェーズ2：コンポーネントの計画

目標：プラグインに必要なコンポーネントの種類を判断します。

要件の確認で得た回答に基づき、次の項目を判断してください。

• スキル — Claudeが必要に応じて読み込む専門知識や、ユーザーが開始するアクションが必要ですか？（分野の専門知識、参照用スキーマ、ワークフローガイド、デプロイ／設定／分析／レビューのアクション）
• MCP サーバー — 外部サービスとの連携が必要ですか？（データベース、API、SaaSツール）
• エージェント（一般的ではありません） — 自律的に複数の手順を実行するタスクがありますか？（検証、生成、分析）
• フック（まれです） — 特定のイベントで何かを自動的に実行する必要がありますか？（ポリシーの適用、コンテキストの読み込み、操作の検証）

作成しないと判断したコンポーネントの種類も含め、コンポーネント計画の表を提示してください。

| 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：設計と確認事項

目標：各コンポーネントを詳細に仕様化します。実装を始める前に、すべての曖昧な点を解消してください。

計画に含まれるコンポーネントの種類ごとに、設計に関する具体的な質問をします。質問はコンポーネントの種類ごとにまとめて提示します。回答を待ってから次に進んでください。

スキル：

• どのようなユーザーの問い合わせをきっかけに、このスキルを実行しますか？
• どの知識分野を対象にしますか？
• 詳細な内容を記載した参考ファイルを含めますか？
• スキルがユーザーによって開始されるアクションを表す場合、どのような引数を受け付け、どのツールが必要ですか？（Read、Write、Bash、Grep など）

エージェント：

• 各エージェントは自発的に起動しますか、それとも要求された場合にのみ起動しますか？
• どのツールが必要ですか？
• 出力形式はどうしますか？

フック：

• どのイベントを対象にしますか？（PreToolUse、PostToolUse、Stop、SessionStart など）
• 検証、ブロック、変更、コンテキストの追加など、どのような動作をさせますか？
• プロンプトベース（LLM による処理）にしますか、それともコマンドベース（決定論的なスクリプト）にしますか？

MCP サーバー：

• サーバーの種類は何ですか？（ローカル用の stdio、OAuth を使用するホスト型の SSE、REST API 用の HTTP）
• 認証方法は何ですか？
• どのツールを公開しますか？

ユーザーが「最適だと思うものを選んで」と答えた場合は、具体的な推奨事項を提示し、明示的な確認を得てください。

出力：すべてのコンポーネントの詳細な仕様。

フェーズ 4：実装

目標：ベストプラクティスに従って、すべてのプラグインファイルを作成します。

作業順序：

1. プラグインのディレクトリ構造を作成する
2. plugin.json マニフェストを作成する
3. 各コンポーネントを作成する（正確な形式については references/component-schemas.md を参照）
4. プラグインを説明する README.md を作成する

実装ガイドライン：

• スキルでは段階的な情報開示を採用します。SKILL.md の本文は簡潔に保ち（3,000 語未満）、詳細な内容は references/ に記載します。フロントマターの説明は、具体的なトリガーフレーズを含む三人称で記述する必要があります。スキルの本文は、ユーザーへのメッセージではなく、Claude への指示です。何をすべきかを示す指示として記述してください。
• エージェントには、起動条件を示す <example> ブロックを含む説明と、Markdown 本文のシステムプロンプトが必要です。
• フックの設定は hooks/hooks.json に記述します。スクリプトのパスには ${CLAUDE_PLUGIN_ROOT} を使用します。複雑なロジックには、プロンプトベースのフックを優先してください。
• MCP の設定は、プラグインのルートにある .mcp.json に記述します。ローカルサーバーのパスには ${CLAUDE_PLUGIN_ROOT} を使用します。必要な環境変数を README に記載してください。

フェーズ 5：レビューとパッケージ化

目標：完成したプラグインを納品します。

1. 作成したものを要約し、各コンポーネントとその目的を列挙する

2. ユーザーに調整が必要か確認する

3. claude plugin validate <path-to-plugin-json> を実行して、プラグインの構造を確認する。このコマンドを使用できない場合（たとえば、Cowork 内で実行している場合）は、次の項目を手動で検証する：

   • .claude-plugin/plugin.json が存在し、少なくとも name フィールドを含む有効な JSON である
   • name フィールドが kebab-case（小文字、数字、ハイフンのみ）である
   • プラグインが参照するコンポーネントディレクトリ（commands/、skills/、agents/、hooks/）が実際に存在し、想定される形式のファイル（commands/skills/agents は .md、hooks は .json）を含んでいる
   • 各スキルのサブディレクトリに 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 ファイルはチャット内にリッチプレビューとして表示されます。ユーザーはファイルを閲覧し、ボタンを押してプラグインを受け入れることができます。

ベストプラクティス

• 小さく始める：まずは必要最小限のコンポーネントから始めます。よく練られたスキルが1つあるプラグインのほうが、作り込みの足りないコンポーネントが5つあるプラグインより役立ちます。
• スキルでは段階的に情報を提示する：基本的な知識はSKILL.mdに、詳細な参考資料はreferences/に、実際に動作する例はexamples/に記載します。
• 明確なトリガーフレーズ：スキルの説明には、ユーザーが実際に使う具体的なフレーズを含めます。エージェントの説明には<example>ブロックを含めます。
• スキルはClaude向けです：スキル本文は、ユーザーが読むドキュメントではなく、Claudeが従う指示として記述します。
• 命令形で記述する：スキルでは動詞から始まる指示を使います（「設定ファイルを解析する」であり、「設定ファイルを解析する必要があります」ではありません）。
• 移植性：プラグイン内のパスには必ず${CLAUDE_PLUGIN_ROOT}を使い、ハードコードしたパスは使いません。
• セキュリティ：認証情報には環境変数を使い、リモートサーバーにはHTTPSを使い、ツールへのアクセス権限は必要最小限にします。

追加リソース

• references/component-schemas.md — 各コンポーネントタイプ（スキル、エージェント、フック、MCP、レガシーコマンド、CONNECTORS.md）の詳細な形式仕様
• references/example-plugins.md — 複雑さの異なる3種類の完全なプラグイン構成例