📋 Shared Instructions: shared-instructions.md — Cross-cutting concerns.

Reference: connector-reference.md — Inline connection creation, Grep-first for large generated files.

Reference: allowed-actions.md — Shared connections must declare allowedActions before deploy (Step 4).

Add Data Source (Canonical)

This is the single implementation for all connector-binding skills.

Delegation model:

• Specialized /add-* skills (e.g., /add-office365, /add-workiq) delegate to this skill with presets
• If this skill is called from a wrapper, do not delegate back
• If this skill is called directly, complete the workflow without delegation

After the connector is added:

• If invoked via a specialized skill → Refer to that specialized skill's documentation for usage patterns (it was already provided)
• If invoked directly → Identify which specialized skill matches your use case and refer to its documentation for:
  • Correct import paths for generated services
  • Best practices for using the connector
  • Common patterns and implementation examples
  • Error handling guidance

This ensures developers have complete context for implementing features, not just adding the connector.

Workflow

1. Verify workspace + auth.
2. Resolve api-id (discover via ms connector list if the user didn't supply one), mode, and required arguments.
3. Run the matching ms app add ... command.
4. Check for a shared connection and declare allowedActions if so.
5. Run npm run build.
6. Record the binding in memory-bank.md if present.

Step 1: Verify Project + Env

test -f ms.config.json || { echo "Not in a Microsoft App workspace."; exit 1; }
BIN=ms
$BIN auth status

Step 2: Resolve Inputs

Collect:

• api-id (required — see resolution order below). Passed to the CLI via --connector <api-id>.
• mode = action | table (controls the --as flag). There is no procedure mode — binding a specific SQL stored procedure is not exposed by the current CLI (see note below).
• connection-id (optional interactive, required for non-interactive where applicable)

Additional by mode:

• table: dataset, table. Dataverse uses a table logical name without dataset, plus an optional dataverse-environment-id.

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 <db> --table <tbl>), but binding a specific stored procedure is not currently supported.

2a. Resolve api-id

Try sources in this order; stop at the first one that yields a value:

1. Wrapper preset. If invoked by a specialized /add-* skill (see "Common Presets" below), use the preset api-id and skip discovery.
2. Caller-supplied. If $ARGUMENTS includes an api-id (e.g., api-id=shared_office365), use it verbatim.
3. User-supplied verbatim string. If the user already typed an api-id (anything matching the shared_* / microsoftcopilotstudio shape, or a string they explicitly call an api-id), use it. Apply the Dataverse rule below to ambiguous service names.

4. Discovery via ms connector list. Do not ask the user to type an api-id from memory. Instead:

   a. Ask one question: "Which connector do you need? (a short keyword like 'teams', 'sql', 'sharepoint', 'salesforce' is fine — I'll search the catalog.)" Capture the keyword as {term}.

   b. Search the catalog:

   $BIN connector list --search "<term>"

   Parse the output into a short table (display name + api-id). If the result set is large (more than ~10 rows), narrow with a more specific term and re-run rather than dumping everything.

   c. Present the candidates to the user via AskUserQuestion with the display names as choices (and api-ids in parentheses for transparency). Map their selection back to the api-id; never ask them to retype it.

   d. If ms connector list --search "<term>" returns no results, fall back to ms connector list with no filter, surface a representative slice, and ask the user to refine the term. Do not proceed with a guessed api-id.

5. Validation. Once an api-id is chosen, confirm it's real before spending a build cycle on it: $BIN connector list-actions --connector <api-id> --search "" should succeed. If the CLI replies that the api-id is unknown, drop back to step 4 — don't keep retrying with the same value.

Dataverse intent hint

For Dataverse requests, use shared_commondataserviceforapps. Treat dataverse and "Microsoft Dataverse" as ambiguous service names, not exact connector IDs. Both the current connector and the older shared_commondataservice connector use that display name. Use the older connector only when the user explicitly requests it.

Use table mode for a fixed, existing table. Use action mode when users choose the organization URL or entity-set name inside the app. Preserve the caller's selected mode. Do not ask for a fixed table in action mode.

Work IQ intent hint

When user intent is about knowledge retrieval / grounded Microsoft 365 search summaries (for example: "analyze M365 content", "search my email and Teams", "knowledge-grounded query"), default to:

• api-id: shared_a365copilotchatmcp
• mode: action

⚠️ IMPORTANT: If the user is adding Work IQ via /add-data-source, ask them to use /add-workiq instead.

Why: Work IQ uses MCP (Model Context Protocol), a stateful protocol that requires special handling. The /add-workiq skill provides:

• Complete McpSession wrapper class (handles session initialization, auto-retry, response parsing)
• Best practices for structuring prompts
• Error handling patterns
• Multi-turn conversation support

Guidance: "I can add the connector, but for Work IQ I recommend using /add-workiq — it provides a production-ready McpSession class and comprehensive patterns to avoid common errors. Would you like to use /add-workiq instead?"

If they insist on /add-data-source, proceed but after adding the connector, refer them to the /add-workiq skill documentation so they understand the McpSession requirement.

2b. Resolve mode

