Skip to main content
skill CX Codex

diagnose-flow — Claude Code skill: Power Automate diagnostics

diagnose-flow is a Claude Code skill that analyzes failed Power Automate runs, builds an execution graph, finds the root cause, and suggests a fix in the flow definition.

MIT ★ 1,167 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add microsoft/power-platform-skills
/plugin install power-automate@power-platform-skills
Open on GitHub

What diagnose-flow does

The skill queries run history via FlowAgent MCP tools (diagnose_run, get_run_details, get_run_actions), the flow definition (get_flow), and for failed loops, iteration details (get_run_action_repetitions). It builds an action dependency graph from runAfter fields, separates root failures from cascading skips, and matches errors against patterns: authorization issues, expression evaluation failures, timeouts, invalid parameters, action-type mismatches. When the cause lies in the definition, it applies the fix via edit_flow or update_flow.

Requires the FlowAgent MCP server and a Power Platform account. Without them, the skill will suggest running the setup skill from the same repository. It relies on the opus model and runs in a separate context (context: fork) to keep diagnostic data out of the main session.

What it helps with

  • find which step caused a Power Automate flow to fail
  • understand why an action inside a loop failed on the third iteration
  • fix the flow definition after a connection failure
  • trace action dependencies and see where a branch broke off

Example prompts for the agent

  • Diagnose why run abc123 of flow def456 in environment env789 failed
  • Analyze the failure of flow email-sender in environment prod-env, run run-20231215
  • Find the cause of error in run failed-run-001 and suggest how to fix the definition

How to install diagnose-flow

1Plugin marketplace

/plugin marketplace add microsoft/power-platform-skills
/plugin install power-automate@power-platform-skills

This installs the whole power-automate plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/power-platform-skills --skill diagnose-flow -a claude-code

3Manually: put the files in place

~/.claude/skills/diagnose-flow/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagnose-flow/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about diagnose-flow

How to install diagnose-flow in Claude Code?

Run /plugin marketplace add microsoft/power-platform-skills, then /plugin install power-automate@power-platform-skills. The skill will appear in the available skills list.

What does diagnose-flow do?

The skill autonomously analyzes a failed Power Automate flow run: retrieves details via FlowAgent MCP, constructs an execution graph, classifies errors, and identifies the root cause. If the failure is in the definition, it suggests a specific code fix.

What is needed for diagnose-flow to work?

FlowAgent MCP server and a Power Platform account with access to the environment. Without MCP, the skill will ask you to run the setup skill for configuration.

Source text

SKILL.md · MIT
---
name: diagnose-flow
description: Deep autonomous diagnosis of a failed flow run. Provide environment, flow, and run IDs. Use when the user asks to diagnose or deeply investigate a specific failed flow run.
user-invocable: true
argument-hint: "<env-id> <flow-id> <run-id>"
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_content, 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, mcp__flowagent__whoami, mcp__flowagent__doctor, mcp__flowagent__reconnect, mcp__flowagent__list_accounts, mcp__flowagent__switch_account
model: opus
---

# Deep Flow Diagnostic Agent

You are an autonomous diagnostic agent. Given environment, flow, and run IDs, perform a comprehensive failure analysis.

## Input

Parse `$ARGUMENTS` for: environment ID, flow ID, run ID.

## Tools

This skill uses the **FlowAgent MCP tools**, referred to by bare name (clients
surface them as `mcp__flowagent__<tool>` in Claude Code or `flowagent-<tool>` in
Copilot CLI). If no MCP tools are present, the plugin is not wired up — run the `setup` skill.

## Workflow

1. **Triage with `diagnose_run`**, then gather full context in parallel:
   - `diagnose_run` — classified failed/timed-out actions with a remediation each (start here)
   - `get_run_details` for overall run status
   - `get_run_actions` for the full action-level execution trace
   - `get_flow` for definition context
   - For a failed loop, `get_run_action_repetitions` on an action **inside** the loop (the container returns none) to find the failing iteration
   - Repetition results are `{ action, count, truncated, repetitions }`; `count` is the returned count, not the total. Treat `truncated: true` as incomplete evidence.
   - If payload evidence is needed, request `get_run_actions` with `includeSizes: true`, then `get_run_action_content` for one action with `which: "inputs"` or `"outputs"`. The default cap is 256000 bytes; oversized content is reported rather than dumped. Fetch only necessary payloads and omit sensitive values from the report.

2. **Build execution graph**: Map each action's `runAfter` dependencies. Identify parallel branches.

3. **Identify failed actions**: Filter for status != Succeeded. Classify each as:
   - **Root failure**: dependencies all Succeeded but this action failed
   - **Cascading skip**: skipped because a dependency failed

4. **Analyze each root failure** against common patterns:
   - Authorization/Connection errors
   - Expression evaluation failures
   - HTTP 4xx/5xx from external services
   - Timeout errors
   - Parameter validation failures (empty required fields, wrong enum values)
   - Action type mismatches (OpenApiConnection vs OpenApiConnectionWebhook)

5. **Cross-reference with definition**: Check if the action's parameters, connection references, or expressions have issues visible in the definition.

6. **Write diagnosis report** with:
   - Execution timeline
   - Root cause identification
   - Specific fix with code changes
   - Confidence level (high/medium/low)

7. **Optionally generate fixed definition**: If the fix is a definition change, apply it with `edit_flow` (surgical, one action/parameter) — fall back to `update_flow` only for large rewrites.

© Microsoft · MIT · microsoft/power-platform-skills

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

From the same set157

The whole set →
canvas-create-layout canvas-create-layout is a Claude Code subagent that plans Canvas app screen layouts before control selection. It joins work on new screens or layout revisions. CX Codex ★ 1,167repo stars add-data-source add-data-source is a Claude Code skill that guides you through adding a data source or connector in Power Apps Studio and verifies the result over MCP. CX Codex +1 ★ 1,167repo stars list-connections list-connections finds or provisions Power Platform connections and references for Expo and React Native apps. Handy when linking data sources via CLI. CX Codex +1 ★ 1,167repo stars create-flow The create-flow skill guides an interactive Power Automate flow setup, from gathering requirements and checking connectors to validating the definition before creation. CX Codex +1 ★ 1,167repo stars add-connector add-connector adds any generic Power Platform connector to a Power Apps code app when a dedicated skill does not exist. CX Codex +1 ★ 1,167repo stars add-dataverse The add-dataverse Claude Code skill connects Dataverse tables to Power Apps code apps and generates TypeScript models and services. It also guides new table creation. CX Codex +1 ★ 1,167repo stars add-office365 add-office365 connects Office 365 Outlook to Power Apps code app. Provides calendar access, email sending, inbox reading and event management. CX Codex +1 ★ 1,167repo stars manage-flows manage-flows manages Power Automate flow lifecycles in Claude Code: handles publish-test loops, batch changes, tenant inventories, and runaway run cancellations. CX Codex +1 ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open