Skip to main content
skill CX Codex

debug-flow — Claude Code skill: what it does, how to install

debug-flow diagnoses failed Power Automate runs. It traces execution graphs, flags root causes, and prepares targeted flow fixes.

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 debug-flow does

This skill connects to Power Automate using FlowAgent MCP tools. When triggered, it queries run history, pulls the most recent failure, and runs triage via diagnose_run. If a flow lacks run history altogether, the skill reports that directly instead of guessing reasons from the raw definition.

Execution analysis parses the runAfter chain to separate actual root failures from skipped downstream steps. It categorizes bad connections, expression failures, HTTP error codes, and timeouts. When troubleshooting a failed loop, the skill calls get_run_action_repetitions on an action inside that loop to isolate the exact failed iteration.

Operating this skill requires an active FlowAgent MCP server. Minor definition fixes are applied via edit_flow, preserving the rest of the flow structure.

What it helps with

  • Track down the exact failing step in a Power Automate flow run
  • Isolate which specific iteration broke a loop
  • Distinguish root errors from cascading skipped actions
  • Apply targeted parameter or expression fixes without rewriting the flow

Example prompts for the agent

  • Debug the latest failed run for flow 12345-abc
  • Check why flow "Send Daily Report" failed and report the root cause
  • Investigate flow ID 5a6b7c with run ID 987654 and suggest a fix

How to install debug-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 debug-flow -a claude-code

3Manually: put the files in place

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

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

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

Questions about debug-flow

How do I install debug-flow in Claude Code?

First, register the marketplace source via /plugin marketplace add microsoft/power-platform-skills, then install the package with /plugin install power-automate@power-platform-skills.

What does debug-flow do?

It inspects execution logs for failed Power Automate flows, classifies root causes, and assists in patching faulty parameters or expressions.

What happens if a flow has never run?

The skill stops immediately, states that no runs were found in the history, and offers to check trigger settings instead of guessing.

Source text

SKILL.md · MIT
---
name: debug-flow
description: Debug a failed Power Automate flow run. Use when a flow failed, has errors, or the user wants to troubleshoot a run. If the flow has no runs, says so plainly instead of guessing a cause.
user-invocable: true
argument-hint: "[flow-id] [run-id]"
allowed-tools: Bash, Read, Write, Glob, Grep, AskUserQuestion, 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
---

# Debug a Failed Flow Run

You are helping the user debug a failed Power Automate flow run.

## 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
(e.g. `get_run_actions`). Use CLI shell commands (local engine build only) for
CLI-only operations or when no MCP tools are present.

| Tool | Purpose |
|------|---------|
| `list_flows` | Find flows by name (use `name` param for search) |
| `get_run_history` | Get recent runs for a flow |
| `diagnose_run` | One-shot: classify failed actions with remediations |
| `get_run_details` | Get details for a specific run |
| `get_run_actions` | Get action-level execution trace |
| `get_run_action_content` | Retrieve bounded recorded inputs or outputs for one action |
| `get_run_action_repetitions` | Iteration-level detail for a loop (which iteration failed — pass an action **inside** the loop) |
| `get_flow` | Get flow definition for context |
| `get_operation_details` | Confirm the correct action type / parameters |
| `edit_flow` | Apply a surgical fix to one action/parameter |
| `update_flow` | Replace the whole definition (large rewrites) |
| `run_flow` | Re-run after fix (use `wait: true` to see result) |
| `resubmit_run` / `cancel_run` | Resubmit a fixed run / cancel a stuck one |

## Steps

1. **Identify the flow and run**
   - Parse `$ARGUMENTS` for flow ID and optional run ID.
   - If the user names an environment (or none is set), call `resolve_environment` first so the search runs in the right environment.
   - If no flow ID, call `list_flows` with `name` param to search. Ask user to pick if ambiguous.
   - If no run ID, call `get_run_history` and find the most recent failed run.
   - **If `get_run_history` returns no runs, stop and say so plainly** ("this flow has no recorded runs in its history"). Do not invent a failure, do not diagnose from the definition as if it had failed; offer to check the trigger configuration or to run/test the flow instead.
   - Present recent runs in a table: Run ID | Status | Start Time | Error

