Cowork プラグインを作成

ガイド付きの会話を通じてゼロからプラグインを構築します。ユーザーをディスカバリー、計画、設計、実装、パッケージングの各段階を経由してウォークスルーし、最後にインストール可能な .plugin ファイルを配信します。

概要

プラグインはスキル、エージェント、フック、および MCP サーバー統合を使用して Claude の機能を拡張する自己完結型ディレクトリです。このスキルはプラグインアーキテクチャ全体と、対話的に作成するための 5 段階のワークフローをエンコードしています。

プロセス：

1. ディスカバリー — ユーザーが何を構築したいのかを理解する
2. コンポーネント計画 — どのコンポーネントタイプが必要かを決定する
3. 設計と質問の明確化 — 各コンポーネントを詳細に指定する
4. 実装 — すべてのプラグインファイルを作成する
5. レビューとパッケージ化 — .plugin ファイルを配信する

非技術的な出力: ユーザーに表示される会話はすべて平易な言語で保ってください。ユーザーが質問しない限り、ファイルパス、ディレクトリ構造、スキーマフィールドなどの実装詳細は公開しないでください。すべてをプラグインが何をするかという観点から説明してください。

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

ディレクトリ構造

すべてのプラグインは次のレイアウトに従います：

plugin-name/
├── .claude-plugin/
│   └── plugin.json           # 必須: プラグインマニフェスト
├── skills/                   # スキル (SKILL.md を含むサブディレクトリ)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── agents/                   # サブエージェント定義 (.md ファイル)
├── .mcp.json                 # MCP サーバー定義
└── README.md                 # プラグインドキュメント

レガシー commands/ フォーマット: 古いプラグインは単一ファイル .md スラッシュコマンドを含む commands/ ディレクトリを含む場合があります。このフォーマットは引き続き機能しますが、新しいプラグインは代わりに skills/*/SKILL.md を使用する必要があります。Cowork UI は両方を単一の「スキル」概念として表示し、スキルフォーマットは 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": "プラグインの目的についての簡潔な説明",
  "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"
}

コンポーネントスキーマ

各コンポーネントタイプの詳細スキーマは references/component-schemas.md に記載されています。概要：

コンポーネント	場所	フォーマット
スキル	skills/*/SKILL.md	Markdown + YAML frontmatter
MCP サーバー	.mcp.json	JSON
エージェント	agents/*.md	Markdown + YAML frontmatter
フック	hooks/hooks.json	JSON
コマンド (レガシー)	commands/*.md	Markdown + YAML frontmatter

このスキーマは Claude Code のプラグインシステムと共有されていますが、Claude Cowork (知識作業用デスクトップアプリ) のプラグインを作成しています。 Cowork ユーザーは通常、スキルが最も有用だと感じるでしょう。新しいプラグインは skills/*/SKILL.md でスカフォールドしてください。ユーザーが明示的にレガシー単一ファイルフォーマットが必要でない限り、commands/ を作成しないでください。

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

デフォルトではこのパターンを使用したり、尋ねたりしないでください。 ユーザーが明示的に組織外の人々がプラグインを使用したいと言った場合のみ、~~ プレースホルダーを導入してください。 ユーザーが外部でプラグインを配布したいように見える場合、これが選択肢であることを言及できますが、AskUserQuestion で予防的に尋ねないでください。

プラグインが会社外の他者と共有する予定がある場合、個々のユーザーに適応する必要があるプラグイン部分がある可能性があります。 特定の製品ではなくカテゴリ別に外部ツールを参照する必要があるかもしれません（例：「Jira」ではなく「プロジェクトトラッカー」）。 共有が必要な場合、汎用的な言語を使用し、これらを ~~project tracker などの 2 つのチルダ文字でカスタマイズが必要なものとしてマークします。 ツールカテゴリを使用した場合、プラグインルートで CONNECTORS.md ファイルを作成して説明してください：

# コネクタ

## ツール参照の仕組み

プラグインファイルは `~~category` をユーザーがそのカテゴリで接続するツールのプレースホルダーとして使用します。プラグインはツールに依存しません。特定の製品ではなく、ワークフローをカテゴリの観点から説明します。

## このプラグインのコネクタ

| カテゴリ        | プレースホルダー    | オプション                      |
| --------------- | ------------------- | ------------------------------- |
| チャット        | `~~chat`            | Slack、Microsoft Teams、Discord |
| プロジェクトトラッカー | `~~project tracker` | Linear、Asana、Jira             |

