Copilot Cowork 用のプラグインをビルドする

Microsoft Copilot Cowork では、Teams アプリ、Copilot エージェント、Office アドインで使用されるのと同じ配布メカニズムである M365 アプリ パッケージによる拡張性がサポートされています。Cowork は次のように拡張できます:

• スキル: 財務分析、法律調査、人事ワークフローなど、Cowork に新しい専門知識を教えるプロンプトベースのワークフロー。
• コネクタ: Cowork に外部データ ソースと API へのアクセスを提供するリモート サーバー。

どちらも標準の Microsoft 365 アプリ パッケージにまとめてパッケージ化され、Microsoft 365 App Store を通じて配布されます。

ビルドする内容

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ツールでサポートされているのと同じ形式であるエージェントスキルオープンスタンダードを使用します。

開始点を選択する

既存のプラグインをインポートする

スキルと MCP サーバーを含む Claude コードまたはカーソル プラグインが既にある場合は、Microsoft 365 Agents Toolkit CLI (atk) が直接インポートします。 CLI は、Windows、macOS、Linux で実行されます。

1. CLI をインストールします (バージョン 1.1.12 以降が必要):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. バージョンを確認します。

   atk --version
   

3. プラグインをインポートします。

   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 を含める必要があります。

結果をアップロード可能な .zipにパッケージ化します。

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

インポートされる情報

変換されないもの

次の Claude プラグイン機能は、Microsoft 365 マニフェストではまだサポートされていません。

インポート オプション

認証の種類の自動検出:

自動検出が設定と一致しない場合は、 --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

[エクスポート] では、生成されたplugin.jsonにx-microsoft-365-agents-toolkit ブロックが書き込まれます。 このブロックには、マニフェスト id、開発者 URL、およびコネクタ設定が含まれるため、後で atk import openplugin ラウンド トリップが再 --privacy-url または --terms-url 必要ありません。

レガシ: PowerShell 変換スクリプト

プラグイン インポートがサポートされる前 atk 、変換には Windows 専用の PowerShell スクリプトが使用されていましたが、これは変換 スクリプトとして引き続き使用できます。

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

代わりに atk import openplugin を使用してください。 クロスプラットフォームであり、CursorとClaudeコードソースをサポートし、プラグインディレクトリにエクスポートすることができます。

プラグインを最初からビルドする

次の手順に従って、最初のスキルから始めて、公開可能な完全なパッケージに至るまで、プラグイン パッケージをゼロから作成します。

手順 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 フィールド

必須フィールド:

名前付けルール (ケバブケース): 小文字の英数字とハイフンは必ず使用してください。 連続するハイフンは使用しないでください。また、先頭または末尾のハイフンは使用しないでください。

手順 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 以外のファイル) を含めることができます。 スキルごとに次の制限が適用されます。

コンパニオン ファイルのルール

コンパニオン ファイル パスは次の規則に従う必要があります。

• 相対パスのみ使用(絶対パスは使用しない)
• パス トラバーサルなし (セグメント.. )
• ファイル名にバックスラッシュまたは NULL バイトを含まない
• 隠しファイル ( . で始まる名前) は許可されません
• Windows の予約名 (CON、 PRN、 AUX、 NUL、 COM1–COM9、 LPT1–LPT9) はありません
• ファイル SKILL.md 自体はコンパニオン ファイルとしてカウントされません
• ファイル名には、英数字、ハイフン、アンダースコア、ドット、スペース、 !

コンテキスト ウィンドウを効率的に保つために、システムはスキルを 3 つのレイヤーに読み込みます。

エージェントがサブディレクトリが存在することを認識できるように、 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 サーバーを追加します。 この手順は省略できます。 スキル専用パッケージは、プロンプトベースのワークフローに適しています。

コネクタの要件

ツール設計ガイドライン

• 小規模な API (操作が 15 個未満) の場合は、アクションごとに 1 つのツール: search_case_law、get_ruling、cite_precedent
• 大規模な API (50+ 操作) の検索 + 実行:search_actions + execute_action
• わかりやすい名前:get_bond_pricegetData
• リッチ入力スキーマ: すべてのパラメーターの説明を含めます (これはエージェントが読み取る内容です)
• 構造化出力: エージェントがユーザー用に書式設定できる JSON を返します
• ファイル入力: ユーザーのワークスペースからファイルを受け入れるには、パラメーターを contentEncoding: base64 で宣言します。 詳細については、「Cowork ワークスペースからファイルを受け入れる」を参照してください。

