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
/plugin marketplace add microsoft/power-platform-skills
/plugin install power-automate@power-platform-skillsWhat 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-skillsThis 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-code3Manually: put the files in place
~/.claude/skills/debug-flow/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-flow/
1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill debug-flow -a codex2Manually: put the files in place
.agents/skills/debug-flow/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill debug-flow -a cursor2Manually: put the files in place
.cursor/skills/debug-flow/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/power-platform-skills plugins/power-automate/skills/debug-flow2Manually: put the files in place
.github/skills/debug-flow/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill debug-flow -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/power-platform-skills --path plugins/power-automate/skills/debug-flowManually: put the files in place
.devin/skills/debug-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 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