${CLAUDE_PLUGIN_ROOT} 変数

フック と MCP 設定内のすべてのプラグイン内パス参照には ${CLAUDE_PLUGIN_ROOT} を使用してください。絶対パスはハードコードしないでください。

ガイド付きワークフロー

ユーザーに質問するときは AskUserQuestion を使用してください。「業界標準」のデフォルトが正しいと仮定しないでください。注意: AskUserQuestion には常にスキップボタンとフリーテキスト入力ボックスが含まれるため、None または Other をオプションとして含めないでください。

フェーズ 1: ディスカバリー

目標: ユーザーが何を構築したいのか、そしてなぜなのかを理解する。

尋ねる（不明な点のみ。ユーザーの最初のリクエストが既に答えている場合はスキップ）：

• このプラグインは何をすべきか？どんな問題を解決するか？
• 誰がどのコンテキストで使用するか？
• 外部ツールやサービスと統合するか？
• 参考にできる同様のプラグインやワークフローがあるか？

理解を要約し、進む前に確認してください。

出力: プラグインの目的と範囲の明確な説明。

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

目標: プラグインが必要とするコンポーネントタイプを決定する。

ディスカバリー回答に基づいて、以下を決定します：

• スキル — Claude がオンデマンドで読み込むべき専門知識、またはユーザー主導のアクション が必要か？（ドメイン専門知識、参考スキーマ、ワークフローガイド、デプロイ/設定/分析/レビューアクション）
• MCP サーバー — 外部サービス統合が必要か？（データベース、API、SaaS ツール）
• エージェント (非一般的) — 自律的なマルチステップタスクがあるか？（検証、生成、分析）
• フック (稀) — 特定のイベントで自動的に何かが起こるべきか？（ポリシーの適用、コンテキストの読み込み、操作の検証）

コンポーネント計画表を提示します。作成しないと決定したコンポーネントタイプを含めます：

| コンポーネント | 個数 | 目的 |
|-----------|-------|---------|
| スキル    | 3     | X のドメイン知識、/do-thing、/check-thing |
| エージェント | 0 | 不要 |
| フック     | 1     | 書き込みを検証 |
| MCP       | 1     | サービス 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/ 内の詳細なコンテンツ。Frontmatter 説明は特定のトリガーフレーズを含む三人称である必要があります。スキル本文はユーザーへのメッセージではなく 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/）によって参照されるコンポーネントディレクトリが実際に存在し、期待されるフォーマットのファイルを含んでいる。コマンド/スキル/エージェント用 .md、フック用 .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 を作成してから、outputs フォルダにコピーしてください。outputs フォルダに直接書き込むとパーミッション問題により失敗する可能性があります。

命名: .plugin ファイルの名前には plugin.json のプラグイン名を使用します（例：名前が code-reviewer の場合、code-reviewer.plugin を出力します）。

.plugin ファイルはチャットでリッチプレビューとして表示され、ユーザーはファイルを参照してプラグインボタンを押すことで受け入れることができます。

ベストプラクティス

• 小さくスタート: コンポーネントの最小限の実行可能なセットで始めてください。1つの完成度の高いスキルを持つプラグインは、5つの半端なコンポーネントを持つプラグインより有用です。
• スキルのプログレッシブディスクロージャー: SKILL.md のコア知識、references/ の詳細な参考資料、examples/ の動作例。
• 明確なトリガーフレーズ: スキル説明は、ユーザーが言及する可能性がある特定のフレーズを含むべきです。エージェント説明には <example> ブロックを含めてください。
• スキルは Claude 用: スキル本文コンテンツは Claude が従うべき指示として記述し、ユーザーが読むドキュメントではありません。
• 命令型の文体: スキルで「config ファイルを解析してください」ではなく「config ファイルを解析する」などの動詞優先の指示を使用します。
• 移植性: プラグイン内パス参照には常に ${CLAUDE_PLUGIN_ROOT} を使用し、ハードコードされたパスは使用しません。
• セキュリティ: 認証情報には環境変数を使用し、リモートサーバーには HTTPS を使用し、ツールアクセスは最小権限にします。

追加リソース

• references/component-schemas.md — すべてのコンポーネントタイプ（スキル、エージェント、フック、MCP、レガシーコマンド、CONNECTORS.md）の詳細フォーマット仕様
• references/example-plugins.md — 異なる複雑性レベルでの 3 つの完全な例プラグイン構造