2. **Fast triage with `diagnose_run`**
   - Call `diagnose_run` for the run — it returns the failed/timed-out actions already classified with a remediation each. Use this as the starting point.
   - For deeper analysis, also fetch (in parallel): `get_run_actions` (full trace) and `get_flow` (definition context). For a failed loop, call `get_run_action_repetitions` on an action **inside** the loop to find the failing iteration.
   - Repetition results are `{ action, count, truncated, repetitions }`; `count` is the returned count, not the total. If `truncated` is true, do not infer absence from the returned subset.
   - When recorded payloads are needed, use `get_run_actions` with `includeSizes: true`, then `get_run_action_content` with the action name and `which: "inputs"` or `"outputs"`. The default download cap is 256000 bytes; an oversized result is reported rather than dumped. Retrieve only what the diagnosis needs and avoid reproducing sensitive payloads in the report.

3. **Analyze failures**
   - Identify actions with status != "Succeeded"
   - Trace the `runAfter` dependency chain to separate root cause from cascading failures:
     - **Root cause**: action whose dependencies all Succeeded but it failed
     - **Cascading**: actions skipped because a dependency failed
   - Report root cause actions with: name, type, error code, error message

4. **Root cause classification**
   - **Connection errors** (`AuthorizationFailed`, `ConnectionNotFound`, `InvokerConnectionOverrideFailed`): Suggest re-auth or fix connection source to Embedded
   - **Expression errors** (`ExpressionEvaluationFailed`, `InvalidTemplate`): Show the expression, explain what's wrong, suggest fix
   - **API/External errors** (401/403/404/429/500+): Explain the HTTP error, check connector status
   - **Parameter errors** (`WorkflowOperationParametersRuntimeMissingValue`): Missing/empty required parameter. Add null guard: `@if(empty(...), 'default', ...)`
   - **Timeout** (`ActionTimedOut`): Suggest retry policy or splitting the operation
   - **Type mismatch** (`InvalidOpenApiConnectionOperationType`): Wrong action type. Call `get_operation_details` to find correct type.

5. **Suggest fix**
   - Provide a specific fix with code/expression changes.
   - If the fix is a definition change, offer to apply it with `edit_flow` (surgical, one action/parameter) — fall back to `update_flow` only for large rewrites.

6. **Re-test**
   - Offer to call `run_flow` with `wait: true` to verify the fix works (or `resubmit_run` to retry the original run with its trigger inputs).
   - Report the result: Succeeded/Failed with action details.

## Output Format

### Diagnosis Summary
- **Flow**: [name] ([ID])
- **Run**: [run ID] | [start time] | Status: **[status]**

### Failed Actions
| # | Action | Status | Error Code | Error Message |
|---|--------|--------|------------|---------------|

### Root Cause
[Classification]: [Explanation]

### Fix
[Step-by-step fix with code]

© 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-discovery canvas-create-discovery — a subagent that scans Power Apps to map available controls, data sources, and APIs, then documents feasible design choices and constraints. Use it to validate your canvas app concept before implementation begins. CX Codex ★ 1,167repo stars check-updates check-updates is a Claude Code skill that sequentially checks and updates direct dependencies in Power Apps mobile projects, with type-checking, Expo validation, and rollback. CX Codex +1 ★ 1,167repo stars report-issue report-issue collects project details and diagnostics, then drafts a GitHub issue for the mobile-app plugin. Use it to document a bug, unexpected result, or documentation problem. CX Codex +1 ★ 1,167repo stars setup setup guides the agent through Process Intelligence configuration: dependency checks, cloud and environment selection, az login binding, then profile activation. CX Codex +1 ★ 1,167repo stars configure-canvas-mcp The configure-canvas-mcp skill connects Canvas Authoring MCP to an active Power Apps coauthoring session. Run it before editing a canvas app when the server is not connected yet. CX Codex +1 ★ 1,167repo stars add-sharepoint add-sharepoint connects SharePoint Online to Power Apps code apps: reads lists, manages documents, creates new lists via Graph API. CX Codex +1 ★ 1,167repo stars preview-offline-scope preview-offline-scope estimates download payload and sync frequency costs for a Power Platform offline profile before rollout. Runs strictly in read-only mode. CX Codex +1 ★ 1,167repo stars canvas-screen-builder canvas-screen-builder is a Claude Code subagent that adds or edits one screen in an existing Canvas App from a shared contract and scoped brief. It runs local QA without compiling. CX Codex ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open