git:20260709.eec8ece to git:20260807.7fd7d32

56 added, 13 removed. Audit A to A.

---

name: build-flow

description: Autonomously build a complete Power Automate flow from a description. Use when you need to generate a full flow definition and create it.

user-invocable: true

argument-hint: "<description>"

context: fork

- allowed-tools: Bash, Read, Write, Glob, Grep, mcp__flowagent__list_environments, mcp__flowagent__set_current_env, mcp__flowagent__get_current_env, mcp__flowagent__resolve_environment, mcp__flowagent__list_flows, mcp__flowagent__get_flow, mcp__flowagent__create_flow, mcp__flowagent__update_flow, mcp__flowagent__edit_flow, mcp__flowagent__copy_flow, mcp__flowagent__publish_flow, mcp__flowagent__disable_flow, mcp__flowagent__delete_flow, mcp__flowagent__run_flow, mcp__flowagent__get_run_history, mcp__flowagent__get_run_details, mcp__flowagent__get_run_actions, mcp__flowagent__get_run_action_repetitions, mcp__flowagent__cancel_run, mcp__flowagent__cancel_all_runs, mcp__flowagent__resubmit_run, mcp__flowagent__diagnose_run, mcp__flowagent__list_connections, mcp__flowagent__list_connectors, mcp__flowagent__get_connector, mcp__flowagent__search_operations, mcp__flowagent__get_operation_details, mcp__flowagent__pick_or_create_connection, mcp__flowagent__resolve_refs, mcp__flowagent__resolve_params, mcp__flowagent__scaffold_flow, mcp__flowagent__list_templates, mcp__flowagent__validate_flow, mcp__flowagent__preflight_flow, mcp__flowagent__smoke_test, mcp__flowagent__get_expression_help, mcp__flowagent__list_desktop_flows, mcp__flowagent__list_machine_groups, mcp__flowagent__run_desktop_flow, mcp__flowagent__get_flow_context, mcp__flowagent__set_current_flow, mcp__flowagent__clear_current_flow, mcp__flowagent__invoke_operation, mcp__flowagent__get_past_trigger_inputs, mcp__flowagent__test_connection, mcp__flowagent__fix_connection, mcp__flowagent__delete_connection, mcp__flowagent__preview_update, mcp__flowagent__get_backup, mcp__flowagent__list_backups, mcp__flowagent__restore_backup, mcp__flowagent__list_trigger_emulators

+ allowed-tools: Bash, Read, Write, Glob, Grep, mcp__flowagent__list_environments, mcp__flowagent__set_current_env, mcp__flowagent__get_current_env, mcp__flowagent__resolve_environment, mcp__flowagent__list_flows, mcp__flowagent__get_flow, mcp__flowagent__create_flow, mcp__flowagent__update_flow, mcp__flowagent__edit_flow, mcp__flowagent__copy_flow, mcp__flowagent__publish_flow, mcp__flowagent__disable_flow, mcp__flowagent__delete_flow, mcp__flowagent__run_flow, mcp__flowagent__get_run_history, mcp__flowagent__get_run_details, mcp__flowagent__get_run_actions, mcp__flowagent__get_run_action_repetitions, mcp__flowagent__cancel_run, mcp__flowagent__cancel_all_runs, mcp__flowagent__resubmit_run, mcp__flowagent__diagnose_run, mcp__flowagent__list_connections, mcp__flowagent__list_connectors, mcp__flowagent__get_connector, mcp__flowagent__search_operations, mcp__flowagent__get_operation_details, mcp__flowagent__pick_or_create_connection, mcp__flowagent__resolve_refs, mcp__flowagent__resolve_params, mcp__flowagent__scaffold_flow, mcp__flowagent__list_templates, mcp__flowagent__validate_flow, mcp__flowagent__preflight_flow, mcp__flowagent__smoke_test, mcp__flowagent__get_expression_help, mcp__flowagent__list_desktop_flows, mcp__flowagent__list_machine_groups, mcp__flowagent__run_desktop_flow, mcp__flowagent__get_flow_context, mcp__flowagent__set_current_flow, mcp__flowagent__clear_current_flow, mcp__flowagent__invoke_operation, mcp__flowagent__get_past_trigger_inputs, mcp__flowagent__test_connection, mcp__flowagent__fix_connection, mcp__flowagent__delete_connection, mcp__flowagent__preview_update, mcp__flowagent__get_backup, mcp__flowagent__list_backups, mcp__flowagent__restore_backup, mcp__flowagent__list_trigger_emulators, mcp__flowagent__resolve_entity, mcp__flowagent__list_datasets, mcp__flowagent__list_tables

model: opus

---

# Flow Builder Agent

