プラグインは、 組み込み または カスタム のスキル、ツール、エージェントを含めることができるインストール可能なパッケージです。 組み込みスキルはCopilotに付属しています。 カスタム スキルは作成者によって作成されます。 カスタム スキルをプラグインにパッケージ化すると、ユーザーはそれをインストールしてCopilotの機能を拡張できます。
Microsoft Copilot Cowork では、Teams アプリ、Copilot エージェント、Office アドインで使用されるのと同じ配布メカニズムである M365 アプリ パッケージによる拡張性がサポートされています。Cowork は次のように拡張できます:
- スキル: 財務分析、法務調査、人事ワークフローなどの新たな分野の専門知識を Cowork に身に付けさせる、プロンプトベースのワークフロー。
- コネクタ: Cowork が外部データソースや API にアクセスできるようにするリモートサーバー。
どちらも標準の Microsoft 365 アプリ パッケージにまとめてパッケージ化され、Microsoft 365 App Store を通じて配布されます。
Important
Microsoft Purview 情報バリア (IB) は現在、プラグインやスキルの管理と共有についてはサポートされていません。 IB が有効になっているテナントでは、埋め込み知識ファイルのアップロードはテナント レベルでブロックされます。 これにより、影響を受けるプラグインとスキルがアップロードまたは公開されなくなります。
Microsoft は、クロール、スクレイピング、ハーベスト、一括エクスポート、取り込み、またはその他の方法 (API、MCP サーバー、またはその他の方法) のいずれによっても、永続的なインデックス、ナレッジ グラフ (Microsoft Graph を含む)、または ISV コンテンツを含むデータベースを作成または維持することはありません。 Microsoftは、ユーザーのリアルタイム クエリに応答するために必要に応じて ISV コンテンツを一時的に処理する場合がありますが、そのセッションの期間を超えて ISV コンテンツは保持されません。 ISV の書面による要求に応じて、Microsoft は所有または管理する ISV コンテンツを 10 営業日以内に削除し、そのような削除を書面で証明します。 Microsoft Copilot と Microsoft Copilot Chat のエンタープライズ データ保護に関する詳細情報をご覧ください。
ビルドと発行<
プラグインの作成とパッケージ化は、レジストリパブリケーション、管理者の承認/割り当て、ユーザーインストール、およびサービスサインインとは異なります。
- Work IQ Dev Tools は、選択した対象向けにレジストリへ発行できます。
- Cowork の特定のユーザーとの共有には、管理者の承認は必要ありません。
- 組織全体の共有には管理者の承認が必要です。
- 直接共有は Marketplace オファーではありません。
プラグインの検出と管理を容易にするには、共有プラグイン レジストリを調べる必要があります。 プラグイン レジストリは、プラグインを 1 回公開し、ユーザーが検出し、サポートされているCopilotエクスペリエンスで利用できるようにする一般的なMicrosoft Copilot インフラストラクチャであり、管理者によって一元的に管理されます。 詳細については、 プラグイン ハブを参照してください。
Note
Cowork では、パッケージ化されたすべてのコンポーネントが機能するわけではありません。 既存のプラグインが自動的に移行されない場合があります。
Prerequisites
この一覧を使用して、Cowork プラグインがサポートするものと必要とするものを確認します。
-
Copilot Cowork 用のプラグインをビルドする
- Microsoft 365 Copilot ライセンス: Cowork ユーザーに必要です。
- サポートされている管理者ロール: MCP の承認とテナントの同意には 、AI 管理者 または グローバル管理者 を使用します。
-
開発ツール
- Work IQ Dev Tools: パッケージ化、検証、プロビジョニング、共有、および公開要求用。
- Microsoft 365 Agents Toolkit: エージェントとアプリの開発とパッケージ化用。
- プラグイン ビルダー (以前のエージェント ビルダー): 作成環境。確認時のロールアウト範囲。
- Cowork のアップロード: 完全な開発ワークフローではなく、サポートされているパッケージをインポートします。
-
有効なパッケージ形式: Microsoft 365 アプリ パッケージ形式を使用します (
agentSkills宣言とagentConnectors宣言を含むmanifest.json)。 - 必須スキーマ: 宣言型エージェント マニフェスト 1.9 の標準に従います。
-
公開ルート
- 直接共有 (Work IQ Dev Tools または
wiqd plugin share経由)。 - 組織によるアップロード (Microsoft 365 管理センター で、Agents>Tools>Registry>Upload を選択します)。
- Microsoft Marketplace
- 直接共有 (Work IQ Dev Tools または
-
ライセンスと同意
- ユーザーごとに Microsoft 365 Copilot ライセンスが必要です。
- MCP 登録およびサーバーにリンクされたプラグインには管理者の同意が必要です。
-
ガバナンスとアクセス
- 管理対象のプラグイン それらを見つけるには、Microsoft 365 管理センター と Microsoft Agent 365 で ツール を選択します。
- ポリシーと発行元カテゴリの制御。 それらを見つけるには、Agents>、Settings>、Agent and plugin access の順に選択します。
-
互換性: スキル形式の
agentskills.io業界標準に従います。
作成するもの
Cowork プラグインは、以下を含む.zipパッケージです。
my-extension.zip
├── manifest.json # M365 Unified App Manifest (v1.28)
├── color.png # 192×192 full-color app icon
├── outline.png # 32×32 outline icon
└── skills/ # Agent Skills (SKILL.md files)
├── skill-one/
│ ├── SKILL.md
│ └── references/ # Optional deep-dive docs
└── skill-two/
└── SKILL.md
スキルでは、Claude Code、Visual Studio Code Copilot、Gemini CLI、Cursor、JetBrains Junie、および 30 以上の他の AI ツールでサポートされているのと同じ形式の、Agent Skills のオープン標準を使用します。
出発点を選択する
wiqd CLI を使用してプラグインをビルドします。 CLI はパッケージを生成し、manifest.json とスキル フォルダーを同期した状態に保ちます。また、アップロード前にプラットフォーム独自の検証ルールを実行し、その後、結果をプロビジョニングして共有できるようにします。 CLI はプレビュー段階であるため、一般公開前にコマンドや生成される出力は変更される可能性があります。 生成されるものはすべてプレーンな Microsoft 365 アプリ パッケージであるため、ファイルを直接開いたり、編集したり、バージョン管理したりすることができます。
ツールをインストールできない場合、または独自のパッケージ化パイプラインを構築している場合にのみ、パッケージを手動でアセンブルしてください。 その場合は、この記事の パッケージ形式リファレンス が必要です。それは wiqd が生成する結果を正確に記述します。
| 開始ポイント | これをやってください | 最初のパッケージまでの時間 |
|---|---|---|
| ゼロから始める | wiqdでプラグインをビルド | 約10分 |
| 既存のClaude Codeプラグインがあります | 変換します | 約5分 |
| ツールをインストールできないか、独自のパッケージングをスクリプト化している | パッケージを手動で作成する | 約30分 |
wiqd でプラグインを構築する
wiqd CLI は、作成、機能の追加、検証、プロビジョニング、パッケージ化、共有といった、通常は手動で行うのと同じライフサイクルを実行します。 生成されるパッケージは、この記事の 検証規則 を既に満たしています。
手順 1: wiqd をインストールしてサインインする
Wiqd インストール ガイド (Windows、macOS、Linux を対象としている) に従って、wiqd CLI をインストールします。 次に、開発対象の Microsoft 365 テナントにサインインします。プロビジョニングと共有は両方ともテナントに対して作用するためです。
wiqd auth login --interactive
インストーラーは GitHub Copilot CLI プラグインも登録するため、同じライフサイクルを会話的に実行できます。 たとえば、Triage Helper という名前のスタンドアロン プラグインを作成する または 自分のプラグインを検証する。 と言うことができます。カンバセーション パスでは、このセクションと同じコマンドが実行されます。 パイプラインをスクリプト化する場合や、再現可能な非対話型オートメーションを実行する場合は、これらのコマンドを直接使用します。
ステップ 2: プラグインをスキャフォールディングし、機能を追加する
プラグイン コンテナーを作成し、必要な機能を任意の組み合わせで追加してください。
wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp
add skill は appPackage/skills/contract-analysis/SKILL.md をスキャフォールドし、agentSkills[] に登録します。
add connector は agentConnectors[] エントリを書き込みます。 どちらのコマンドも、書き込み前にプラットフォームの名前付けとサイズの上限を強制するため、フォルダー名の不一致や長さ超過の id がマニフェストに到達することはありません。
生成された SKILL.mdにスキル ロジックを記述してください。 フロントマター フィールド、プログレッシブ読み込みモデル、およびコンパニオン ファイルの制限は、「手順 1: 最初のスキルを作成する」 と 「手順 2: 参考資料を追加する (省略可能)」 で説明されているものと同じです。
Important
wiqd plugin create はパッケージを manifestVersion: "1.29" に固定しますが、この記事の手動で作成した例では 1.28 を使用しています。 コネクタでは、違いは重要です。 1.28 では mcpToolDescription が必要であり、それが指すファイルは ZIP 内になければなりません。 1.29 では、agentConnectors[] エントリは URL のみであり、mcpToolDescription は省略可能であるため、wiqd で生成されたパッケージがそのアップロード失敗に遭遇することはありません。 wiqd はまだコネクタ認証をスキャフォールドしません。サポートされている認証の種類の説明に従って直接構成します。
手順 3: 構築しながら検証する
パッケージを組み立ててアップロードが成功することを期待するのではなく、継続的に検証します。
wiqd plugin validate
wiqd plugin validate --mode deep
validate は、宣言型エージェントの対象範囲に対するオフラインの静的チェックです。 スキルのみまたはコネクタのみのプラグインは、確認する項目がないままパスしますが、これは予想されることです。これはビルド ループのチェックであり、完全なカバレッジではありません。
validate --mode deep は、まずプラグインをパッケージ化し、ビルドされた .zip を、アップロードで使用されるのと同じアプリ検証ライブラリに対して検証します。 そこで、ASKILLコードとコネクタルールが現れます。
手順 4: プロビジョニング、パッケージ化、共有
次の3つのコマンドを順番に実行してください。
wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com
share と provision の両方が依存する環境ファイルを書き込むため、最初に package を実行してください。
--scope users を使用して一覧に追加した相手と共有したり、--scope tenant を使用して組織内のすべてのユーザーと共有したりできます。 どちらの方法でも、プラグインは >>プラグイン の下の 自分と共有 に表示されます。 代わりに、Discover セクションに一覧表示するには、管理者がパッケージをアップロードします。 詳細については、「 手順 8: テナントに公開する」を参照してください。 作成した provision を削除するには、wiqd plugin delete --env local --yes を実行してください。
パブリック ストアの申請は、パートナー センターでは依然として手動のプロセスです。 詳しくは、「手順 9: 一般公開する」をご覧ください。
完全な公開方法と次の手順のガイダンスについては、プラグインの発行または共有とプラグインを使用可能にするを参照してください。
プラグインを別のホストに移動する
Claude Code、Cursor、またはその他のエージェントスキルホストでスキルを使用するには、フォルダーを手動でコピーするのではなく、プロジェクトをエクスポートしてください。
wiqd plugin export --format claude-plugin
export の既定値は --format open-plugin で、cursor-plugin も指定できます。 圧縮されていないディレクトリを <path>/export/<format> の下に書き込みます。
既存のプラグインをインポートする
スキルとMCPサーバーを備えたClaude Codeプラグインをすでに持っている場合は、2つの変換ルートがあります。 どのルートを選択するかは、プラグインの開発を続けるつもりなのか、それとも手持ちのものだけを出荷するつもりなのかによって決まります。
| ゴール | Use |
|---|---|
| Microsoft 365 でプラグインの開発、検証、およびリリースを続ける | wiqd plugin import |
既存の Claude プラグインから公開可能な.zipを今すぐ作成する |
変換スクリプト |
wiqd でインポート
wiqd plugin import は、Open Plugin、Claude プラグイン、または Cursor プラグインのソースを認識し、それを基に wiqd プラグイン プロジェクトを生成します。 インポートされたプラグインは、 wiqd plugin create で作成したのと同じライフサイクルに参加します。
wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms
--privacy-url と --terms-url はプラグインの最初のインポートでのみ必要です。 ソースが以前の wiqd plugin export からのものである場合、ラウンド トリップ メタデータには既にその情報が保持されています。
Important
インポートされたプロジェクトは、ライフサイクルの読み取り専用部分 (wiqd plugin validate、 show、 list) のみをサポートします。 まだパッケージ化、プロビジョニング、共有はできません。インポートでは、これらの手順に必要なローカル配置ファイルがスキャフォールドされないためです。 これは追跡対象の不具合です。 現在の状態については、wiqd CLI リファレンスを確認します。 今すぐ公開可能なパッケージが必要な場合は、変換スクリプトを使用してください。
変換スクリプトを使用して変換する
変換スクリプトは、Claudeプラグインを公開可能なM365パッケージに直接変換します。
CLI をインストールします (バージョン 1.1.12 以降が必要):
npm install -g @microsoft/m365agentstoolkit-cliバージョンを確認してください:
atk --versionプラグインをインポート:
atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \ --privacy-url https://contoso.com/privacy \ --terms-url https://contoso.com/terms
このコマンドは、プラグインの .claude-plugin/plugin.json(または .cursor-plugin/plugin.json)、.mcp.json、skills/ ディレクトリを読み取り、appPackage/manifest.json、スキル、生成されたアイコンを含む Agents Toolkit プロジェクトをスキャフォールディングします。
プラグイン マニフェストには同等のフィールドがなく、Microsoft 365 マニフェストには両方が必要なため、 --privacy-url と --terms-url を含める必要があります。
Note
atk import openpluginは、.mcp.jsonと共に、ドット プレフィックス付きのディレクトリ (.claude-plugin/plugin.json、.cursor-plugin/plugin.json、または.plugin/plugin.json) にあるプラグイン マニフェストを見つけます。
Agent Plugins 1.0.0 仕様では、マニフェストはトップレベルのplugin.jsonに、MCP 構成はmcp.jsonに位置します。 1.0.0 レイアウトに従ったプラグインをインポートするには、そのマニフェストを .plugin/plugin.json に移動し、mcp.json の名前を .mcp.json に変更してください。
結果をアップロード可能な .zipにパッケージ化してください。
cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
--output-package-file ./appPackage/build/appPackage.zip \
--output-folder ./appPackage/build
Note
atk import openplugin は、 devPreview マニフェストを生成します。 この記事の他の場所にあるマニフェストの例は、スキーマ v1.28 を対象としています。 v1.28 を必要とするチャネルを通じて公開する場合は、生成された$schema内のappPackage/manifest.jsonとmanifestVersionを更新します。
インポートされるもの
| プラグイン成果物 | M365 相当 | メモ |
|---|---|---|
.claude-plugin/plugin.json |
manifest.json |
名前、説明、開発者の各フィールドをマッピング済み; GUID は自動生成(決定論的 UUID v5) |
skills/*/SKILL.md |
agentSkills[] エントリ + skills/ フォルダー |
そのままコピー - 同じ形式 |
.mcp.json servers |
agentConnectors[] エントリ |
URL と認証の種類が自動検出されました |
color.png / outline.png |
パッケージ内のアイコン | 存在する場合は使用されます。存在しない場合はプレースホルダーが生成されます |
Important
.mcp.json からインポートされたコネクタごとに、生成されるauthorization.referenceIdは、プラグインとサーバー名から派生したプレースホルダーです。 発行する前に、実際の OAuth クライアント登録 ID に置き換えてください。 詳しくは、「 サポートされている認証の種類」をご覧ください。
変換されない項目
次の Claude プラグイン機能は、Microsoft 365 マニフェストではまだサポートされていません。
| Claudeプラグイン機能 | Status |
|---|---|
commands/(スラッシュコマンド) |
まだサポートされていません |
agents/ (サブエージェント) |
まだサポートされていません |
hooks/ (イベント ハンドラー) |
まだサポートされていません |
settings.json |
該当なし |
bin/ (実行可能ファイル) |
該当なし |
インポート オプション
| Option | Description |
|---|---|
--path、-p |
Required.
.claude-plugin/plugin.json、.cursor-plugin/plugin.json、または.plugin/plugin.json を含むプラグイン ディレクトリ |
--output、-o |
ターゲット プロジェクト フォルダー (既定値: ./<plugin-name>) |
--privacy-url |
developer.privacyUrl 生成されたマニフェスト用 |
--terms-url |
developer.termsOfUseUrl 生成されたマニフェスト用 |
--website-url |
developer.websiteUrl。
homepage にフォールバックし、その後 author.url にフォールバックします |
--app-id |
マニフェスト用に生成された確定的な UUID v5 を上書きする id |
--default-auth-type |
Auto(既定値)、None、OAuthPluginVault、または ApiKeyPluginVault |
認証タイプの自動検出:
| Source | 既定の認証の種類 | 理由 |
|---|---|---|
| 外部 HTTPS URL 一覧 | OAuthPluginVault |
ほとんどのリモート API には認証が必要です |
localhost および HTTPS 以外の URL |
None |
ローカル開発サーバー |
自動検出が設定と一致しない場合は、--default-auth-type を使用して上書きしてください。
プラグイン ディレクトリにエクスポートし直す
Agents Toolkit プロジェクトをプラグインディレクトリに戻すには、(たとえば、Claude Code プラグインと Cowork パッケージの同期を維持するために)atk export openpluginを使用します:
atk export openplugin --path ./my-plugin-project \
--output ./my-claude-plugin --manifest-kind claude-plugin
| Option | Description |
|---|---|
--path、-p |
Required.
appPackage/manifest.json を含む Agents Toolkit プロジェクト フォルダー |
--output、-o |
宛先プラグイン ディレクトリ (既定値: ./<plugin-name>-openplugin) |
--manifest-kind |
open-plugin(既定、.plugin/plugin.json に書き込む)、claude-plugin、または cursor-plugin |
[エクスポート] では、生成されたx-microsoft-365-agents-toolkitにplugin.json ブロックが書き込まれます。 このブロックには、マニフェスト id、開発者 URL、およびコネクタ設定が含まれるため、そのため、後で atk import openplugin を往復しても、--privacy-url や --terms-url を再度必要としません。
Note
x-microsoft-365-agents-toolkit ブロックは Agents Toolkit に固有であり、既定のopen-pluginの種類ではマニフェストが .plugin/plugin.json に書き込まれます。
エージェント プラグイン 1.0.0 では、最上位の plugin.json が使用され、クライアント固有のデータが逆ドメイン名前空間を持つ extensions キーの下に格納されるため、他のクライアントはこのブロックを無視して処理を行います。 ターゲットが Claude Code または Cursor の場合は、--manifest-kind claude-plugin または cursor-plugin を使用します。
レガシ: PowerShell 変換スクリプト
プラグイン インポートがサポートされる前 atk、変換には Windows 専用の PowerShell スクリプトが使用されていましたが、これは 変換スクリプトとして引き続き利用可能です。
.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output
atk import openplugin を代わりに使用します。 クロスプラットフォームであり、Cursor および Claude Code のソースをサポートし、プラグインディレクトリに戻してエクスポートすることができます。
パッケージを手作業で組み立てる
このセクションはパッケージ形式のリファレンスです: wiqd でプラグインを構築する で生成される内容をフィールドごとに正確に説明します。 ツールをインストールできない場合や、独自のパッケージ化パイプラインを構築している場合は、最初から最後まで実行できます。 生成されたパッケージを理解またはデバッグする必要がある場合に、リファレンスとして使用します。
手順 1: 最初のスキルを作成する
スキルは、 SKILL.md ファイルを含むフォルダーです。 次のフォルダー構造を作成してください:
my-extension/
└── skills/
└── contract-analysis/
└── SKILL.md
YAML フロントマターと Markdown 本文を使用して SKILL.md を記述します。
---
name: contract-analysis
description: |
Analyzes contracts for key terms, risks, and obligations.
Use when user asks to "review this contract", "find the liability clause",
"summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
author: Contoso Legal Tech
version: "1.0"
---
# Contract Analysis
## What This Skill Does
Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions
## Workflow
1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations
## Output Format
Present findings in a structured table:
| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |
SKILL.md frontmatter フィールド
必須フィールド:
| フィールド | Constraints | Description |
|---|---|---|
name |
1~64文字、kebab-case | スキル識別子 - フォルダー名と正確に一致する必要があります |
description |
1~1024文字 | このスキルを使うタイミング - トリガーフレーズを含めてください |
Important
- フォルダー名は、フロントマターの
nameフィールドと一致する必要があります。 この不一致は、スキルの実行失敗の最も一般的な原因です。 - プラグインの一覧
descriptionフィールドには、サブスクリプションを購入するためにユーザーを外部マーケットプレースに誘導する行動喚起を含めることはできません。
| フォルダー パス |
name field |
有効? | なぜでしょうか |
|---|---|---|---|
skills/contract-analysis/SKILL.md |
contract-analysis |
Yes | フォルダー名が一致 |
skills/contract-analysis/SKILL.md |
ContractAnalysis |
No | 名前はフォルダ名に合わせるのではなく、PascalCase を使用します |
skills/my-skill/SKILL.md |
contract-analysis |
No | フォルダーは my-skill ですが、名前は contract-analysis |
名前付け規則 (kebab-case): 小文字の英数字とハイフンのみを使用します。 連続するハイフンは使用しないでください。また、先頭または末尾のハイフンは使用しないでください。
| 例 | 有効? | Issue |
|---|---|---|
bond-relative-value |
Yes | ハイフン付きの小文字 |
fx-carry-trade |
Yes | ハイフン付きの小文字 |
email |
Yes | 1語で、ハイフン不要 |
Bond_Relative_Value |
No | アンダースコアと大文字 |
--my-skill-- |
No | 先頭と末尾のハイフン |
my--skill |
No | 連続するハイフン |
手順 2: 参考資料を追加する (オプション)
複雑なスキルの場合は、メイン SKILL.md を無駄のない状態に保ち、詳細なコンテンツをサブディレクトリに移動します。 これらの追加ファイルは コンパニオン ファイルです。 スキルは必要に応じてそれらをロードします。
skills/
└── contract-analysis/
├── SKILL.md # Core workflow (~1,500-2,000 words ideal)
├── references/ # Deep-dive docs loaded on demand
│ ├── clause-taxonomy.md
│ └── risk-scoring.md
└── scripts/ # Executable utilities
└── extract-clauses.py
コンパニオン ファイルの制限
各スキルには、最大 20 個のコンパニオン ファイル ( SKILL.md 以外のファイル) を含めることができます。 スキルごとに次の制限が適用されます。
| Limit | Value |
|---|---|
| コンパニオン ファイルの最大数 | 20 |
| コンパニオン ファイルあたりの最大サイズ | 5 メガバイト |
| コンパニオンの最大合計サイズ | 10MB |
| ダウンロード タイムアウト (すべてのコンパニオン) | 15 秒 |
コンパニオン ファイルのルール
コンパニオン ファイル パスは次の規則に従う必要があります。
- 相対パスのみ使用します (絶対パスは使用しません)。
- パス トラバーサルなし(
..セグメント)。 - ファイル名にバックスラッシュまたは NULL バイトを使用できません。
- 隠しファイルなし (名前が
.で始まるファイル) - Windows 予約名 (
CON、PRN、AUX、NUL、COM1–COM9、LPT1–LPT9) はありません。 - ファイル
SKILL.md自体はコンパニオン ファイルとしてカウントされません。 - ファイル名には、安全な文字のみ使用する必要があります: 英数字、ハイフン、アンダースコア、ドット、スペース、
!。
コンテキスト ウィンドウを効率的に保つために、システムはスキルを 3 つのレイヤーに読み込みます。
| レイヤー | 読み込み時 | ターゲット サイズ |
|---|---|---|
Frontmatter (name + description) |
常時 - 起動時 | ~100 トークン |
SKILL.md 本文 |
スキルがトリガーされるとき | 5,000 トークン未満 (1,500~2,000語) |
参考文献 (references/) |
エージェントの要求に応じて | Unlimited |
スクリプト (scripts/) |
実行済み、コンテキストに読み込まれていません | N/A |
エージェントがサブディレクトリが存在することを認識できるように、 SKILL.md でサブディレクトリを明示的に参照します。
## Additional Resources
- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility
手順 3: コネクタを追加する(任意)
拡張機能が外部データにアクセスする必要がある場合は、リモート MCP サーバーを追加してください。 このステップはオプションです。 スキル専用パッケージは、プロンプトベースのワークフローに適しています。
Tip
サーバーがクライアントごとにツールの表示を制御している場合、または受信トラフィックを属性付けしている場合は、Cowork が提示するクライアント ID の詳細については、サーバーへの Cowork トラフィックの識別 に関するページを参照してください。
Note
カスタム プラグインは、モバイル上の Cowork ではサポートされていません。
コネクタの要件
| 要件 | Details |
|---|---|
| Transport | Streamable HTTP (HTTPS が必要、TLS 1.2+) |
| Protocol | JSON-RPC 2.0 メッセージ形式 |
| ツールの発見 | 動的ディスカバリーをサポート tools/list(推奨) |
| ツールの実行 | 呼び出し向けのサポート tools/call |
| Availability | ストア公開アプリには、99.9% の稼働時間 SLA を推奨します |
| 応答時間 | ツール呼び出しごとに 30 秒未満 |
ツール設計ガイドライン
- アクションごとに1つのツール 小さな API(15 操作未満): 、、
-
検索と実行を大規模な API 向けに (50 以上の操作):
search_actions+execute_action -
わかりやすい名前:
get_bond_priceではなくgetData - 充実した入力スキーマ: 各パラメーターに説明を含めます。これはエージェントが参照する内容です
- 構造化された出力: エージェントがユーザー向けに整形できる JSON を返します
-
ファイル入力: ユーザーのワークスペースからファイルを受け入れるには、
contentEncoding: base64を使用してパラメーターを宣言します。 詳細については、「Cowork ワークスペースからファイルを受け入れる」を参照してください。
コネクタのツールについて説明する (mcpToolDescription)
remoteMcpServer コネクタには、オプションで mcpToolDescription オブジェクトを含めることができます。 指定された場合、入れ子になった file プロパティは、ご使用の .zip 内にパッケージ化し、パッケージ ルートからの相対パスで参照するツール記述 JSON ファイルを指し示します。 Cowork は MCP サーバーからツールを動的に検出し、このファイルが存在する場合でも使用しません。
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp",
"mcpToolDescription": {
"file": "./tools/contoso-legal-tools.json"
},
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
}
mcpToolDescription を含める場合、参照ファイル (tools/contoso-legal-tools.json など) はコネクタが公開するツールについて説明し、そのファイルは ZIP パッケージ内に存在する必要があります。 プラグインをパッケージ化するときに、manifest.json フォルダーおよび skills/ フォルダーと一緒に含めます。
Tip
この要件は、マニフェスト バージョン 1.28 に適用されます。
wiqd plugin create が生成するパッケージはターゲット 1.29 向けです。agentConnectors[] エントリは URL のみであり、mcpToolDescription は省略可能であり、ツール記述ファイルがないため、入れ忘れる心配がありません。
サポートされている認証の種類
| 認証の種類 | いつ使用するか | ユーザー エクスペリエンス |
|---|---|---|
None |
パブリックまたは匿名の API、内部サービス | 透過接続 - 認証プロンプトなし |
OAuthPluginVault |
OAuth 2.0 API(本番環境向け(推奨)) | ユーザーは OAuth 同意を 1 回完了します |
ApiKeyPluginVault |
API キー ベースのサービス | ユーザーはキーを 1 回指定します |
Note
- API キー認証は、Cowork ではまだサポートされていません。
- MCP サーバーで API キーが必要な場合は、代わりに
OAuthPluginVaultまたは 動的クライアント登録 を使用するか、Noneを受け入れるエンドポイントを公開してください。
Entra で保護された MCP エンドポイントを介して API キーで保護されたサービスに Cowork を接続する参照パターンについては、「 基幹業務 API のプラグインを構築する」を参照してください。
OAuthPluginVaultおよびApiKeyPluginVaultの場合、referenceIdは Microsoft Enterprise トークン ストアに格納されている資格情報を指します。シークレットがマニフェストやスキル ファイルに表示されることはありません。
referenceId値は、OAuth クライアントを Agents Toolkit に登録するときに作成する OAuth クライアント登録 ID です。
Important
OAuth クライアントを登録するときは、プラグインがテナント間で機能するように、組織による利用対象を Any Microsoft 365 Organization に設定します。
MCP 認証
認証に OAuth または ApiKey を使用するには、セットアップと構成の詳細については、「Microsoft 365 Copilot のエージェントで MCP および API プラグインの認証を構成する」を参照してください。
動的クライアント登録
MCP サーバーが動的クライアント登録 (DCR) をサポートしている場合は、コネクタ定義からauthentication設定を省略でき、Cowork はプラグインに代わって OAuth クライアントを自動的に作成します。
Note
authentication構成の省略は、Coworkでのみサポートされます。 これは Copilot Chat ではサポートされていません。 プラグインが Copilot Chat でも動作する必要がある場合は、OAuthPluginVaultで説明されているように、認証を構成します。
authorization オブジェクト全体を省略できます。 MCP サーバー URL を構成すると、Cowork が OAuth クライアントを管理します。
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp"
}
手順 4: マニフェストを作成する
パッケージのルートに manifest.json を作成します。 この例では、マニフェスト バージョン 1.28 を使用します。代わりにwiqd plugin create1.29 をピン留めします。ここで、コネクタのエントリは URL のみです。
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
"manifestVersion": "1.28",
"version": "1.0.0",
"id": "YOUR-GUID-HERE",
"developer": {
"name": "Contoso Legal Tech",
"websiteUrl": "https://contoso.com",
"privacyUrl": "https://contoso.com/privacy",
"termsOfUseUrl": "https://contoso.com/terms"
},
"name": {
"short": "Contoso Legal Tools",
"full": "Contoso Legal Tools for Copilot Cowork"
},
"description": {
"short": "Contract analysis, clause extraction, and legal research",
"full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"accentColor": "#2B579A",
"agentSkills": [
{ "folder": "./skills/contract-analysis" }
]
}
コネクタを追加するには、agentConnectorsを含めます。
{
"agentConnectors": [
{
"id": "contoso-legal-api",
"displayName": "Contoso Legal Database",
"description": "Access to case law, statutes, and regulatory databases",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://api.contoso.com/legal/mcp",
"mcpToolDescription": {
"file": "./tools/contoso-legal-tools.json"
},
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
}
}
}
]
}
コネクタの構成では、referenceId は OAuth 登録 ID であるべきです。
mcpToolDescription を含める場合、そのfileは、ZIP パッケージに含まれるツール記述 JSON ファイルを指す必要があります。
Important
v1.28 のマニフェスト スキーマは厳密です。ルートで additionalProperties: false を設定しているため、スキーマで定義されていないフィールドは拒否されます。 標準の Teams アプリ マニフェストで有効なフィールド ( packageName など) を使用すると、Property 'packageName' has not been defined and the schema does not allow additional properties. のようなエラーが表示され、アップロードは失敗します。ここに示すフィールドのみを含めてください。
手順 5: アイコンを追加する
2 つの PNG アイコンを作成します。
| Icon | Size | Purpose |
|---|---|---|
color.png |
192×192 ピクセル | ストアとアプリの一覧に表示されるフルカラー アプリ アイコン |
outline.png |
32×32 ピクセル | コンパクト ビュー用の単色アウトライン アイコン |
アイコンがまだない場合は、atk import openplugin は単色のプレースホルダーを生成します。 ストアへの提出前に置き換えてください。
手順 6: パッケージ
すべてのコンテンツをルート階層に配置した ZIP ファイルを作成します。 (wiqd plugin package では、wiqd plugin provision後にこれと同じ構造が生成されます)。
contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│ └── contoso-legal-tools.json # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
└── contract-analysis/
├── SKILL.md
└── references/
└── clause-taxonomy.md
コネクタに mcpToolDescription が含まれている場合は、mcpToolDescription が参照するツール説明 JSON ファイルを含めます。 スキル専用パッケージを含め、 mcpToolDescriptionを使用しないパッケージには、 tools/ フォルダーは不要です。
Windows (PowerShell):
Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip
macOS/Linux:
zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/
Microsoft 365 Agents Toolkit の使用
atk package --manifest-file ./appPackage/manifest.json \
--output-package-file ./appPackage/build/appPackage.zip \
--output-folder ./appPackage/build
手順 7: テスト
アプリをテストするには、Teams にアプリをアップロード で説明されているように、アプリ パッケージを Teams にアップロードします。
wiqd を使用してプラグインをビルドした場合は、代わりに wiqd plugin provision を実行します。これにより、プラグインがテナントに自動的に登録されます。 手動で組み立てたパッケージを個人でテストする場合は、Microsoft 365 Agents Toolkit コマンド ライン インターフェイスを使用してアプリをサイドロードします。
@microsoft/m365agentstoolkit-cliからnpmをインストールします。npm install -g @microsoft/m365agentstoolkit-cli次を実行してインストールを確認します:
atk --versionMicrosoft 365 職場または学校アカウントで認証します:
atk auth login職場アカウントにサインインして、エージェント パッケージをインストールします。 ファイル パスをお使いの ZIP パッケージの場所に置き換えてください。
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personalインストールが成功すると、アカウント用の
TitleIdとAppIdを含む出力が返されます。後で更新またはアンインストールするときに使用するために、これらの ID を保存してください。
詳細については、Microsoft 365 Agents Toolkit コマンド ライン インターフェイス をご覧ください。
手順 8: テナントに公開する
管理センターでパッケージをアップロードして、[Discover] セクションにプラグインを一覧表示します。組織内の誰もがプラグインを見つけることができます。
- M365 管理センターを開き>アプリの管理>カスタム アプリをアップロードします。
- 省略記号ボタン (...) を選択し、>エージェントの追加。
-
.zipパッケージをアップロードしてください。 - Cowork>ソース & スキル>プラグインを開く。 プラグインが Discover セクションに表示されます。
wiqd plugin shareは、プラグインをShared with meに配置し、Discoverには配置しません。 これは、テストおよび特定のユーザーへのターゲットを絞ったロールアウトに使用します。 管理センターのアップロードは、プラグインを見つけられるようにするために一覧表示するものです。
手順 9: 一般に公開する
一般配布を目的としたプラグインの場合は、パートナー センター経由でプラグインを Microsoft 365 App Store に提出してください。 詳細については、「Microsoft 365 Copilot 用のエージェントの発行」を参照してください。
ローカルの MCP サーバーに対してコネクタをテストする
コネクタには HTTPS 接続 mcpServerUrlが必要です。 マシンで実行されているサーバーをテストするには、パブリック HTTPS URL 経由でサーバーを公開する必要があります。
Dev tunnels は、TLS を終了するリレーを提供します。
devtunnel port create <tunnel> -p <port> --protocol http
Important
--protocol http ではなく、https を使用してください。
--protocol フラグは、パブリック トンネル URL ではなく、トンネルの転送先のローカル サービスを記述します。 ほとんどのローカル MCP サーバーはプレーンな HTTP を使用するため、サーバーが HTTP を提供しているときに --protocol https を設定すると、トンネルを通過するすべての要求で 502 エラーが返されます。 リレーは TLS 終端を行い、このフラグに関係なく HTTPS 経由でパブリック URL を提供します。
Troubleshooting
| 症状: | 原因 | 修正 |
|---|---|---|
トンネリングされたすべての要求は 502 を返し、ローカル サーバーは HTTP で通信します |
devtunnel port create は --protocol https で実行されました |
--protocol http でポートを再作成 |
ローカル サーバーが実行されていても、トンネリングされた要求によって macOS で 502 が返される |
サーバーは 0.0.0.0 (IPv4 のみ) にバインドされていますが、トンネルは localhost に接続しようとし、localhost は最初に ::1 (IPv6) に解決されます |
IPv4 接続と IPv6 接続の両方を受け入れるようにサーバーを :: にバインドする |
アップロードに失敗する Property '<field>' has not been defined and the schema does not allow additional properties |
マニフェストには、v1.28 スキーマでは許可されていないフィールドが含まれています (たとえば、packageName) |
フィールドを削除します。v1.28 スキーマでは additionalProperties: false を使用します |
パッケージ パターン
拡張機能に合ったパターンを選択します。
スキルのみ (コネクタなし)
プロンプトベースのワークフロー、ドキュメント分析、文書作成支援に最適です。
my-skills-pack.zip
├── manifest.json # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
├── skill-one/SKILL.md
└── skill-two/SKILL.md
スキル + リモート コネクタ
データ分析、API 統合、エンタープライズ システムに最適です。
my-data-skills.zip
├── manifest.json # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/ # Tool-description file(s) for mcpToolDescription (optional)
│ └── my-connector.json
└── skills/
├── analysis-workflow/SKILL.md
└── reporting-workflow/SKILL.md
コネクタのみ (カスタム スキルなし)
Cowork の組み込みスキルで既に使用できるデータ ソースには、このオプションを使用します。
my-connector.zip
├── manifest.json # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/ # Tool-description file(s) for mcpToolDescription (optional)
└── my-connector.json
インポートされた Claude Code または Cursor プラグイン
このオプションは、Coworkを対象とする既存のClaudeエコシステムプラグインに使用します。 Microsoft 365 でプラグインの開発を続けるには、プラグインをインポートしてください。
wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms
現在のプラグインから公開可能な .zip を生成するには、変換スクリプトを使用してください。
atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
--privacy-url https://contoso.com/privacy \
--terms-url https://contoso.com/terms
スキル作成のベストプラクティス
次のガイドラインに従って、確実に動作し、一貫した結果を生み出すスキルを作成してください。
効果的な説明文を書く
description フィールドは、エージェントがスキルをアクティブ化するタイミングを決定します。 具体的に:
# Good-specific trigger phrases, concrete scenarios
description: |
Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
Use when user asks to "analyze bond spreads", "compare bonds",
"rich-cheap analysis", "relative value", or "Z-spread calculation".
# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.
効果的なワークフローを作成する
- 説明は具体的にします。 トリガー フレーズを含める: "ユーザーが要求したときに..."この説明に基づいて、エージェントは有効化するスキルを判断します。
- ワークフローとして構成する。 手順に番号を付けます。 各ステップは、具体的なアクション (ファイルの読み取り、ツールの呼び出し、出力の生成) にマップする必要があります。
- 出力形式を定義します。 ユーザーが期待できる表、リスト、またはドキュメントの構造を正確に表示します。 この定義により、一貫性が大幅に向上します。
-
名前による参照ツール。 スキルがコネクタ ツールに依存している場合は、ツール名を明記します: "
search_case_lawツールを使用して..." -
メインの SKILL.md を無駄にし続けます。 詳細な参照資料を
references/サブディレクトリに移動します。 スキルボディは百科事典ではなく、ワークフローであるべきです。
一般的な間違いを避ける
-
SKILL.mdファイルにシークレットを埋め込むことはありません。 認証用の API 資格情報でagentConnectorsを使用します。 - 組み込みスキルを重複して作成しないでください。 ビルドする前に組み込みのスキル リストを確認してください。
- スキルを広くしすぎないでください。 「法的文書ですべてを行う」は、「契約分析」「条項抽出」「法的調査」の特定のスキルよりも劣ります。
- ファイル パスやシステム コマンドをハードコーディングしないでください。 スキルは、環境間で移植可能である必要があります。
-
すべてを SKILL.md に入れないでください。 本文が ~3,000 語を超える場合は、詳細なコンテンツを
references/に移動してください。
検証規則
パッケージを送信すると、プラットフォームによって複数のレベルで検証が行われます。 拒否されないように、提出前にこれらのエラーを修正してください。
アップロード時ではなくビルド時にそれらをキャッチするには、 wiqd plugin validate --mode deep を実行します。 このコマンドはプラグインをパッケージ化し、これらの同じルールをローカルで実行します。 詳細については、「手順 3: ビルド時に検証する」を参照してください。
マニフェストレベルの検証
| Code | ルール | Severity |
|---|---|---|
| ASKILL-M001 |
folder は、各 agentSkills エントリに必要です |
Error |
| ASKILL-M002 |
agentSkills 配列には最大 20 個の項目を含めることができます |
Error |
| ASKILL-M003 |
folder パスには最大 256 文字を指定できます |
Error |
パッケージ レベルの検証
| Code | ルール | 一般的な対処法 | Severity |
|---|---|---|---|
| ASKILL-P001 | マニフェストで参照されているフォルダーが ZIP に存在する | ZIP 構造を確認する | Error |
| ASKILL-P002 | フォルダーには SKILL.md ファイルが含まれています |
不足している SKILL.md の追加 |
Error |
| ASKILL-P003 |
SKILL.md には、--- 区切り記号の間に有効な YAML フロントマッターがある |
YAML 構文を修正する | Error |
| ASKILL-P004 | Frontmatter には name フィールドが含まれます |
フロントマターの先頭に name: を追加する |
Error |
| ASKILL-P005 | Frontmatter には description フィールドが含まれます |
フロントマターの先頭に description: を追加する |
Error |
| ASKILL-P006 |
name フォルダー名 (最後のパス セグメント) と一致します |
フォルダー名を変更するか、修正する name: |
Error |
| ASKILL-P007 |
name は kebab-case です |
MySkill や my_skill ではなく my-skill を使用してください |
Error |
| ASKILL-P008 | 配列に重複する folder 値はありません |
重複を削除する | Error |
コネクタの検証
| ルール | Severity |
|---|---|
各コネクタには id と displayName が必要です |
Error |
すべてのコネクタ id 値は、マニフェスト内で一意である必要があります |
Error |
plugin または remoteMcpServer のどちらか 1 つのみ |
Error |
mcpServerUrl は有効な HTTPS URL である必要があります |
Error |
mcpToolDescriptionが存在する場合は、そのfileが ZIP に存在する必要があります |
Error |
authorization.referenceId 型が None でない限り必須 |
Error |
authorization.referenceId 型が 〘の場合は存在しない None |
Error |
コンパニオン ファイルの検証
ポータルでは、アップロード時および同期時にコンパニオン ファイル ( SKILL.mdと共に参照資料、スクリプト、その他のファイル) を検証します。
| ルール | Severity |
|---|---|
スキルごとにコンパニオン ファイルは最大 20 個までです ( SKILL.md を除く) |
Error |
| 各コンパニオン ファイルは 5 MB 以下である必要があります | Error |
| コンパニオン ファイルの合計は、スキルごとに 10 MB 以下である必要があります | Error |
| ファイル パスは相対パスである必要があります (絶対パスは使用できません) | Error |
パストラバーサルセグメントはありません (..) |
Error |
| ファイル名にバックスラッシュまたは null バイトを含めないこと | Error |
隠しファイル ( . で始まる名前) |
Error |
Windows の予約名 (CON、 PRN、 AUX、 NUL、 COM1–COM9、 LPT1–LPT9) はありません |
Error |
ファイル名には、使用できる安全な文字 (英数字、ハイフン、アンダースコア、ドット、スペース、!) のみを使用する必要があります |
Error |
クロスプラットフォーム互換性
スキルはAgent Skills Open Standardを採用しています。 同じ SKILL.md ファイルが複数の AI ツールで動作します。
| Platform | Compatibility |
|---|---|
| クロード符号 | 完全に同じ SKILL.md 形式 |
| Claude.aiプロジェクト | フルスキルはプロジェクトファイルとしてアップロードできます |
| VS Code/GitHub Copilot | エージェント モードでサポートされている Full-Agent スキル |
| Gemini CLI | Full-Agent スキルをサポート |
| JetBrains Junie | Full-Agent スキルをサポート |
| OpenAIコデックス | Full-Agent スキルをサポート |
| Cursor | Full-Agent スキルをサポート |
Claude Code と Copilot Cowork の両方のスキルを開発している場合は、wiqd を使用してプラグインを作成してください。 次に、wiqd plugin export --format claude-pluginを実行してClaude コード レイアウトを生成します。 Claude Codeのプラグイン構造(スーパーセット)から始めたい場合、レイアウトは次のようになります。
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Claude plugin manifest
├── skills/
│ ├── skill-one/
│ │ ├── SKILL.md # Works in both Claude Code AND M365
│ │ └── references/
│ └── skill-two/
│ └── SKILL.md
└── .mcp.json # MCP server config (optional)
Microsoft 365 App Store に発行する準備ができたら、wiqd plugin importまたは変換スクリプトを使用して、Microsoft 365 に取り込みます。
atk import openplugin --path ./my-plugin --output ./my-plugin-project \
--privacy-url https://contoso.com/privacy \
--terms-url https://contoso.com/terms
MCP のアノテーションと確認の管理
Copilot Cowork は、サーバーが annotations から返すツール上の標準 MCP tools/list オブジェクトを読み取り、それを使用して、ツールの呼び出しにユーザーによる確認が必要かどうか、およびプロンプトに表示するラベルを決定します。
[使用できるフィールド]
| フィールド | タイプ | Effect |
|---|---|---|
readOnlyHint |
bool |
false: ツールを実行する前に確認が必要です。 |
destructiveHint |
bool |
true: ツールを実行する前に確認が必要です。 |
title |
文字列 | 確認ダイアログに表示される人が判読できるラベル。 未設定の場合は、ツール名にフォールバックします。 |
確認ルール
readOnlyHint == falseまたはdestructiveHint == trueの場合は確認が必要です。
すべてのツールには安全注釈が指定されている必要があります。 注釈のないツールは破壊的なものとして扱われ、確認が必要です。 詳細については、 MCP スキーマ リファレンスをご覧ください。
MCP の例
フレンドリなラベルが付いた破壊的な操作:
{
"name": "send_email",
"description": "Send an email message.",
"annotations": {
"title": "Send Email",
"destructiveHint": true
},
"inputSchema": { ... }
}
自動実行されるセーフ リード:
{
"name": "search_docs",
"annotations": {
"title": "Search Documents",
"readOnlyHint": true
}
}
現在利用可能なもの
- Microsoft ツール (Graph、Dataverse など) は、注釈に関係なく、Cowork の組み込みポリシーによってアクセス制御されます。
- Microsoft MCP 以外のサーバーについては、注釈駆動型の確認が段階的に展開されています。 ここでヒントを設定しておくと、将来の変更にも対応でき、開発者が変更することなく、ロールアウトが拡大するにつれて確認プロンプトが表示されます。
Cowork ワークスペースからファイルを受け入れる
コネクタ ツールは、ユーザーのCoworkセッション内のファイル(ユーザーが添付したドキュメント、Cowork が保存したメールの添付ファイル、または以前の手順で生成されたファイル)を入力として受け取れます。 標準の JSON スキーマ キーワード (keyword) contentEncoding: base64でパラメーターを宣言し、残りは Cowork が処理します。 Microsoft 固有のスキーマ拡張機能は必要なく、サーバーの API サーフェイスは変更されません。
Cowork はワークスペース ファイルを解決し、サーバーを呼び出す前に base64 エンコードするため、ファイル バイトがエージェントのコンテキストに入ることはありません。 エージェントは、ワークスペース ファイル パスのみを参照して出力します。
Note
ファイル自体を base64 でエンコードして、ツール呼び出しに BLOB を貼り付けるようにエージェントに指示しないでください。 このアプローチでは、ファイル全体がモデルのコンテキストに読み込まれ、モデルが blob を正確に再現することに依存します。 小さなテストファイルでは動作するようで、実際のテストファイルでは失敗します。
ファイル パラメーターの宣言
contentEncoding: base64 を持つ文字列プロパティは、ファイル入力として認識されます。
{
"name": "analyze_contract",
"description": "Extract key terms from a contract document.",
"annotations": {
"title": "Analyze Contract",
"readOnlyHint": true
},
"inputSchema": {
"type": "object",
"properties": {
"document": {
"type": "string",
"contentEncoding": "base64",
"description": "The contract file to analyze."
},
"jurisdiction": {
"type": "string",
"description": "Two-letter country code governing the contract."
}
},
"required": ["document"]
}
}
複数のファイルを受け入れるツールの場合、このような文字列の配列も認識されます。
"attachments": {
"type": "array",
"items": { "type": "string", "contentEncoding": "base64" },
"description": "Receipt images to attach to the expense line."
}
エージェントに表示される内容
inputSchema.properties の最上位レベルで宣言されたファイル パラメーターの場合、Cowork は、モデル向けスキーマ内の 1 つのdirect_attachment_file_paths配列に置き換えます。これは、Cowork の組み込みツールで使用されるのと同じパラメーターであるため、エージェントはその設定方法を既に把握しています。 上記のスキーマは、次のようにエージェントに表示されます。
{
"type": "object",
"properties": {
"direct_attachment_file_paths": {
"type": "array",
"items": { "type": "string" },
"description": "Workspace file paths to attach."
},
"jurisdiction": { "type": "string" }
}
}
ツールで複数の最上位ファイル パラメータを宣言している場合、すべてのパラメーターがその 1 つの direct_attachment_file_paths 配列にまとめられます。 呼び出し時に、Cowork は解決されたファイルを宣言順に元のパラメーター名に割り戻します。
ネストされたファイル パラメーター
エージェントは、オブジェクトまたはオブジェクトの配列内にネストされたファイル パラメーターをサポートします。 エージェントはこのパラメーターを別の方法で処理します。パラメータを折りたたむのではなく、そのその場で元の位置にあるパス文字列に書き換えます。 この方法では、ファイルとその兄弟フィールド間の関連付けが保持されます。 たとえば、経費明細行ごとに 1 つの領収書を取得します。
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number" },
"receipt": { "type": "string", "contentEncoding": "base64" }
}
}
}
エージェントは、line_items[].receiptにワークスペース パスを設定し、Cowork は呼び出しを転送する前に、各パスをその場でbase64コンテンツに置き換えます。
入れ子は、inputSchema のトップレベル配下から 4 階層までトラバースされます。
$ref ポインターはたどられません。$refの後ろではなく、ファイル パラメーターをインラインで定義します。
サーバーが受け取る内容
サーバーは、base64 エンコードされたコンテンツが設定された元のパラメーター名を含む通常の tools/call を受け取ります。
{
"method": "tools/call",
"params": {
"name": "analyze_contract",
"arguments": {
"document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
"jurisdiction": "US"
}
}
}
エージェントがパスベースのインターフェイスを使用したことをサーバーは認識する必要はなく、 contentEncoding: base64 パラメーターを宣言しないツールも影響を受けません。
Limits
| Limit | Value |
|---|---|
| ツール呼び出しあたりのファイル数 | 8 |
| ファイルごとのサイズ | 150 MiB |
| ツール呼び出しごとの合計サイズ | 150 MiB |
| ツールごとの配列ファイル パラメーター | 1 (任意の数のスカラー ファイル パラメーターと組み合わせる) |
| 最大入れ子の深さ | 最上位から 4 レベル下 inputSchema |
ファイル数またはサイズの上限を超える呼び出しは、ツール エラーで失敗し、サーバーに到達しません。 150MiB の上限を念頭に置いて、API とそのタイムアウトのサイズを設定します。base64 は、ペイロードを生ファイルサイズより約 3 分の 1 大きくし、エンコードされたコンテンツは JSON-RPC 要求本文で送信されます。
Recommendations
- 人間の読者向けにパラメータを記述します。 エージェントは、説明を使用して、どのファイルがどのパラメーターに属するかを判断します。 たとえば、
"The signed contract PDF to analyze"は"file"よりもうまく機能します。 - パラメーターの説明で受け入れる形式を指定します。 Cowork は、ユーザーがアタッチしたものをすべてそのまま渡します。 そちら側でコンテンツ タイプを検証し、使用できない場合はクリア ツール エラーを返します。
- 注釈を設定。 通常、ファイルを受け取って操作するツールは読み取り専用ではないため、確認を求めます。 MCP の注釈と確認の管理に関する詳細情報。
- ファイル パラメーターはインラインのままにします。
$refの後ろにあるパラメーター、または 4 レベルより深く入れ子になったパラメーターは書き換えられません。 サーバーは、コンテンツを期待する箇所でパス文字列を受け取ります。 - ツールごとに最大 1 つの配列ファイル パラメータを宣言します。 2 つ以上の場合、Cowork はどのファイルがどの配列に属しているかを判断できず、呼び出しがツール エラーで失敗します。 1 つの配列、複数のスカラー パラメーター、またはスカラーと 1 つの配列の組み合わせを使用します。
- スカラーのみのツールでは正確なカウントが得られます。 ツールでスカラー ファイル パラメーターのみを宣言する場合は、エージェントが渡すファイルの数が宣言された数と一致する必要があります。 オプションのファイルパラメータを説明内で明確に示し、エージェントが不足したり過剰に指定したりしないようにします。
Note
このメカニズムは、MCP ファイル アップロード ワーキング グループによって標準化が進められている、Model Context Protocol 自身のファイル入力の取り組みよりも前から存在します。 Cowork は、標準化された形式の宣言型ファイル入力が導入されたら、そのサポートを追加する可能性があります。 ここで説明する contentEncoding: base64 コントラクトは引き続き機能します。
サーバーへの Cowork トラフィックを特定する
MCP サーバーがクライアントごとにツールの可視性を制御する場合、または受信したトラフィックの送信元を特定したい場合は、Cowork からのリクエストを認識できます。 Cowork は、次の 2 つのチャネルで安定したソフトウェア アイデンティティを示します。
| Channel | 表示される場所 | Value |
|---|---|---|
User-Agent リクエストヘッダー |
Cowork がサーバーに送信する各リクエスト | copilot-cowork/1.0 |
clientInfo MCP initialize ハンドシェイク内の |
initializeリクエストのみ |
{ "name": "copilot-cowork", "version": "<version>" } |
copilot-cowork プレフィックスに一致
いずれかのチャネルで copilot-coworkプレフィックス に一致する(大文字と小文字を区別しない)。
copilot-cowork/1.0文字列または特定のclientInfo.versionに完全一致させないでください。 バージョンは client-identity 契約を追跡しており、変更される可能性があります。プレフィックス一致により、バージョン変更後もゲート機能が動作し続けます。
# Correct: case-insensitive prefix match
copilot-cowork
# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0
ゲートに適したチャネルを選択してください
2 つのチャネルの適用範囲は異なるため、サーバーが制限を適用する方法に一致するものを基準にしてください:
-
User-Agentヘッダーは、tools/callや を含むtools/list要求に存在します。 要求ごとにゲートまたは属性付けする場合は、このヘッダーをキーにします。 -
clientInfoはハンドシェイクでinitialize送信されます。 接続時に セッションごとに ゲートする場合は、そこで読み取ることができますが、その後の要求では繰り返されません。
ID 情報に含まれるものと含まれないもの
その識別情報はソフトウェアのみを識別します。 これはすべての Cowork ユーザーと接続で同じであり、ユーザー ID を伝達することはありません。 ユーザー ID は、コネクタの認証構成が定義する認可フローに残ります。
| ID 情報には次のものが含まれます | この ID には含まれていません |
|---|---|
安定したソフトウェア名 (copilot-cowork) とコントラクト バージョン |
任意のテナント、ユーザー、セッション、または会話識別子 |
| すべての要求とすべての接続で同じ値 | コネクタごとの修飾子 |
コネクタごとの修飾子がないため、現在のところ、この ID を使用して、呼び出しを行ったコネクタを見分けたり、公開済みの Microsoft プラグインを同じ URL を指すサイドロードされたサーバーから分離したりすることはできません。 その区別が必要な場合は、クライアント ID ではなく、コネクタの認可設定を通じて適用します。
一般的な質問
Claude Code で M365 パッケージのスキルを使用できますか?
Yes. スキル フォルダーには、標準のエージェント スキルが含まれています。
wiqd plugin export --format claude-pluginを実行してClaude Codeレイアウトを生成するか、スキルフォルダーを任意のClaude Codeプロジェクトの.claude/skills/にコピーします。
リモート コネクタは必要ですか?
No. スキル専用パッケージは、プロンプトベースのワークフローに適しています。 コネクタは、スキルが外部システムからのライブ データを必要とする場合にのみ必要です。
プラグインのスキルと組み込みのスキルの違いは何ですか?
プラグイン スキルは、API でソース "package" として表示されます。 同じ名前の組み込みスキルを上書きすることはできません。 管理者が展開したパッケージは isAdminDeployed: true と表示されます。
IT 管理者は使用可能なプラグインを制御できますか?
Yes. Standard M365 管理コントロールが適用されます: テナント レベルの許可/ブロック リスト、管理者が管理するデプロイ、コンプライアンス ポリシー。
プラグインが取り消された場合はどうなりますか?
次の同期サイクルで、そのパッケージのスキルとコネクタはユーザーのセッションから削除されます。 アクティブな会話は中断されませんが、新しいセッションにはパッケージの機能がありません。
パッケージあたりのスキルの最大数は何ですか?
二十(20)個のスキル(ASKILL-M002に基づく)。 コネクタの場合、制限はパッケージあたり 10 個です。
スキルは同じパッケージからコネクタ ツールを参照できますか?
はい、そうすべきです。
SKILL.md ワークフローでツールを明示的に指定してください (たとえば、"search_case_law ツールを使用して...")。 エージェントは実行時にそれらを接続します。
プラグインのツールで Cowork ワークスペースのファイルを受け入れることはできますか?
Yes. ツール パラメーターを contentEncoding: base64 で宣言すると、Cowork はサーバーを呼び出す前にユーザーのワークスペース ファイルを base64 コンテンツに解決します。 モデルはファイル コンテンツではなくファイル パスを渡すため、大きなファイルはモデルのコンテキストを消費しません。 申告の詳細と制限については、「Cowork ワークスペースからファイルを受け入れる」を参照してください。
パッケージの決定論的 GUID を生成するにはどうすればよいですか?
wiqd plugin create によってアプリ ID が生成され、ピン留めされます。 変換スクリプトはプラグイン名の UUID v5 (SHA-1 ベース) を使用するため、変換を 2 回実行すると同じ GUID が生成されます。 手動パッケージ化の場合は、任意の GUID ジェネレーターを使用します。 バージョン間で安定性を保つようにしてください。
どのマニフェスト バージョンをターゲットにする必要がありますか?
wiqd を使用してビルドしている場合は、1.29 を目標にします。wiqd が 1.29 に自動的にピン留めしてくれます。 1.29 では、 agentConnectors[] エントリは URL のみであり、 mcpToolDescription は省略可能です。 この記事の手書きの例では 1.28 を使用します。ここで mcpToolDescription が必要であり、そのmcpToolDescriptionが指すファイルは ZIP 内になければなりません。
atk import openplugin は、プラグイン名に基づく UUID v5(SHA-1 ベース)を使用します。 インポートを 2 回実行すると、同じ GUID が生成されます。 独自のものを設定するには、--app-id を渡します。 手動パッケージ化の場合は、任意の GUID ジェネレーターを使用します。 バージョン間で安定性を保つようにしてください。