From 753d260bc33ca980064280c8ff3bc11d753956b0 Mon Sep 17 00:00:00 2001 From: Esteban Chavez Date: Wed, 24 Jun 2026 10:24:51 -0700 Subject: [PATCH 1/3] Rename 'app add connector' to 'app add data-source' in managed-apps docs Mirror CLI PR renaming the verb 'ms app add connector' -> 'ms app add data-source' (connector kept as a deprecated alias; --connector flag retained). Rename the /add-connector skill to /add-data-source and update all delegating wrapper skills and docs (including the connector decision guide). Note the connector form is deprecated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- plugins/microsoft-managed-apps/AGENTS.md | 4 +-- plugins/microsoft-managed-apps/QUICKSTART.md | 4 +-- plugins/microsoft-managed-apps/README.md | 2 +- .../agents/microsoft-apps-architect.md | 4 +-- .../shared/connector-decision-guide.md | 26 +++++++++---------- .../shared/connector-reference.md | 9 ++++--- .../skills/add-azuredevops/SKILL.md | 6 ++--- .../SKILL.md | 21 ++++++++------- .../skills/add-dataverse/SKILL.md | 6 ++--- .../api-authentication-reference.md | 2 +- .../skills/add-excel/SKILL.md | 6 ++--- .../skills/add-mcscopilot/SKILL.md | 6 ++--- .../skills/add-office365/SKILL.md | 6 ++--- .../skills/add-onedrive/SKILL.md | 6 ++--- .../skills/add-sharepoint/SKILL.md | 6 ++--- .../references/sharepoint-reference.md | 2 +- .../skills/add-teams/SKILL.md | 6 ++--- .../skills/create-app/SKILL.md | 6 ++--- .../skills/list-connectors/SKILL.md | 4 +-- 19 files changed, 69 insertions(+), 63 deletions(-) rename plugins/microsoft-managed-apps/skills/{add-connector => add-data-source}/SKILL.md (87%) diff --git a/plugins/microsoft-managed-apps/AGENTS.md b/plugins/microsoft-managed-apps/AGENTS.md index b3cc146..cd1a5e6 100644 --- a/plugins/microsoft-managed-apps/AGENTS.md +++ b/plugins/microsoft-managed-apps/AGENTS.md @@ -67,7 +67,7 @@ This plugin uses a memory bank (`memory-bank.md`) to persist state across sessio | `/add-onedrive` | OneDrive for Business files. | | `/add-azuredevops` | Azure DevOps work items / pipelines. | | `/add-mcscopilot` | Microsoft Copilot Studio agents. | -| `/add-connector` | Generic fallback for any other connector. | +| `/add-data-source` | Generic fallback for any other connector. | | `/list-connectors` | Enumerate connectors / bound data sources for discovery. | ### Workflow @@ -75,7 +75,7 @@ This plugin uses a memory bank (`memory-bank.md`) to persist state across sessio ``` /create-app └── /dev (default loop) - └── /add-connector (or specific /add-*) + └── /add-data-source (or specific /add-*) └── /deploy (explicit, requires confirmation) └── /share, /delete-app (explicit, require confirmation) ``` diff --git a/plugins/microsoft-managed-apps/QUICKSTART.md b/plugins/microsoft-managed-apps/QUICKSTART.md index f056b61..10a6d94 100644 --- a/plugins/microsoft-managed-apps/QUICKSTART.md +++ b/plugins/microsoft-managed-apps/QUICKSTART.md @@ -79,9 +79,9 @@ Your copilot will recommend data sources based on what your app needs to do. To | Send Teams messages | `/add-teams` | | Query Azure DevOps work items | `/add-azuredevops` | | Invoke a Copilot Studio agent | `/add-mcscopilot` | -| Something else (any other connector) | `/add-connector` | +| Something else (any other connector) | `/add-data-source` | -Each command runs `ms app add connector --connector ` against the right connector, regenerates typed TypeScript services under `src/`, and verifies the build. Your local `ms app dev` hot-reloads the new services. +Each command runs `ms app add data-source --connector ` against the right connector, regenerates typed TypeScript services under `src/`, and verifies the build. Your local `ms app dev` hot-reloads the new services. ### Ship to the Cloud diff --git a/plugins/microsoft-managed-apps/README.md b/plugins/microsoft-managed-apps/README.md index b20106c..24f67e1 100644 --- a/plugins/microsoft-managed-apps/README.md +++ b/plugins/microsoft-managed-apps/README.md @@ -12,7 +12,7 @@ Microsoft Apps run locally against the App Player with hot reload (`ms app dev`) | ---------------- | -------- | | Scaffold | `/create-app` | | Lifecycle | `/dev`, `/deploy`, `/play`, `/share`, `/share-link`, `/delete-app`, `/list-apps` | -| Data sources | `/add-connector`, `/add-dataverse`, `/add-sharepoint`, `/add-excel`, `/add-office365`, `/add-teams`, `/add-onedrive`, `/add-azuredevops`, `/add-mcscopilot`, `/list-connectors` | +| Data sources | `/add-data-source`, `/add-dataverse`, `/add-sharepoint`, `/add-excel`, `/add-office365`, `/add-teams`, `/add-onedrive`, `/add-azuredevops`, `/add-mcscopilot`, `/list-connectors` | ## Prerequisites diff --git a/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md b/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md index 742dacd..d173b3c 100644 --- a/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md +++ b/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md @@ -67,13 +67,13 @@ ms --version # Bin name has flipped between dev builds | Read lists or manage documents in SharePoint | SharePoint (`/add-sharepoint`) | Direct list/document operations | | Send emails, read inbox, manage calendar | Office 365 Outlook (`/add-office365`) | Native calendar API with CRUD | | Invoke a Copilot Studio agent | MCS Copilot (`/add-mcscopilot`) | Agent invocation | -| Connect to any other service | Generic (`/add-connector`) | Fallback for unlisted connectors | +| Connect to any other service | Generic (`/add-data-source`) | Fallback for unlisted connectors | **See** [Connector Decision Guide](../shared/connector-decision-guide.md) for decision trees, common app patterns, and scenario examples. ### Generated Code Pattern -`ms app add connector` (with `--as table` or `--as action`) writes generated TypeScript directly under `src/`. The exact subdirectory layout is owned by `@microsoft/apps-actions`; expect `*Model.ts` and `*Service.ts` files alongside your handwritten code. Always use these generated services for data access. +`ms app add data-source` (with `--as table` or `--as action`) writes generated TypeScript directly under `src/`. The exact subdirectory layout is owned by `@microsoft/apps-actions`; expect `*Model.ts` and `*Service.ts` files alongside your handwritten code. Always use these generated services for data access. ### Scaffolding diff --git a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md index 8d92126..c4dab27 100644 --- a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md +++ b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md @@ -23,7 +23,7 @@ ms connector list-actions --connector shared_office365 --search Mail ### **Via Plugin Skills** -- **`/add-connector`** — Generic connector skill. Ask for a keyword ("salesforce", "slack", "jira", "workiq") and it will search, present options, and add the connector. +- **`/add-data-source`** — Generic connector skill. Ask for a keyword ("salesforce", "slack", "jira", "workiq") and it will search, present options, and add the connector. - **`/list-connections`** — View connectors already bound to your app, or explore operations on a specific connector ### **Via Specific Skills** @@ -34,7 +34,7 @@ For common connectors, shortcuts exist: - **`/add-sharepoint`** — SharePoint lists/documents - **`/add-dataverse`** — Dataverse tables - **`/add-mcscopilot`** — Copilot Studio agents -- (See full list in `/add-connector` help) +- (See full list in `/add-data-source` help) ### **Via Microsoft Docs** @@ -61,7 +61,7 @@ The matrix shows which connectors can search, create/update, delete, and provide ``` Does the app need to search across M365 (email, files, calendar, contacts)? - ├─ YES, semantic/conversational search → Use Work IQ (`/add-connector`) + ├─ YES, semantic/conversational search → Use Work IQ (`/add-data-source`) │ Example: "Find all meetings with client XYZ" │ Example: "Show emails about project Alpha from last month" │ @@ -102,7 +102,7 @@ What kind of AI capability? │ Example: "Summarize this meeting transcript" │ Example: "Generate action items from notes" │ - ├─ Semantic search, Q&A with citations → Work IQ (`/add-connector`) + ├─ Semantic search, Q&A with citations → Work IQ (`/add-data-source`) │ Example: "What was decided about budget in past meetings?" │ Example: "Show me all discussions about Q3 planning" │ @@ -120,10 +120,10 @@ What kind of AI capability? Example: "Meeting Insights" app ├─ List past meetings (action) → Office365 (`/add-office365`) ├─ Fetch transcript/recording details (action) → Teams (`/add-teams`) - ├─ Allow "find meetings about topic X" (search) → Work IQ (`/add-connector`) + ├─ Allow "find meetings about topic X" (search) → Work IQ (`/add-data-source`) └─ Generate summary (AI) → Copilot Studio (`/add-mcscopilot`) -→ Invoke `/add-office365`, `/add-teams`, `/add-connector`, `/add-mcscopilot` in sequence +→ Invoke `/add-office365`, `/add-teams`, `/add-data-source`, `/add-mcscopilot` in sequence ``` **Rule:** When multiple connectors are needed, each handles one responsibility. Invoke in order of dependency (actions first, then searches/AI). @@ -198,7 +198,7 @@ User Goal: "Build a dashboard showing my tasks and calendar" Connectors Recommended: 1. Office 365 (`/add-office365`) — fetch calendar events 2. Azure DevOps (`/add-azuredevops`) — fetch work items - 3. Optional: Work IQ (`/add-connector`) — allow search/drill-down + 3. Optional: Work IQ (`/add-data-source`) — allow search/drill-down ``` ### **Pattern 2: Meeting Insights App** @@ -209,7 +209,7 @@ Connectors Recommended: 1. Office 365 (`/add-office365`) — fetch calendar + meeting metadata 2. Teams (`/add-teams`) — fetch transcripts/recordings 3. Copilot Studio (`/add-mcscopilot`) — generate summaries - 4. Optional: Work IQ (`/add-connector`) — semantic meeting search + 4. Optional: Work IQ (`/add-data-source`) — semantic meeting search ``` ### **Pattern 3: Document Search & Management App** @@ -217,7 +217,7 @@ Connectors Recommended: User Goal: "Search company documents and allow downloads" Connectors Recommended: - 1. Work IQ (`/add-connector`) — semantic document search + 1. Work IQ (`/add-data-source`) — semantic document search 2. SharePoint (`/add-sharepoint`) — manage documents 3. OneDrive (`/add-onedrive`) — if including personal files ``` @@ -239,7 +239,7 @@ User Goal: "Store customer data, fetch emails, track interactions" Connectors Recommended: 1. Dataverse (`/add-dataverse`) — customer records 2. Office 365 (`/add-office365`) — fetch emails by customer - 3. Optional: Work IQ (`/add-connector`) — search customer conversations + 3. Optional: Work IQ (`/add-data-source`) — search customer conversations ``` --- @@ -255,7 +255,7 @@ When the user describes their app goal or data need: 4. Explain why each is chosen (reference the rules above) 5. Invoke the appropriate `/add-*` skills in order -### **For `/add-connector` (Canonical Skill)** +### **For `/add-data-source` (Canonical Skill)** This skill handles ANY connector, including those not listed in this guide. When called: @@ -272,7 +272,7 @@ This skill handles ANY connector, including those not listed in this guide. When - Check Microsoft connectors documentation: https://learn.microsoft.com/en-us/connectors/ - Use `/list-connections` skill to browse available connectors -**This guide covers the most common cases, but `/add-connector` works with any Microsoft connector — not just the 10 listed above.** +**This guide covers the most common cases, but `/add-data-source` works with any Microsoft connector — not just the 10 listed above.** ### **For Microsoft Apps Architect Agent** @@ -308,7 +308,7 @@ Decision Process: 3. Action needed? → NO (search-only) 4. AI needed? → NO -→ Recommend: `/add-connector` (then optionally `/add-sharepoint` if file management needed) +→ Recommend: `/add-data-source` (then optionally `/add-sharepoint` if file management needed) ``` ### **Example 3: User says "I need to build a system to store customer records and generate AI summaries of their interactions"** diff --git a/plugins/microsoft-managed-apps/shared/connector-reference.md b/plugins/microsoft-managed-apps/shared/connector-reference.md index b4ea74d..9bd4dd5 100644 --- a/plugins/microsoft-managed-apps/shared/connector-reference.md +++ b/plugins/microsoft-managed-apps/shared/connector-reference.md @@ -5,13 +5,16 @@ Applies to all `/add-*` skills. ## Connections — created inline by the CLI There is **no separate "create connection" command**. Connections are created and resolved -inline by `ms app add connector` (the single add command — there is no `ms app add action` / +inline by `ms app add data-source` (the single add command — there is no `ms app add action` / `ms app add table` / `ms app add procedure`): ```bash -ms app add connector --connector [--as table|action] [--connection-id | -c ] +ms app add data-source --connector [--as table|action] [--connection-id | -c ] ``` +> **Deprecated alias:** `ms app add connector` is the former name of this command. It still works +> but is **deprecated** — prefer `ms app add data-source` (same handler and flags). + When you run it, the CLI resolves a connection for `` as follows: **Interactive (default, a TTY is attached):** @@ -39,7 +42,7 @@ need it to bypass the picker or to script a non-interactive run. ### Dataverse is different The tabular Dataverse connector (`--connector dataverse`) doesn't use the connection-id model — -`ms app add connector --connector dataverse --as table --table ` resolves the active +`ms app add data-source --connector dataverse --as table --table ` resolves the active environment's Dataverse automatically. No `--connection-id` is required (or accepted). (The separate `shared_commondataserviceforapps` connector instead pairs `--table` with `--dataverse-environment-id`.) diff --git a/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md b/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md index 540e9c9..78eaf8b 100644 --- a/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md @@ -1,6 +1,6 @@ --- name: add-azuredevops -description: Adds Azure DevOps by delegating to `/add-connector` with `api-id=shared_visualstudioteamservices` and action mode. Use when adding Azure DevOps integration. +description: Adds Azure DevOps by delegating to `/add-data-source` with `api-id=shared_visualstudioteamservices` and action mode. Use when adding Azure DevOps integration. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add Azure DevOps (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_visualstudioteamservices` - `mode`: `action` diff --git a/plugins/microsoft-managed-apps/skills/add-connector/SKILL.md b/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md similarity index 87% rename from plugins/microsoft-managed-apps/skills/add-connector/SKILL.md rename to plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md index a314010..21f87a2 100644 --- a/plugins/microsoft-managed-apps/skills/add-connector/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md @@ -1,6 +1,6 @@ --- -name: add-connector -description: Canonical add flow for Microsoft Managed Apps. Use when adding any connector through `ms app add connector` (with `--as table` or `--as action`), or when the user wants help discovering which connector / api-id to use. +name: add-data-source +description: Canonical add flow for Microsoft Managed Apps. Use when adding any data source through `ms app add data-source` (with `--as table` or `--as action`), or when the user wants help discovering which connector / api-id to use. user-invocable: true allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, Skill model: sonnet @@ -10,7 +10,7 @@ model: sonnet **Reference:** [connector-reference.md](${CLAUDE_PLUGIN_ROOT}/shared/connector-reference.md) — Inline connection creation, Grep-first for large generated files. -# Add Connector (Canonical) +# Add Data Source (Canonical) This is the **single implementation** for all connector-binding skills. @@ -47,8 +47,8 @@ Additional by mode: - `table`: `dataset`, `table` -> **SQL stored procedures:** the CLI has no `ms app add procedure` command and `ms app add connector` -> does not accept `--sql-stored-procedure`. You can still add the SQL connector as a table +> **SQL stored procedures:** the CLI has no `ms app add procedure` command and `ms app add data-source` +> does not accept `--sql-stored-procedure`. You can still add the SQL data source as a table > (`--connector shared_sql --as table --dataset --table `), but binding a specific > stored procedure is not currently supported. @@ -89,19 +89,22 @@ If the caller is a wrapper skill, use wrapper presets as defaults and only ask f ### Step 3: Execute Add Command -All modes use the single `ms app add connector` command; `--as` chooses table vs action. The +All modes use the single `ms app add data-source` command; `--as` chooses table vs action. The connector is passed via `--connector` (there is **no** `--api-id` flag). +> **Deprecated alias:** `ms app add connector` still works but is **deprecated** — prefer +> `ms app add data-source`. Both share the same handler and flags. + **Action mode** ```bash -$BIN app add connector --connector --as action +$BIN app add data-source --connector --as action ``` **Table mode** ```bash -$BIN app add connector --connector --as table --dataset "" --table "" +$BIN app add data-source --connector --as table --dataset "" --table "
" ``` The CLI resolves a connection inline (interactive picker, or `--connection-id ` / `-c ` @@ -110,7 +113,7 @@ available connections and then errors. Dataverse (`--connector dataverse --as ta `--connection-id`. See [connector-reference.md](${CLAUDE_PLUGIN_ROOT}/shared/connector-reference.md). > **SQL stored procedures** have no `ms app add procedure` command and `--sql-stored-procedure` is not -> accepted by `ms app add connector`; binding a specific stored procedure is not currently supported. +> accepted by `ms app add data-source`; binding a specific stored procedure is not currently supported. ### Step 4: Build diff --git a/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md b/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md index ab1a09a..c91a7eb 100644 --- a/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md @@ -1,6 +1,6 @@ --- name: add-dataverse -description: Adds Dataverse by delegating to `/add-connector` with `api-id=dataverse` and table mode. Use when binding Dataverse tables. +description: Adds Dataverse by delegating to `/add-data-source` with `api-id=dataverse` and table mode. Use when binding Dataverse tables. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: opus @@ -10,11 +10,11 @@ model: opus # Add Dataverse (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `dataverse` - `mode`: `table` diff --git a/plugins/microsoft-managed-apps/skills/add-dataverse/references/api-authentication-reference.md b/plugins/microsoft-managed-apps/skills/add-dataverse/references/api-authentication-reference.md index 17c5205..121b06d 100644 --- a/plugins/microsoft-managed-apps/skills/add-dataverse/references/api-authentication-reference.md +++ b/plugins/microsoft-managed-apps/skills/add-dataverse/references/api-authentication-reference.md @@ -2,7 +2,7 @@ Direct Dataverse Web API access for table / schema management. Uses Azure CLI authentication (`az account get-access-token`). -The `ms app add connector --connector dataverse --as table --table ` flow does NOT use this — Dataverse table *binding* goes through the CLI and the active `ms` auth context. This reference is for the schema-management path (`add-dataverse` Step 3) where the skill talks to the Dataverse Web API directly to create / extend tables before binding them. +The `ms app add data-source --connector dataverse --as table --table ` flow does NOT use this — Dataverse table *binding* goes through the CLI and the active `ms` auth context. This reference is for the schema-management path (`add-dataverse` Step 3) where the skill talks to the Dataverse Web API directly to create / extend tables before binding them. ## Prerequisites diff --git a/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md b/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md index 05e6b0f..7fe909a 100644 --- a/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md @@ -1,6 +1,6 @@ --- name: add-excel -description: Adds Excel Online (Business) by delegating to `/add-connector` with `api-id=shared_excelonlinebusiness` and table mode. Use when binding Excel tables. +description: Adds Excel Online (Business) by delegating to `/add-data-source` with `api-id=shared_excelonlinebusiness` and table mode. Use when binding Excel tables. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add Excel Online (Business) (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_excelonlinebusiness` - `mode`: `table` diff --git a/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md b/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md index 087c607..050af74 100644 --- a/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md @@ -1,6 +1,6 @@ --- name: add-mcscopilot -description: Adds Microsoft Copilot Studio by delegating to `/add-connector` with `api-id=microsoftcopilotstudio` and action mode. Use when integrating Copilot Studio agents. +description: Adds Microsoft Copilot Studio by delegating to `/add-data-source` with `api-id=microsoftcopilotstudio` and action mode. Use when integrating Copilot Studio agents. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add Microsoft Copilot Studio (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `microsoftcopilotstudio` - `mode`: `action` diff --git a/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md b/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md index 69506c4..e91f623 100644 --- a/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md @@ -1,6 +1,6 @@ --- name: add-office365 -description: Adds Office 365 Outlook by delegating to `/add-connector` with `api-id=shared_office365` and action mode. Use when integrating Outlook mail/calendar. +description: Adds Office 365 Outlook by delegating to `/add-data-source` with `api-id=shared_office365` and action mode. Use when integrating Outlook mail/calendar. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add Office 365 Outlook (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_office365` - `mode`: `action` diff --git a/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md b/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md index b4c7a1c..e40d320 100644 --- a/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md @@ -1,6 +1,6 @@ --- name: add-onedrive -description: Adds OneDrive for Business by delegating to `/add-connector` with `api-id=shared_onedriveforbusiness` and action mode. Use when integrating OneDrive files. +description: Adds OneDrive for Business by delegating to `/add-data-source` with `api-id=shared_onedriveforbusiness` and action mode. Use when integrating OneDrive files. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add OneDrive for Business (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_onedriveforbusiness` - `mode`: `action` diff --git a/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md b/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md index 8eea47d..4938f1c 100644 --- a/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md @@ -1,6 +1,6 @@ --- name: add-sharepoint -description: Adds SharePoint Online by delegating to `/add-connector` with `api-id=shared_sharepointonline` and table mode. Use when binding SharePoint lists/libraries. +description: Adds SharePoint Online by delegating to `/add-data-source` with `api-id=shared_sharepointonline` and table mode. Use when binding SharePoint lists/libraries. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: opus @@ -10,11 +10,11 @@ model: opus # Add SharePoint Online (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_sharepointonline` - `mode`: `table` diff --git a/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md b/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md index d7b7eae..55c13cf 100644 --- a/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md +++ b/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md @@ -127,7 +127,7 @@ await SharePointOnlineService.PatchItem({ ## Generated Service Patterns -After running `ms app add connector --connector shared_sharepointonline --as table --dataset "" --table ""`, the generated `SharePointOnlineService.ts` provides methods that work across all bound lists. The `dataset` (site URL) and `table` (list name) parameters select which list to operate on: +After running `ms app add data-source --connector shared_sharepointonline --as table --dataset "" --table ""`, the generated `SharePointOnlineService.ts` provides methods that work across all bound lists. The `dataset` (site URL) and `table` (list name) parameters select which list to operate on: ```typescript import { SharePointOnlineService } from "./SharePointOnlineService"; diff --git a/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md b/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md index 55dbe3b..cc837ab 100644 --- a/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md @@ -1,6 +1,6 @@ --- name: add-teams -description: Adds Microsoft Teams by delegating to `/add-connector` with `api-id=shared_teams` and action mode. Use when integrating Teams messaging. +description: Adds Microsoft Teams by delegating to `/add-data-source` with `api-id=shared_teams` and action mode. Use when integrating Teams messaging. user-invocable: true allowed-tools: Read, AskUserQuestion, Skill model: sonnet @@ -10,11 +10,11 @@ model: sonnet # Add Teams (Wrapper) -This skill is a thin wrapper. Use `/add-connector` as the single implementation path. +This skill is a thin wrapper. Use `/add-data-source` as the single implementation path. ## Delegation contract -Invoke `/add-connector` with: +Invoke `/add-data-source` with: - `api-id`: `shared_teams` - `mode`: `action` diff --git a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md index 372a4a9..b827e56 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md @@ -95,7 +95,7 @@ Once you have their description: 2. **Ask about data.** Focus on what the app needs to do, not specific technologies: - "What data does your app need to work with?" - "Does it need to search existing information, manage its own data, or both?" - - Based on the answers, identify the connector(s) and the matching `/add-*` skill (or `/add-connector` with an api-id) that will be invoked in Step 8. Capture **all** info those skills will need (connection IDs, table/list names, api-id, environment URL, etc.) — you will run them yourself, not hand them off. + - Based on the answers, identify the connector(s) and the matching `/add-*` skill (or `/add-data-source` with an api-id) that will be invoked in Step 8. Capture **all** info those skills will need (connection IDs, table/list names, api-id, environment URL, etc.) — you will run them yourself, not hand them off. 3. **Ask about UI:** key screens, layout, interactions, theme preference. Capture enough detail to actually generate the components in Step 9. 4. Resolve all ambiguity now — easier than re-planning mid-scaffold. The user should approve the plan once and not be asked to approve sub-steps later. @@ -193,14 +193,14 @@ Detect the trap by matching `Authentication failed for 'https://...d.environment For every connector identified in Step 3 / Step 4, invoke the matching skill **now**, in this session, before any UI code is generated: - A specific `/add-*` skill when one exists (`/add-dataverse`, `/add-sharepoint`, `/add-excel`, `/add-office365`, `/add-teams`, `/add-onedrive`, `/add-azuredevops`, `/add-mcscopilot`). -- `/add-connector` (with api-id) for anything else. +- `/add-data-source` (with api-id) for anything else. Run them sequentially. After each one: - Confirm the typed services were generated under `src/` (the add-skills regenerate TypeScript clients). - Capture the connection ID + service path so Step 9 can import them. -**Forward all captured context to each sub-skill so its own gather-info prompts are suppressed.** The per-service skills (`/add-dataverse`, `/add-sharepoint`, etc.) and `/add-connector` each have their own prompt sequences (pick connection, pick table/list/site, choose api-id, etc.). The plan you got the user to approve in Step 4 already contains those answers, so pass them through as `$ARGUMENTS` (or whatever invocation surface is available) when dispatching: api-id, connection ID or name, table/list/site identifiers, environment URL, and the project root. If a sub-skill still needs an input you didn't capture, that's a Step 4 gap — go back and ask the user once, then update the plan, rather than letting the sub-skill ask interactively. +**Forward all captured context to each sub-skill so its own gather-info prompts are suppressed.** The per-service skills (`/add-dataverse`, `/add-sharepoint`, etc.) and `/add-data-source` each have their own prompt sequences (pick connection, pick table/list/site, choose api-id, etc.). The plan you got the user to approve in Step 4 already contains those answers, so pass them through as `$ARGUMENTS` (or whatever invocation surface is available) when dispatching: api-id, connection ID or name, table/list/site identifiers, environment URL, and the project root. If a sub-skill still needs an input you didn't capture, that's a Step 4 gap — go back and ask the user once, then update the plan, rather than letting the sub-skill ask interactively. The intent of this step is no per-connector approval prompts: the approved plan from Step 4 covers them. If a sub-skill fails (auth, missing connection, wrong api-id), surface the error verbatim and stop; do not silently proceed with a half-wired app. diff --git a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md index ff8102b..39d4bfa 100644 --- a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md @@ -77,7 +77,7 @@ Output is a list of operation names and their summaries. Use it to confirm an ap ## When the user wants a connection ID -The CLI creates or reuses connections **inline** while `ms app add connector` runs — you don't +The CLI creates or reuses connections **inline** while `ms app add data-source` runs — you don't need a connection ID to start an `/add-*` skill. Two cases need a bit more care: - **`--non-interactive`**: the CLI can't open a browser or run the SSO flow, so it can't create @@ -90,6 +90,6 @@ need a connection ID to start an `/add-*` skill. Two cases need a bit more care: - **SQL (`shared_sql`)**: each SQL connection points at a different database, so when scripting non-interactively pass the `--connection-id` for the right database explicitly. -To **create** a connection that doesn't exist yet, just run `ms app add connector` interactively: +To **create** a connection that doesn't exist yet, just run `ms app add data-source` interactively: the CLI handles consent + sign-in (silent SSO, or a browser dialog), creates the connection, prints its Connection ID, and binds it — no maker portal needed. From d73a6a9cd9693ccc9136adb99442e2eb8fdc2adb Mon Sep 17 00:00:00 2001 From: Esteban Chavez Date: Wed, 24 Jun 2026 10:57:06 -0700 Subject: [PATCH 2/3] Fix list-connectors description: available connectors + org policy status Address PR review: the '/list-connectors' line was false. 'ms connector list' shows available connectors and whether each is allowed or blocked by org policy (verified against CLI ListConnectors.ts Policy Status column). Correct the connector decision guide line and document the policy-status view in the list-connectors skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../shared/connector-decision-guide.md | 2 +- .../skills/list-connectors/SKILL.md | 26 ++++++++++++++----- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md index c4dab27..2f9a36a 100644 --- a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md +++ b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md @@ -24,7 +24,7 @@ ms connector list-actions --connector shared_office365 --search Mail ### **Via Plugin Skills** - **`/add-data-source`** — Generic connector skill. Ask for a keyword ("salesforce", "slack", "jira", "workiq") and it will search, present options, and add the connector. -- **`/list-connections`** — View connectors already bound to your app, or explore operations on a specific connector +- **`/list-connectors`** — View available connectors and whether they are blocked or allowed by your organization ### **Via Specific Skills** diff --git a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md index 39d4bfa..26610e8 100644 --- a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md @@ -1,6 +1,6 @@ --- name: list-connectors -description: Lists connectors reachable in the active environment and the connection-bound data sources already wired into a Microsoft App. Use when discovering connectors and their operations before adding data sources. +description: Lists connectors available in the active environment — including whether each is allowed or blocked by your organization's policy — plus the connection-bound data sources already wired into a Microsoft App. Use when discovering connectors and their operations before adding data sources. user-invocable: true allowed-tools: Read, Bash, AskUserQuestion model: sonnet @@ -10,10 +10,11 @@ model: sonnet # List Connectors -Two read-only views, depending on what the user is asking: +Three read-only views, depending on what the user is asking: -1. **What data sources are already bound to *this* app?** → `ms app show --json` (inspects `ms.config.json`). -2. **What connectors are reachable in the active environment?** → `ms connector list-actions --connector ` for a specific connector, or browse the public reference for available api-ids. +1. **What connectors are available, and which are allowed vs blocked by org policy?** → `ms connector list` (lists every connector in the environment with a `Policy Status` of `Allowed` or `Blocked`). +2. **What data sources are already bound to *this* app?** → `ms app show --json` (inspects `ms.config.json`). +3. **What operations does a specific connector expose?** → `ms connector list-actions --connector `, or browse the public reference for available api-ids. ## Workflow @@ -36,10 +37,23 @@ $BIN auth status # confirm the active UPN Ask (or infer): +- **available**: list connectors available in the environment and whether each is allowed or blocked by org policy (`ms connector list`). - **app**: enumerate data sources already wired into the current project (requires `ms.config.json` in cwd). - **connector**: list the operations exposed by a specific connector — useful when planning an `/add-*` invocation. -### Step 4a: App-bound data sources +### Step 4a: Available connectors + policy status + +```bash +BIN=ms +$BIN connector list [--search ] +``` + +Output is a table of connectors with a `Policy Status` column (`Allowed` or `Blocked`) and a +`Tabular` column. Use it to confirm a connector is available and **not blocked by your +organization's DLP policy** before planning an `/add-*` invocation. Add `--search ` to +narrow a large catalog. + +### Step 4b: App-bound data sources ```bash test -f ms.config.json || { echo "Not in a Microsoft App workspace."; exit 1; } @@ -56,7 +70,7 @@ Parse the response for the data-source list and print a summary: Use this to spot drift (e.g., `ms.config.json` claims a data source that no longer exists in the env). -### Step 4b: Discover operations on a connector +### Step 4c: Discover operations on a connector The CLI prompts for / creates connections inline when an `/add-*` skill runs, so users rarely need to look up connection IDs ahead of time. The more useful query is "what can this connector do?": From 49e40df2f38c075d149b651054d4370613b62b16 Mon Sep 17 00:00:00 2001 From: Esteban Chavez Date: Wed, 24 Jun 2026 10:57:59 -0700 Subject: [PATCH 3/3] Fix remaining stale /list-connections reference -> /list-connectors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../microsoft-managed-apps/shared/connector-decision-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md index 2f9a36a..6c07c60 100644 --- a/plugins/microsoft-managed-apps/shared/connector-decision-guide.md +++ b/plugins/microsoft-managed-apps/shared/connector-decision-guide.md @@ -270,7 +270,7 @@ This skill handles ANY connector, including those not listed in this guide. When 3. **If uncertain about availability**: - Check Microsoft connectors documentation: https://learn.microsoft.com/en-us/connectors/ - - Use `/list-connections` skill to browse available connectors + - Use `/list-connectors` skill to browse available connectors **This guide covers the most common cases, but `/add-data-source` works with any Microsoft connector — not just the 10 listed above.**