Adding general connector namespace skill and refactored sandboxes skill#124
Merged
Conversation
New skill under Skills/General/azure-connectorgateway providing a sandbox-agnostic playbook for managing Microsoft.Web connector gateways, connections, trigger configs, and MCP server configs. The customer-owned callback URL and notification authentication are user-provided; the skill never assumes a sandbox runtime. Trigger types covered: connector-event, Recurrence, SlidingWindow. MCP focus is on ManagedMcpServer; HostedMcpServer is referenced briefly. Reuses dynamic-values resolution and consent flow from the existing Skills/Sandbox/azure-connectorgateway skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand mcp-server-config.md with a full "Resolving dynamic parameters for MCP config" section that covers all four x-ms-dynamic-* kinds, the cascading-dependency pattern (e.g., channel depends on team), dynamic schema for body shapes, and a rule of thumb for what to bake into userParameters vs leave LLM-supplied. Mirror the same triage in SKILL.md Step 4B. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
User correction: 'audience is not a required field' on ManagedServiceIdentity callback auth. Updated the skill to treat it as optional and to always ASK the user whether to set one: - notification-authentication.md sec 4: audience-less example first, audience-with-value second; validation rules say 'optional, omit for non-AAD callbacks'. - SKILL.md auth-type table + STOP-and-ask list updated. - trigger-setup.md example shows audience commented out + gotcha table updated. - gotchas.md row replaced (was 'audience required', now 'fabricated audience -> always ask'). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
If the user doesn't provide an MSI audience, default to https://management.azure.com/ (a real AAD-protected resource — ARM). Never use the callback URL as the audience. Updated: - notification-authentication.md sec 4: workflow (ask -> use / default to ARM), examples lead with default-audience pattern, validation rule reverted to 'audience required, default if not given'. - SKILL.md auth-type table, rules table, STOP-and-ask list. - trigger-setup.md example shows default audience + comment, gotcha table updated. - gotchas.md row updated to reflect default-audience behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
MCP server config access policies require BOTH a principal.type of 'ActiveDirectory' AND a sibling properties.principalType of 'User' or 'Group' (the shared ActiveDirectory enum is insufficient here). The access-policy resource name in the URL must equal the caller's objectId (case-insensitive). MIs/service principals are not supported as MCP principals - only Entra users and groups. Discovered while creating servicebus-send-aigateway MCP config on apseth-msi gateway. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The MCP runtime validates that every required Swagger parameter — including required body sub-properties — is declared in either userParameters (fixed value) or agentParameters (caller-supplied JSON Schema). Skipping this triage causes runtime failures like: The API operation 'SendEmailV2' is missing required property 'emailMessage/To'. Changes: - mcp-server-config.md: rewrote the parameter section to cover userParameters vs agentParameters, body decomposition (one agentParameter named after the body root with a nested object schema), and a STOP-and-ask triage workflow per parameter. Added the ConvertTo-Json depth gotcha and updated the PUT example to show both arrays. - SKILL.md: added the per-parameter triage rule + STOP-and-ask entry; updated Step 4B to enumerate body sub-properties and triage each one; updated the PUT example to include agentParameters. - gotchas.md: added rows for the "missing required property" runtime error and the ConvertTo-Json depth truncation symptom. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The trigger wizard (Cascade `serializeTriggerParams`) aggregates every body- sourced leaf — including dotted nested paths — into ONE `parameters[]` entry whose name is literally `"body"` (independent of the Swagger body parameter's own name, e.g. Teams declares it as `requestBody`) and whose `value` is the nested object. Non-body dotted leaves group under their root segment via `groupDottedEntriesToNestedObjects`. The skill previously only showed flat scalar examples and would have produced broken `body.<path>` dotted entries. Also calls out the wrapper-name asymmetry between MCP and triggers: - MCP: body wrapper name = Swagger body param's own name (e.g. `emailMessage`). - Trigger: body wrapper name = literal `"body"`, always. Changes: - trigger-setup.md: added §2a (per-parameter enumeration + STOP-and-ask) and §2b (wire-shape rules with a nested-body example and an anti-pattern). Bumped the PUT example to ConvertTo-Json -Depth 20. Added Common-Mistakes rows for flat dotted body names, wrong wrapper name, and depth truncation. - SKILL.md: rewrote Step 4A item 2 to spell out body decomposition and the literal `"body"` wrapper. Updated the rules table entry for "Trigger body schema" to document the wrapper convention. Clarified MCP triage rule to highlight the wrapper-name difference. - gotchas.md: added rows for "body leaves visible as flat dotted params" and "trigger body wrapper named after the Swagger param". Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both MCP and trigger configs need to build nested-object payloads from per-leaf user answers. The previous commit covered the rules and shapes but didn't walk through the Swagger → user answers → assembled wire entry flow. Add concrete worked examples in both docs: - trigger-setup.md §2c: Teams PostMessageToChannelV3 → user picks team/channel, types message content, picks contentType → assembled as ONE entry named "body" (literal) with the recipient/messageBody sub-objects. - mcp-server-config.md "Worked example": SharePoint PostItem → user splits Title (agent), Status (user="Open"), Assignee.Email (agent), Tags (agent) → assembled as paired userParameters/agentParameters entries with the same root name "item" (Swagger body param's own name). The two examples make the user-vs-agent / fixed-vs-dynamic distinction and the wrapper-name asymmetry (literal "body" for triggers vs Swagger name for MCP) concrete. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Cascade portal has renamed the user-facing term to "Connector Namespace"
(see CreateConnectorNamespacePanel.tsx, ConnectorNamespaceIcon.tsx, the
CONNECTOR_NAMESPACE_REGIONS_* constants, etc.). Update the skill to match.
What changed:
- Folder: Skills/General/azure-connectorgateway/ ->
Skills/General/azure-connectornamespace/ (git mv preserves history).
- SKILL.md frontmatter: name -> azure-connectornamespace; description
rewritten with "Connector Namespace"; kept "connector gateway" as a
legacy discovery keyword so users searching the old term still hit
this skill.
- All prose in SKILL.md + references/*.md: "Connector Gateway"/"gateway"
-> "Connector Namespace"/"namespace" with proper case handling.
- Variable placeholders: {gw} -> {namespace}, $gw -> $namespace,
$gwBody -> $namespaceBody, $gwMi -> $namespaceMi, $gwTenant ->
$namespaceTenant.
- Example resource names: gateway-acl -> namespace-acl, tutorial-gw ->
tutorial-ns, <gateway-host> -> <namespace-host>.
- Added a "Naming note" section on SKILL.md explaining the rename and
what stayed unchanged.
- Added a gotchas.md row clarifying display name vs API strings.
What stayed unchanged (API contracts):
- ARM resource type: Microsoft.Web/connectorGateways (URL segment is
the live REST API path).
- Sandbox-group property: gatewayConnections[].
- RBAC string: Microsoft.Web/connectorGateways/*.
- Cascade source folder reference: src/.../ConnectorGateways/.
- Sandbox companion skill folder: Skills/Sandbox/azure-connectorgateway/
(separate skill, out of scope for this rebrand).
- Test class name: AIGatewayApiTests_NotificationAuthValidation_*.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the repo’s “skills” packaging by introducing a new generic azure-connectornamespace skill (callback-agnostic + MCP server config guidance) and refactoring/renaming the ACA sandbox skill to align with the “Connector Namespace” terminology and new plugin layout under plugin/.
Changes:
- Added a new generic connector-namespace skill under
plugin/skills/connectorswith detailed reference docs (triggers, dynamic values, MCP server configs, consent, etc.). - Renamed/refactored the ACA sandbox skill to
azure-connectornamespace-aca-sandbox, including updated regional sandbox data-plane callback URLs. - Moved plugin descriptors under
plugin/and updated marketplace + root README to point to the new plugin/skill locations.
Reviewed changes
Copilot reviewed 33 out of 39 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| Skills/Sandbox/README.md | Removed legacy skills README under old Skills/Sandbox layout. |
| README.md | Updated install instructions and skill links to the new plugin/skill structure. |
| plugin/skills/connectors/version.json | Added version metadata for the new generic connectors skill. |
| plugin/skills/connectors/SKILL.md | Added the main “generic connector namespace” skill instructions and rules. |
| plugin/skills/connectors/README.md | Added skill-level README for the generic connectors skill. |
| plugin/skills/connectors/references/prerequisites.md | Added prerequisites for the generic skill workflows. |
| plugin/skills/connectors/references/quickstart.md | Added quick-start commands for listing namespaces/connections/triggers/MCP configs. |
| plugin/skills/connectors/references/connections.md | Added detailed connection CRUD + ACL documentation. |
| plugin/skills/connectors/references/consent.md | Added OAuth consent link generation + verification instructions. |
| plugin/skills/connectors/references/direct-api.md | Added dynamicInvoke direct API call guidance and pitfalls. |
| plugin/skills/connectors/references/dynamic-values.md | Added detailed x-ms-dynamic-* resolution algorithms. |
| plugin/skills/connectors/references/notification-authentication.md | Added callback authentication reference (incl. MSI audience guidance). |
| plugin/skills/connectors/references/trigger-setup.md | Added trigger-config creation guidance, including parameter wiring rules. |
| plugin/skills/connectors/references/trigger-flow.md | Added trigger lifecycle/architecture overview. |
| plugin/skills/connectors/references/tutorial.md | Added end-to-end tutorials for recurrence and connector-event triggers. |
| plugin/skills/connectors/references/gotchas.md | Added troubleshooting guidance for common trigger/MCP/dynamicInvoke issues. |
| plugin/skills/aca-sandboxes/version.json | Updated ACA sandbox skill version metadata. |
| plugin/skills/aca-sandboxes/SKILL.md | Renamed/refactored ACA sandbox skill to connector-namespace terminology + regional callback host guidance. |
| plugin/skills/aca-sandboxes/README.md | Added ACA sandbox skill README under new plugin structure. |
| plugin/skills/aca-sandboxes/scripts/trigger-getting-started.py | Updated terminology in script help/docs to match connector naming. |
| plugin/skills/aca-sandboxes/references/prerequisites.md | Added ACA sandbox prerequisites doc under new layout. |
| plugin/skills/aca-sandboxes/references/quickstart.md | Updated quickstart to point to the new tutorial doc. |
| plugin/skills/aca-sandboxes/references/tutorial-welcome-emailer.md | Updated tutorial terminology from gateway to connector. |
| plugin/skills/aca-sandboxes/references/handler-guide.md | Added handler development/deployment guidance for sandboxes. |
| plugin/skills/aca-sandboxes/references/runtime-url-examples.md | Added runtime URL examples for calling connectors from sandboxes. |
| plugin/skills/aca-sandboxes/references/direct-api.md | Updated example text to “Connector” terminology. |
| plugin/skills/aca-sandboxes/references/consent.md | Added OAuth consent instructions for ACA sandbox skill workflows. |
| plugin/skills/aca-sandboxes/references/dynamic-values.md | Added dynamic-values resolution guidance for ACA sandbox workflows. |
| plugin/skills/aca-sandboxes/references/trigger-setup.md | Updated trigger callback URL guidance to require regional sandbox data-plane host. |
| plugin/skills/aca-sandboxes/references/trigger-flow.md | Updated trigger flow diagram text to “Connector” terminology. |
| plugin/skills/aca-sandboxes/references/gateway-connections.md | Updated prose to reflect connector-namespace naming (still connectorGateways ARM type). |
| plugin/skills/aca-sandboxes/references/gotchas.md | Expanded troubleshooting note about regional sandbox data-plane URLs. |
| plugin/.plugin/plugin.json | Added new Copilot CLI plugin descriptor under plugin/. |
| plugin/.claude-plugin/plugin.json | Added new Claude plugin descriptor under plugin/. |
| marketplace.json | Updated marketplace entry to point at ./plugin and new skill folders. |
| .plugin/plugin.json | Removed legacy root-level Copilot CLI plugin descriptor. |
| .claude-plugin/plugin.json | Removed legacy root-level Claude plugin descriptor. |
| .github/ISSUE_TEMPLATE/portal_bug.yml | Updated portal issue template text to reflect “Connector” naming. |
Comments suppressed due to low confidence (3)
plugin/skills/aca-sandboxes/SKILL.md:121
- The terminology is inconsistent: you ask about an existing "connector" but then immediately say to ask for the "gateway" name. This is confusing, especially since this skill is now framed around connector namespaces (ARM
connectorGateways).
plugin/skills/aca-sandboxes/SKILL.md:121 - The terminology is inconsistent: you ask about an existing "connector" but then immediately say to ask for the "gateway" name. This is confusing, especially since this skill is now framed around connector namespaces (ARM
connectorGateways).
plugin/skills/aca-sandboxes/SKILL.md:121 - The terminology is inconsistent: you ask about an existing "connector" but then immediately say to ask for the "gateway" name. This is confusing, especially since this skill is now framed around connector namespaces (ARM
connectorGateways).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…acy resource type) Line 93 of plugin/skills/connectors/SKILL.md showed `Microsoft.Web/connectorNamespaces` as the ARM base, but the underlying ARM resource type is still `Microsoft.Web/connectorGateways` (legacy URL segment kept for backwards compatibility, as explicitly stated five lines higher on line 38 of the same file and in every actual `az rest` URL in this skill). The mismatched prose came from an accidental over-rebrand in 8a4fb14 (display-only rebrand commit). Restored to match the rest of the doc and the actual ARM resource type. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three places in the connectors skill leaked internal repo paths (`Cascade.Portal.Client/...`) that don't exist in this public repo and aren't actionable for readers. Rewrote each to describe the behavior in user-facing terms: - `plugin/skills/connectors/SKILL.md` line 35-37: `Cascade portal rename - see Cascade.Portal.Client/src/components/ CreateConnectorNamespacePanel.tsx` -> `portal rename`. - `plugin/skills/connectors/references/gotchas.md` line 7: `Cascade portal rename` -> `portal rename`. - `plugin/skills/connectors/references/trigger-setup.md` line 165-166: the `Cascade's serializeTriggerParams` reference with the full TS file path -> a sentence describing what the portal trigger wizard does before PUT, without naming the implementation file. Caught by Copilot reviewer on PR #124. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
rarayudu
approved these changes
Jun 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adding general connector namespace skill and refactored sandboxes skill
Linked issue
Type of change
Checklist