コネクタのツールについて説明する (mcpToolDescription)

すべての remoteMcpServer コネクタには、 mcpToolDescription オブジェクトを含める必要があります。 入れ子になった file プロパティは、 .zip 内にパッケージ化し、パッケージのルートからの相対パスで参照するツール記述 JSON ファイルを指し示します。 mcpToolDescription省略すると、パッケージ サービスは HTTP 400 エラーでアップロードを拒否します。

オブジェクト mcpToolDescription に必要なプロパティがありません。

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  },
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
  }
}

参照ファイル ( tools/contoso-legal-tools.json など) は、コネクタが公開するツールを記述し、 ZIP パッケージ内に存在する必要があります。 プラグインをパッケージ化するときに、 manifest.json フォルダーと skills/ フォルダーに含めます。

サポートされている認証の種類

OAuthPluginVaultおよびApiKeyPluginVaultの場合、referenceIdは Microsoft Enterprise トークン ストアに格納されている資格情報を指します。シークレットがマニフェストやスキル ファイルに表示されることはありません。 referenceId値は、OAuth クライアントを Agents Toolkit に登録するときに作成する OAuth クライアント登録 ID です。

MCP 認証

認証に OAuth または ApiKey を使用するには、セットアップと構成の詳細については、「Microsoft 365 Copilot のエージェントで MCP および API プラグインの認証を構成する」を参照してください。

動的クライアント登録

MCP サーバーが 動的クライアント登録 (DCR) をサポートしている場合は、コネクタ定義からauthentication構成を省略でき、Cowork はプラグインに代わって OAuth クライアントを自動的に作成します。

authorization オブジェクトは省略できますが、mcpToolDescriptionを含める必要があります。 MCP サーバーの URL とツールの説明を構成すると、Cowork が OAuth クライアントを処理します。

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  }
}

手順 4: マニフェストを作成する

パッケージ ルートに manifest.json を作成します。