For Dataverse, use the intent rule above. For other api-ids in the "Common Presets" table, use that table's mode. Otherwise ask the user one question, framed by what they want to do:

• "Read or write rows in a tabular store?" → table
• "Trigger an operation (send a message, post a file, list events)?" → action

mode selects the --as flag. Tabular connectors (e.g. SharePoint, SQL) support both; in non-interactive runs --as is required for them. Action-only connectors ignore --as.

If the caller is a wrapper skill, use wrapper presets as defaults and only ask for missing fields.

Step 3: Execute Add Command

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

$BIN app add data-source --connector <api-id> --as action

Table mode (other connectors)

$BIN app add data-source --connector <api-id> --as table --dataset "<dataset>" --table "<table>"

Dataverse table mode

$BIN app add data-source --connector shared_commondataserviceforapps --as table --table "<logical-name>"

Do not pass --dataset. Run once per table. Add --dataverse-environment-id <environment-guid> only when targeting a specific environment. If omitted, the CLI uses the app environment. For runtime-selected organizations and tables, use the action command without --table or --dataverse-environment-id. In interactive action mode, decline the optional prompt to bind a specific Dataverse table.

The CLI resolves connections inline. Pass --connection-id <id> or -c <id> when a specific connection is required. See connector-reference.md for connection selection.

After a Dataverse add, check the new reference in ms.config.json. Its id must be /providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps, unless the user explicitly requested the older connector. Check that the generated service uses that reference. If the binding is wrong, stop and report the mismatch. Do not change only the ID in the config. Regenerate services and update app calls and shared allowedActions when replacing an older binding.

Check required operations with ms connector list-actions --connector shared_commondataserviceforapps --json. For a runtime-selected organization, inspect the *WithOrganization operations and their generated signatures. If policy blocks a required operation, report the restriction. Do not substitute the older connector or bypass policy.

SQL stored procedures have no ms app add procedure command and --sql-stored-procedure is not accepted by ms app add data-source; binding a specific stored procedure is not currently supported.

Step 4: Shared Connection Policy (allowedActions)

Do this before the build, on every add. The CLI writes sharedConnectionId automatically when the connection's auth type is shareable, so this can trigger without the user asking for it — and it doesn't surface as a build error, it surfaces later as a deploy failure.

4a. Read the config back and check the reference that was just written. Node 22+ is a project prerequisite, so this works in bash and PowerShell alike:

node -e '
const fs = require("fs");
const refs = JSON.parse(fs.readFileSync("ms.config.json", "utf8")).connectionReferences || {};
const ok = (a) => Array.isArray(a) && a.length > 0 &&
  a.every((x) => typeof x === "string" && /\S/.test(x));
let bad = 0;
for (const [name, r] of Object.entries(refs)) {
  if (!String(r.sharedConnectionId || "").trim()) continue;
  const t = Object.entries(r.dataSets || {}).flatMap(([d, s]) =>
    Object.entries(s.dataSources || {}).map(([k, v]) => [d + "/" + k, v]));
  if (r.allowedActions !== undefined && !ok(r.allowedActions)) {
    bad++;
    console.log("INVALID connector-level allowedActions: " + name);
  }
  if (t.length) {
    for (const [p, v] of t) if (!ok(v.allowedActions)) { bad++; console.log("MISSING per-table allowedActions: " + name + " -> " + p); }
  } else if (r.allowedActions === undefined) { bad++; console.log("MISSING connector-level allowedActions: " + name); }
}
if (bad) { console.log(bad + " issue(s): fix before deploy"); process.exitCode = 1; } else console.log("OK: all shared references declare allowedActions");
'

If it prints OK, skip to Step 5 — the connection isn't shared, or is already covered.

4b. If it is shared, determine the shape:

4c. Infer least privilege, then confirm. Grep src/ for calls into the generated service. For dataset tables, map read/list to get, create to post, update to patch, and delete to delete. For action references, use the exact invoked operation IDs from ms connector list-actions. Present the inferred list and ask the user to confirm or adjust:

"<reference> is a shared connection, so it needs an action policy before deploy. From the code, I'd declare <inferred>. Anything else it should be allowed to do?"

Never grant the full set just to pass validation.

Deferral — when there is no app code yet. If src/ has no calls into this service because the app hasn't been written yet (the usual case when /create-app invokes this skill before generating the UI), do not guess and do not prompt. Instead:

• Leave allowedActions unset for now. ms app dev does not validate it, so local iteration is unaffected — only ms app pack / ms app deploy do.
• Record the reference as shared, policy pending in memory-bank.md.
• Note it in your summary so the decision happens once the app code exists.

/deploy re-runs this same check as a preflight gate, so a deferred policy is caught before it can reach a failing deploy — not silently forgotten.

4d. Write the confirmed values into ms.config.json (skip when deferring).

Full rules, worked examples, and failure recovery: allowed-actions.md.

Step 5: Build

npm run build

Step 6: Memory Update

If memory-bank.md exists, record api-id, mode, parameters used, and — when the reference is shared — the allowedActions that were agreed, so the next session doesn't re-litigate them.

Common Presets