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
/plugin marketplace add microsoft/power-platform-skills
/plugin install power-automate@power-platform-skillsWhat 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
abc123of flowdef456in environmentenv789failed - Analyze the failure of flow
email-senderin environmentprod-env, runrun-20231215 - Find the cause of error in run
failed-run-001and 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-skillsThis 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-code3Manually: put the files in place
~/.claude/skills/diagnose-flow/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagnose-flow/
1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill diagnose-flow -a codex2Manually: put the files in place
.agents/skills/diagnose-flow/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill diagnose-flow -a cursor2Manually: put the files in place
.cursor/skills/diagnose-flow/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/power-platform-skills plugins/power-automate/skills/diagnose-flow2Manually: put the files in place
.github/skills/diagnose-flow/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill diagnose-flow -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/power-platform-skills --path plugins/power-automate/skills/diagnose-flowManually: put the files in place
.devin/skills/diagnose-flow/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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