{
  "$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 ファイルを指す必要があります。

手順 5: アイコンを追加する

2 つの PNG アイコンを作成します。

アイコンがまだない場合は、 atk import openplugin によって単色のプレースホルダーが生成されます。 ストアへの提出前に置き換えてください。

手順 6: パッケージ化

すべてのコンテンツをルート レベルで含む ZIP ファイルを作成します。

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

パッケージに agentConnectors エントリが含まれている場合は、 mcpToolDescription.file によって参照されるツール記述 JSON ファイルを含めます。 スキル専用パッケージには 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/

Using 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 にアップロードします。

個人テストでは、Microsoft 365 Agents Toolkit コマンド ライン インターフェイスを使用してアプリをサイドロードします。

1. npm から @microsoft/m365agentstoolkit-cli をインストールします。

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. 次を実行してインストールを確認します。

   atk --version
   

3. Microsoft 365 職場アカウントで認証します。

   atk auth login
   

4. 職場アカウントにサインインして、エージェント パッケージをインストールします。 ファイル パスを ZIP パッケージの場所に置き換えます。

   atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
   

   インストールが成功すると、アカウントの TitleId と AppId を含む出力が返されます。

5. 後で更新またはアンインストールするときに使用するために、これらの ID を保存してください。

Microsoft 365 Agents Toolkit コマンド ライン インターフェイスに関する詳細情報。

手順 8: テナントに公開する

1. M365 管理センターを開き>アプリの管理>カスタム アプリをアップロードします。
2. 省略記号ボタン (...) を選択 >エージェントを追加します。
3. .zip パッケージをアップロードします。
4. Cowork>ソース & スキル>プラグインを開きます。 プラグインが [検出] セクションに表示されます。

手順 9: 一般に公開する

一般配布を目的としたプラグインの場合は、パートナー センター経由でプラグインを Microsoft 365 App Store に提出します。 詳細については、「Microsoft 365 Copilot 用のエージェントの発行」を参照してください。

ローカルの MCP サーバーに対してコネクタをテストする

コネクタには HTTPS mcpServerUrlが必要なため、マシンで実行されているサーバーをテストするには、パブリック HTTPS URL 経由でサーバーを公開する必要があります。 開発トンネルは 、TLS を終了するリレーを提供します。

devtunnel port create <tunnel> -p <port> --protocol http

トラブルシューティング

パッケージ化パターン

拡張機能に合ったパターンを選択します。

スキルのみ (コネクタなし)

プロンプトベースのワークフロー、ドキュメント分析、文書作成支援に最適です。

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
│   └── 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
    └── my-connector.json

インポートされたClaudeコードまたはカーソルプラグイン

このオプションは、Cowork を対象とする他の AI ツールの既存のプラグインに使用します。

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/ に移動します。

入力規則

パッケージを送信すると、プラットフォームによって複数のレベルで検証が行われます。 拒否されないように、提出前にこれらのエラーを修正してください。

マニフェスト レベルの検証

パッケージ レベルの検証

コネクタの検証

コンパニオン ファイルの検証

ポータルでは、アップロード時および同期時にコンパニオン ファイル ( SKILL.mdと共に参照資料、スクリプト、その他のファイル) を検証します。

クロスプラットフォームの互換性

スキルはエージェント スキル オープン スタンダードを使用します。 同じ SKILL.md ファイルが複数の AI ツールで動作します。

Claude Code と Cowork の両方のスキルを開発している場合は、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 に公開する準備ができたら、M365 プロジェクトにインポートします。

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 は、サーバーが tools/list から返すツール上の標準 MCP annotations オブジェクトを読み取り、それを使用して、ツールの呼び出しにユーザーによる確認が必要かどうか、およびプロンプトに表示するラベルを決定します。

使用できるフィールド

確認ルール

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 エンコードするため、ファイル バイトがエージェントのコンテキストに入ることはありません。 エージェントは、ワークスペース ファイル パスのみを認識して出力します。

ファイル パラメーターの宣言

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ワークスペース パスを設定し、呼び出しを転送する前に、各パスを所定の base64 コンテンツ用にスワップCoworkします。

入れ子は、 inputSchema の上部から下の 4 つのレベルの深さまでトラバースされます。 $ref ポインターは追従されません。ファイル パラメーターを $refの背後ではなくインラインで定義します。

サーバーが受け取る内容

サーバーは、base64 でエンコードされたコンテンツが設定された元のパラメーター名を持つ通常の tools/call を受け取ります。

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

エージェントがパスベースのインターフェイスを使用したことをサーバーは認識する必要はなく、 contentEncoding: base64 パラメーターを宣言しないツールも影響を受けません。

制限

ファイル数またはサイズの上限を超える呼び出しは、ツール エラーで失敗し、サーバーに到達しません。 150MiB の上限を念頭に置いて、API とそのタイムアウトのサイズを設定します。base64 は、ペイロードを生ファイルサイズの約 3 分の 1 に膨らませ、エンコードされたコンテンツは JSON-RPC 要求本文で送信されます。

推奨事項

• 人間のリーダーのためにパラメーターを記述します。 エージェントは、説明を使用して、どのファイルがどのパラメーターに属するかを判断します。 たとえば、 "The signed contract PDF to analyze" は "file" よりもうまく機能します。
• パラメーターの説明に受け入れる形式を記述します。 Cowork は、ユーザーがアタッチしたものをすべて通過します。 味方のコンテンツ タイプを検証し、使用できない場合はクリア ツール エラーを返します。
• 注釈を設定します。 通常、ファイルを受け取って操作するツールは読み取り専用ではないため、確認を求められます。 MCP の注釈と確認管理を参照してください。
• ファイル パラメーターはインラインのままにします。 $refの背後にあるパラメーター、または 4 レベルより深く入れ子になったパラメーターは書き換えられません。 サーバーは、コンテンツが必要な場所でパス文字列を受け取ります。
• ツールごとに最大 1 つの配列ファイル パラメータを宣言します。 2 つ以上の場合、Cowork はどのファイルがどの配列に属しているかを判断できず、呼び出しがツール エラーで失敗します。 1 つの配列、複数のスカラー パラメーター、またはスカラーと 1 つの配列の組み合わせを使用します。
• スカラーのみのツールでは正確なカウントが必要です。 ツールでスカラー ファイル パラメーターのみを宣言する場合は、エージェントが渡すファイルの数が宣言された数と一致する必要があります。 オプションのファイルパラメータを説明で明確にマークして、エージェントが過小または過剰に供給しないようにします。

サーバーへの Cowork トラフィックを特定する

MCP サーバーがクライアントによってツールの可視性をゲートする場合、または MCP サーバーが受信するトラフィックに属性を付ける場合は、Cowork からのリクエストを認識できます。 Cowork は、次の 2 つのチャネルで安定したソフトウェア ID を提供します。

copilot-cowork プレフィックスでの一致

いずれかのチャネルで copilot-coworkプレフィックスと一致し、大文字と小文字を区別しません。 copilot-cowork/1.0文字列または特定のclientInfo.versionと完全に一致しない。 バージョンはクライアント ID コントラクトを追跡し、変更される可能性があります。プレフィックスの一致により、バージョン変更後もゲートが機能し続けることができます。

# Correct: case-insensitive prefix match
copilot-cowork

# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0

ゲートに適したチャネルを選択してください

2 つのチャネルのスコープは異なるため、サーバーがゲートを適用する方法に一致するものをキーにしてください:

• User-Agent ヘッダーは、tools/list や tools/call を含むすべての要求に存在します。 要求ごとにゲートまたは属性を設定する場合は、このヘッダーをキーにします。
• clientInfoは、initialize ハンドシェイクでのみ送信されます。 接続時に セッションごとに ゲートする場合は、そこで読み取ることができますが、その後の要求では繰り返されません。

ID に含まれるものと含まないもの

ID は ソフトウェア にのみ名前を付けます。 これはすべての Cowork ユーザーと接続で同じであり、ユーザー ID が保持されることはありません。 ユーザー ID は、コネクタの認証構成が定義する承認フローに残ります。

コネクタごとの修飾子がないため、現在のところ、この ID を使用して、呼び出しを行ったコネクタを見分けたり、公開された Microsoft プラグインを同じ URL を指すサイドロードされたサーバーから分離したりすることはできません。 その区別が必要な場合は、クライアント ID ではなく、コネクタの承認構成を通じて適用します。

よくある質問

Claude CodeでM365パッケージのスキルを使用できますか?

はい。 スキル フォルダーには、標準のエージェント スキルが含まれています。 これらをコピーして任意の Claude Code プロジェクトの.claude/skills/にするか、atk export openpluginを実行してプロジェクト全体を Claude Code プラグインに変換し直します。

リモート コネクタは必要ですか?

その必要はありません。 スキル専用パッケージは、プロンプトベースのワークフローに適しています。 コネクタは、スキルが外部システムからのライブ データを必要とする場合にのみ必要です。

プラグイン スキルと組み込みスキルの違いは何ですか?

プラグイン スキルは、API のソース "package" と共に表示されます。 同じ名前の組み込みスキルを上書きすることはできません。 管理 で展開されたパッケージは isAdminDeployed: true を示します。

IT 管理者は、使用できるプラグインを制御できますか?

はい。 Standard M365 管理コントロールが適用されます: テナント レベルの許可/ブロック リスト、管理者が管理するデプロイ、コンプライアンス ポリシー。

プラグインが取り消された場合はどうなりますか?

次の同期サイクルで、そのパッケージのスキルとコネクタはユーザーのセッションから削除されます。 アクティブな会話は中断されませんが、新しいセッションにはパッケージの機能がありません。

パッケージあたりのスキルの最大数は?

20 のスキル (ASKILL-M002 による)。 コネクタの場合、制限はパッケージあたり 10 個です。

スキルは同じパッケージのコネクタ ツールを参照できますか?

はい、そうすべきです。 SKILL.md ワークフローでツールに明示的に名前を付けます (たとえば、"search_case_law ツールを使用して...")。 エージェントは実行時に接続します。

プラグインのツールは Cowork ワークスペースからのファイルを受け入れますか?

はい。 ツール パラメーターを contentEncoding: base64 で宣言し、サーバーを呼び出す前にCoworkユーザーのワークスペース ファイルを base64 コンテンツに解決します。 モデルはファイル コンテンツではなくファイル パスを渡すため、大きなファイルはモデルのコンテキストを消費しません。 宣言の詳細と制限については、「Cowork ワークスペースからファイルを受け入れる」を参照してください。

パッケージの確定的な GUID を生成する操作方法

atk import openplugin プラグイン名の UUID v5 (SHA-1 ベース) を使用します。 インポートを 2 回実行すると、同じ GUID が生成されます。 独自に設定するには、 --app-id を渡します。 手動パッケージ化の場合は、任意の GUID ジェネレーターを使用します。 バージョン間で安定性を保つようにしてください。

関連コンテンツ

• Cowork の概要
• Cowork を使用する
• Cowork を organization の管理する
• Cowork のプラグインを管理する