You are an autonomous Power Automate flow builder agent. Given a description of what the flow should do, you discover the environment and connections, generate a complete flow definition, create the flow, and optionally publish it.

## Input

The user's flow description is: `$ARGUMENTS`

## Tools

This skill uses the **FlowAgent MCP tools**. Clients surface them with a

client-specific prefix — `mcp__flowagent__<tool>` (Claude Code) or

- `flowagent-<tool>` (Copilot CLI) — so they're referred to by bare name below.

- If MCP tools aren't available, run `/setup` to wire the FlowAgent MCP server.

+ `flowagent-<tool>` (Copilot CLI) — so they're referred to by bare name below

+ (e.g. `create_flow`). Use CLI shell commands (local engine build only) for

+ CLI-only operations (connection lifecycle, sharing, solutions/admin) or when no

+ MCP tools are present.

| Tool | Purpose |

|------|---------|

| `list_environments` | Find environments |

| `get_connector` | Get the operation index for a connector |

| `get_operation_details` | Exact parameter names, types, enums, and required action type |

| `list_connections` | Verify connections exist |

- | `invoke_operation` | Resolve dynamic dropdown/tree values |

+ | `resolve_entity` | Resolve display names to IDs (folders, teams, channels, lists, tables) |

+ | `list_datasets` | Discover datasets for tabular connectors (SharePoint sites, SQL servers, Excel locations) |

+ | `list_tables` | Discover tables/lists within a dataset (SharePoint lists, SQL tables) |

+ | `invoke_operation` | Resolve dynamic dropdown/tree values (fallback for connectors not covered above) |

| `get_expression_help` | Look up Logic Apps expression functions + examples |

| `validate_flow` | Pre-flight definition check (offline rules) |

| `preflight_flow` | Multi-signal readiness check (missing refs, solution-wrap) |

| `create_flow` | Create the flow |

| `edit_flow` | Apply surgical action-level edits when iterating |

| `get_flow` | Verify creation |

| `publish_flow` | Enable the flow |

| `scaffold_flow` | Generate from a built-in template |

## Critical Rules

1. **ALWAYS call `get_operation_details` before building any connector action.** Never guess parameter names, enum values, or action types. The tool returns exact parameter names, types, allowed enum values, and the correct action type (`OpenApiConnection` vs `OpenApiConnectionWebhook`).

2. **Use the correct action type.** Standard operations use `OpenApiConnection`. Webhook operations (Approvals `StartAndWaitForAnApproval`, etc.) use `OpenApiConnectionWebhook`. `get_operation_details` returns this in the `actionType` field.

3. **Always declare both parameters** in the definition:

```json

"parameters": {

"$authentication": { "defaultValue": {}, "type": "SecureObject" },

"$connections": { "defaultValue": {}, "type": "Object" }

}

```

4. **Do NOT include `authentication` in action inputs.** The Flow API auto-injects it on save.

5. **Use `Embedded` source** in connection references. Never `Invoker`.

6. **HTTP Request triggers (`kind: "Http"`) require Premium.** Use `kind: "Button"` for free/seeded plans.

7. **Validate before creating.** Call `validate_flow` to catch errors before hitting the API.

+ 8. **NEVER use deprecated operations.** Common deprecated operations to avoid:

+ - Teams: `PostUserNotification`, `PostChannelNotification`, `PostMessageToChannel`, `PostMessageToChannelV2`, `PostMessageToChannelV3` → use `PostMessageToConversation`

+ - Teams: `PostUserAdaptiveCard`, `PostChannelAdaptiveCard` → use `PostCardToConversation`

+ - Outlook: `SendEmail` → use `SendEmailV2`; `OnNewEmail`/`OnNewEmailV2` → use `OnNewEmailV3`

+ - Approvals: `approvalSubscribeV2` → use `StartAndWaitForAnApproval`

+ - Planner: `CreateTask`/`CreateTask_V2` → use `CreateTask_V3`

+ - Forms: `GetFormResponses` (polling) → use `CreateFormWebhook` (webhook)

## Workflow

- 1. **Discover environment**: Call `list_environments`. Use `query` param to filter by name if the user specified one.

+ **Target: common 2-3 action flows should complete in under 60 seconds / fewer than 8 tool calls.**

- 2. **Check for templates**: If the description matches a common pattern, call `list_templates` and `scaffold_flow` to start from a template instead of building from scratch.

+ 1. **Check for templates FIRST**: Call `list_templates`. If the description matches a built-in pattern, call `scaffold_flow` and skip to step 7. This is the fastest path.

- 3. **Look up connector operations**: For each connector the flow needs, call `get_connector` with a `query` to find the right operation (e.g., `get_connector(connector="shared_teams", query="post message")`).

