geekfujiwara/codeappsdevelopmentstandard/cowork

Cowork プラグイン開発（Dataverse MCP セット）

目的特化型の Copilot Cowork プラグイン（M365 アプリパッケージ .zip）を作る。 ビジネススキル（SKILL.md）と Dataverse MCP コネクタをセットにし、Entra ID の OAuth 2.0 認可コードフロー認証で Cowork から Dataverse を直接操作できるようにする。

データ先は Dataverse だけではない: agentConnectors は remote MCP server を指すため、

mcp-server スキル で構築した 自前 MCP Server（Azure Functions） も

同じようにコネクタにできる。基幹 DB・ファイルサーバー・業務 API など Dataverse に無いデータを

Cowork から扱う場合は 自前 MCP Server をコネクタにする を併せて読む

（差分は Step 3 の権限・Step 4 の可否・Step 5 の Scope・Step 6 の URL の 4 点だけ）。

前提: 利用テナントが Frontier プレビュー に参加していること。

会社環境で Cowork の利用が許可されている場合のみこのスキルを使用してください。利用可否が不明な場合は管理者に確認してください。

異常系・トラブルシュートは references/troubleshooting.md を参照。

サブリファレンス

パッケージ構成（Skills + remote connector）

<plugin-root>/
├── manifest.json                 # M365 Unified App Manifest v1.28
├── color.png                     # 192×192 フルカラーアイコン
├── outline.png                   # 32×32 アウトラインアイコン
├── build-package.ps1             # .zip 生成（検証付き）
└── skills/
    └── <skill-name>/             # kebab-case。フォルダ名 = SKILL.md の name と一致必須
        └── SKILL.md              # frontmatter(name/description) + ワークフロー本文

事前確認（会話の最初に 1 回だけ）

本スキルの利用が確定したら、standard の共通契約に加え、 1 回の AskUserQuestion で次をまとめて確認する。

担当ごとの必要な権限は references/permissions.md を見せて確認する（同意できるロール: クラウド アプリケーション管理者・アプリケーション管理者・AI 管理者）。

Frontier は Cowork を利用するためのプレビュー条件であり、Microsoft Copilot ライセンスとは別に確認する。 Global Administrator を常用せず、Agent 管理は AI Administrator、全テナントへの高権限な OAuth 同意が必要な場合は Privileged Role Administrator を担当工程だけに使用する。

前提チェック:

1. python .github/skills/standard/scripts/check_mcp_client.py cowork が ✅ であること。
2. Python 3（auth_helper.py / アイコン生成）と PowerShell（パッケージビルド）が利用可能であること。
3. いずれかの前提が未確認なら、アプリ登録・シークレット作成・公開へ進まないこと。

スキル同梱スクリプト（再利用）

scripts/ のスクリプトは汎用化されており、どのテナント・環境でも .env（TENANT_ID / DATAVERSE_URL / PUBLISHER_PREFIX / COWORK_OAUTH_CLIENT_ID）を参照して動作する。

ワークフロー（正常系）

Step 0: ヒアリング（プラグイン構想の提案）

ユーザーが「プラグインを作りたい」「Cowork で〜したい」と相談してきたら、いきなり実装に入らず まず構想を提案する。以下の流れで会話を始める。

1. 目的の確認: 「Cowork 用のプラグインとして作りますか？ 例えば『〇〇業務を Cowork から

Dataverse のデータで支援する』ような形を想定しています」と確認する。

1. 対象データの把握: 連携する Dataverse 環境／テーブル（顧客・契約・実績など）をヒアリング。

不明なら describe / search 系で既存テーブルを軽く調べて候補を出す。 Dataverse に無いデータ（基幹 DB・ファイルサーバー・業務 API）が必要なら、この段階で確認する。 必要なら mcp-server スキル で自前 MCP Server を先に立て、 references/custom-mcp-connector.md でコネクタとして併載する。

1. スキル案を5つ提案: その業務ドメインで Cowork が役立つスキルを5つ程度列挙する。

各スキルは「名前（kebab-case）＋一言の用途＋トリガー語の例」をセットで示す。

例（保守契約ドメインの場合）:

1. プラグイン名を提案: 5つのスキル群を束ねるプラグイン名（短縮名 / 正式名）を 2〜3 案提示する。

個社名は避け、業務ドメインが伝わる名前にする（例: 「MFP 年間レビュー」「保守契約アシスタント」）。

1. 合意: ユーザーが採用するスキル（1つでも複数でも可）とプラグイン名を選んだら、Step 1 以降に進む。

テンプレートから始める: 営業支援（予定表・メール・チャット → CRM）なら、合意後に

sales-crm-plugin を scaffold_from_template.py で生成して Step 1 の describe 確認から続ける。

Code Apps の templates/sales-crm と同じ Dataverse を共有する。

最初は 1スキル + Dataverse MCP コネクタの最小構成で公開・疎通確認し、動いたら