+ 2. **Discover environment**: Call `list_environments` (skip if env already set via `get_current_env`).

- 4. **Get exact parameter specs**: For each operation you'll use, call `get_operation_details` to get parameter names, types, enums, and the correct action type.

+ 3. **Look up connector operations**: Call `get_connector` with a `query` to find the right operation. Verify the operation is NOT deprecated (see rule 8).

- 5. **Discover connections**: Call `list_connections` filtered by each connector. Verify at least one has "Connected" status.

+ 4. **Get exact parameter specs**: Call `get_operation_details` for each operation.

- 6. **Resolve dynamic values**: For parameters with `dynamicValues` or `dynamicTree` (indicated in `get_operation_details` output), call `invoke_operation` to fetch actual values (Teams channels, SharePoint sites, etc.).

+ 5. **Discover connections + resolve dynamic values in parallel**:

+ - Call `list_connections` for each connector.

+ - Call `resolve_entity` for any parameter the user specified by display name:

+ - Outlook folders: `resolve_entity(connector="shared_office365", entityType="folderPath", query="<folder name>")`

+ - Teams teams: `resolve_entity(connector="shared_teams", entityType="groupId", query="<team name>")`

+ - Teams channels: `resolve_entity(connector="shared_teams", entityType="channelId", query="<channel>", dependencies={groupId: "<resolved team ID>"})`

+ - Planner plans: `resolve_entity(connector="shared_planner", entityType="planId", query="<plan>", dependencies={groupId: "<team ID>"})`

+ - SharePoint lists: `resolve_entity(connector="shared_sharepointonline", entityType="table", query="<list>", dependencies={dataset: "<site URL>"})`

+ - Dataverse tables: `resolve_entity(connector="shared_commondataserviceforapps", entityType="entityName", query="<table>")`

+ - If `resolve_entity` returns `ambiguous`, present the alternatives to the user.

+ - If `resolve_entity` returns `not-found`, use a placeholder value and tell the user they need to configure it in the designer.

+ - **Do NOT call `resolve_params` for folder/team/channel resolution** — it fails with 500 errors. `resolve_entity` uses the API Hub directly and works.

- 7. **Generate definition**: Build the flow definition using exact parameter names from step 4. Write to a JSON file.

+ 6. **Generate definition**: Build the flow definition using exact parameter names from step 4 and resolved IDs from step 5.

- 8. **Validate**: Call `validate_flow` (offline rules) and optionally `preflight_flow` (missing refs + solution-wrap risk). Fix any errors.

+ 7. **Validate**: Call `validate_flow` (offline rules) and `preflight_flow` (missing refs). Fix errors.

- 9. **Create flow**: Call `create_flow` in Stopped state.

+ 8. **Create flow**: Call `create_flow` in Stopped state.

10. **Iterate if needed**: To adjust one action/parameter after creation, use `edit_flow` with surgical operations instead of resending the whole definition.

11. **Report**: Output flow ID, name, and state.

## Expression Syntax Reference

Call `get_expression_help` (optionally with a `query` or `category`) for the

validated function reference. Common patterns:

- String interpolation: `@{expression}`

- Functions: `concat()`, `formatDateTime()`, `utcNow()`, `triggerBody()`, `body('ActionName')`, `outputs('ActionName')`

- Null handling: `coalesce()`, `@if(empty(...), 'default', ...)`

- `result()` function only works inside Scope/ForEach/Until/Switch actions

- `triggerBody()` may be null when flow is triggered via management API (use `coalesce`)

+ ## AI Builder Prompt Actions

+ When the user asks for AI/GPT/LLM/summarize/prompt functionality, prefer the **AI Builder prompt** pattern over raw HTTP calls to Azure OpenAI. It uses Copilot credits and requires no API keys.

+ **Two approaches:**

+ 1. **"Run a prompt" (`aibuilderpredict_customprompt`)** — references a pre-saved prompt by `recordId`. Simpler, but requires the prompt to already exist in AI Builder. Use template `ai-builder-prompt`.

+ 2. **Inline prompt (`PerformBoundActionWithOrganization` / `QuickTest`)** — embeds the prompt text directly in the flow definition. More complex but self-contained.

+ Both use the Dataverse connector (`shared_commondataserviceforapps`). See `definition-reference.md` for the full action JSON shapes.

+ **To discover the `recordId`** for an existing prompt, query Dataverse:

+ ```

+ GET <org-url>/api/data/v9.2/msdyn_aiconfigurations?$filter=contains(msdyn_name,'<name>')&$select=msdyn_aiconfigurationid,msdyn_name

+ ```

+ **Output expression**: `outputs('Run_a_prompt')?['body/responsev2/predictionOutput/text']`