残りのスキルを追加する流れが安全（コネクタ認証の検証を先に済ませられる）。

Step 1: 対象テーブルを describe でスキーマ確認（クエリを書く前に必須）

スキル本文にクエリを書く前に、必ず `describe` で対象テーブルの実スキーマを確認する。 テーブル名・列名・ルックアップ（外部キー）列の正確な名前を推測で書かない（推測は実行時の Read query Failed の主因。特に FK 列は環境やクエリ方式で表記が異なる）。

1. 対象テーブルごとに describe を実行し、以下を確定する:

• テーブル名（論理名 / コレクション名のどちらをクエリで使うか）
• 列の論理名（表示名ではなく論理名）
• ルックアップ列の表記: describe の結果に出る実際の列名を使う。

read_query のクエリ方式に合わせること（Web API/OData 形式の _xxxid_value と SQL/論理名 xxxid は別物。describe が返す名前をそのまま使う）。

• 選択肢（Picklist）の値とラベルの対応

1. 確認できたスキーマだけを使ってクエリを書く。describe に無い列・テーブルは使わない。
2. スキル本文の冒頭にも「Step 1: 対象テーブルを describe で確認してからクエリする」を入れ、

生成するスキル自身も実行時に describe で裏取りする手順にする（下のテンプレート参照）。

確認結果は「対象データ（テーブル）」表に論理名でまとめる。表示名は補足に留める。

Step 2: スキル（SKILL.md）を作る

skills/<skill-name>/SKILL.md を作成。フォルダ名と frontmatter `name` を完全一致させ、 name は kebab-case（小文字英数とハイフン、連続/先頭/末尾ハイフン禁止）。

---
name: annual-customer-review
description: |
  <何をするスキルか>。Use when ユーザーが「<トリガー語1>」「<トリガー語2>」と依頼したとき。
  Dataverse MCP コネクタ（read_query / search_data / search / describe）を使用する。
license: MIT
metadata:
  author: <作成者>   # 開発中のサインイン アカウントの表示名（manifest の developer.name と同じ値）
  version: "1.0"
---

作成者は開発中のサインイン アカウントにする。python .github/skills/cowork/scripts/get_developer_account.py が

auth_helper のキャッシュで Graph の /me を読み、表示名（developerName。manifest の上限 32 文字に切り詰め）を返す。

この値を COWORK_DEVELOPER_NAME として manifest の developer.name と各スキルの metadata.author に入れる

（テンプレートでは質問の detect で既定値になる）。会社名・固定の文字列を入れない。

本文は ワークフローとして書く（番号付き手順／使用ツール名を明示／出力フォーマットを定義）。 本文は約 1,500〜2,000 語以内。詳細は references/ に逃がす（コンパニオンファイルは最大20・各5MB）。

生成するスキル本文の必須ルール: ワークフローの最初の Step を

「対象テーブルを describe でスキーマ確認（列名・FK 列名を確定）」とする。

クエリ例の列名は describe で確認済みのものだけを使い、未確認の列を推測で書かない。

結果の見せ方（提案するスキルは標準で Render UI のグラフ）: 提案・助言・打ち手・対策案を出すスキルと、数字を扱うスキル（集計・点検・登録の確認）は、 答えを チャットのグラフ（Render UI）・表・保存用の HTML レポート で返す。スキルに書くのは 3 つだけ: ① 必須ルールの後に <!-- include: display-rules.md -->（ビルドで共通ルール display-rules.md に置き換わり、 scripts/ に report_builder.py とひな形が入る）、② 「このスキルのグラフ」の節（図の題名・種類 stacked_hbar / grouped_bar・元の表・単位）、 ③ 図の位置 〔Render UI の図: …〕 と 📄 レポート: <ファイル名>.html を入れた回答のひな形と、「このスキルの確認（返す前・毎回）」。 グラフ・表・HTML は report_builder.py が 1 つの計算結果（results.json）から作り、取得不足・単位の混在・内部識別子・3 つの数字の不一致を止める。 Render UI の仕様と正式な色は公開されていないため、実行時に Render UI の説明を読んで使い、表示を確かめるまで成功と書かず、1 回直して駄目なら文字のグラフに切り替える。 書き方の例・results.json の形は references/visual-output.md。build_agent_package.ps1 が check_visual_output.py で毎回検査し、提案するスキルに手順が無ければ止める（#52・#53）。

Step 3: Entra アプリ（OAuth クライアント）を作成・構成

Dataverse MCP は Microsoft ファーストパーティ API のため、トークンの audience が Dataverse 自身 （https://<org>.crm.dynamics.com）である必要がある。SSO 方式は audience が「自前アプリ」になり失敗する （→ troubleshooting #14）。そのため OAuth 2.0 認可コードフローを使い、Enterprise Token Store に Dataverse 宛のトークンを直接取得させる。クライアントシークレットが必要。値は .env に保存する。