Official agent skill

Debug Flow

by microsoft in microsoft/power-platform-skills

Debug a failed Power Automate flow run. An agent skill from microsoft/power-platform-skills.

OfficialMITAuto-check: notesDevelopment

Install Debug Flow

skills CLI
$ npx skills add microsoft/power-platform-skills --skill debug-flow -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install microsoft/power-platform-skills debug-flow --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/microsoft/power-platform-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/power-automate/skills/debug-flow .claude/skills/debug-flow && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debug-flow
GitHub stars
967
Token cost
~1.8k tokens
SKILL.md length
587 words
Files
1
Skills in repo
87
Repo updated
First seen
Licence
MIT

At a glance

Debug a failed Power Automate flow run. An agent skill from microsoft/power-platform-skills.

  • Works in 6 steps: Identify the flow and run → Fast triage with diagnose_run → Analyze failures → …
  • The user wants to troubleshoot a run
  • SKILL.md covers Tools, Steps and Output Format
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Debug Flow is an agent skill from microsoft/power-platform-skills, published by the product's own GitHub organization. Debug a failed Power Automate flow run. Use when a flow failed, has errors, or the user wants to troubleshoot a run.

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. It works with Power Automate. The repository describes itself as: A plugin marketplace for GitHub Copilot and other AI agents that provides Power Platform development plugins, including reusable skills, agents, and commands for building and… The licence is MIT.

When your agent uses it

  • The user wants to troubleshoot a run

Example prompts

  • “/debug-flow”

Requirements

  • Pre-approved tools (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

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Identify the flow and run
  2. Fast triage with diagnose_run
  3. Analyze failures
  4. Root cause classification
  5. Suggest fix
  6. Re-test

What it can do on your machine

Read from SKILL.md and the folder at commit 5ef4e4f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash
    • Read
    • Write
    • Glob
    • Grep
    • AskUserQuestion
    • mcp__flowagent__list_environments
    • mcp__flowagent__set_current_env
    • mcp__flowagent__get_current_env
    • mcp__flowagent__resolve_environment

    …and 57 more on the same allowed-tools line.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Debug Flow loads about 1.8k tokens when it runs. Until then it costs about 32 tokens; SKILL.md has 587 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~32
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Bash, Read, Write, Glob, Grep, AskUserQuestion, mcp__flowagent__list_environments, mcp__flowagent__s

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft/power-platform-skills at commit 5ef4e4f, republished under its MIT licence (© microsoft). 587 words, ~1,752 tokens.

Download SKILL.mdSave it as .claude/skills/debug-flow/SKILL.md (or your agent's skills folder).
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.
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
user-invocable
true
argument-hint
[flow-id] [run-id]
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.

ToolPurpose
list_flowsFind flows by name (use name param for search)
get_run_historyGet recent runs for a flow
diagnose_runOne-shot: classify failed actions with remediations
get_run_detailsGet details for a specific run
get_run_actionsGet action-level execution trace
get_run_action_contentRetrieve bounded recorded inputs or outputs for one action
get_run_action_repetitionsIteration-level detail for a loop (which iteration failed — pass an action inside the loop)
get_flowGet flow definition for context
get_operation_detailsConfirm the correct action type / parameters
edit_flowApply a surgical fix to one action/parameter
update_flowReplace the whole definition (large rewrites)
run_flowRe-run after fix (use wait: true to see result)
resubmit_run / cancel_runResubmit a fixed run / cancel a stuck one

Steps

  1. Identify the flow and run

    • Parse $ARGUMENTS for flow ID and optional run ID.
    • 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.
    • 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.
Show full SKILL.md (31 more words)Show less

Output Format

Diagnosis Summary
  • Flow: [name] ([ID])
  • Run: [run ID] | [start time] | Status: [status]
Failed Actions
#ActionStatusError CodeError Message
Root Cause
Fix

[Step-by-step fix with code]

© microsoft, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugins/power-automate/skills/debug-flow of microsoft/power-platform-skills.

Open the folder on GitHubat commit 5ef4e4f

Compare with similar skills

Debug Flow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Debug Flow compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debug Flow this skillmicrosoft/power-platform-skills967—~1.8kAutomated safety check: NotesMIT
Flowstudio Power Automate Debuggithub/awesome-copilot40k2 repos~5kAutomated safety check: PassMIT
Flowstudio Power Automate Governancegithub/awesome-copilot40k2 repos~3.6kAutomated safety check: PassMIT
Flowstudio Power Automate Monitoringgithub/awesome-copilot40k2 repos~3.3kAutomated safety check: PassMIT
Power Platform Architectgithub/awesome-copilot40k1 repos~3.6kAutomated safety check: PassMIT
Power Apps Code App Scaffoldgithub/awesome-copilot40k1 repos~1.8kAutomated safety check: PassMIT

Similar skills

  • Flowstudio Power Automate Debug

    github/awesome-copilot

    Official

    Debug failing Power Automate cloud flows using the FlowStudio MCP server.

    40k GitHub starsUsed in 2 repos~5k tokens
    DevelopmentAuto-check passed
  • Official

    Govern Power Automate flows and Power Apps at scale using the FlowStudio MCP cached store.

    40k GitHub starsUsed in 2 repos~3.6k tokens
    DevelopmentAuto-check passed
  • Official

    Pro+ subscription required. An agent skill from github/awesome-copilot.

    40k GitHub starsUsed in 2 repos~3.3k tokens
    DevelopmentAuto-check passed
  • Power Platform Architect

    github/awesome-copilot

    Official

    A skill your agent uses when the user needs to transform business requirements, use case descriptions, or meeting transcripts into a technical Power Platform solution architecture, including…

    40k GitHub starsUsed in 1 repo~3.6k tokens
    DevelopmentAuto-check passed
  • Power Apps Code App Scaffold

    github/awesome-copilot

    Official

    Scaffold a complete Power Apps Code App project with PAC CLI setup, SDK integration, and connector configuration

    40k GitHub starsUsed in 1 repo~1.8k tokens
    DevelopmentAuto-check passed
  • Power Automate

    ericrisco/rsc-harness

    A skill your agent uses when operating Microsoft Power Automate cloud flows from code — create, enable, update, list or delete via the Dataverse Web API (workflow table, category 5) with Entra ID…

    156 GitHub stars~3.1k tokensUpdated yesterday
    DevelopmentAuto-check: notes

More from microsoft/power-platform-skills

All 87 skills in this repo
  • Manage Firewall

    microsoft/power-platform-skills

    Official

    Inspects and configures the web application firewall (WAF) in front of a Power Pages production site.

    967 GitHub stars~4.5k tokensUpdated today
    Auto-check: notes
  • Manage Headers

    microsoft/power-platform-skills

    Official

    Inspects and configures the security headers a Power Pages site sends to browsers — Content Security Policy, frame and clickjacking protection, cross-origin sharing, cookie behavior, and related…

    967 GitHub stars~3k tokensUpdated today
    Auto-check: notes
  • Scan Code

    microsoft/power-platform-skills

    Official

    Scans a Power Pages site project for security issues in source code and dependencies.

    967 GitHub stars~3.4k tokensUpdated today
    Auto-check: notes
  • Scan Site

    microsoft/power-platform-skills

    Official

    Runs a security scan on a deployed Power Pages site, fetches the latest scan report, and produces a plain-language summary.

    967 GitHub stars~3.2k tokensUpdated today
    Auto-check: notes
  • Setup Datamodel

    microsoft/power-platform-skills

    Official

    Creates Dataverse tables, columns, and relationships for a Power Pages site based on a data model proposal.

    967 GitHub stars~4k tokensUpdated today
    Auto-check: notes
  • Add Server Logic

    microsoft/power-platform-skills

    Official

    Creates, edits, and manages Power Pages Server Logic files — server-side JavaScript that runs securely on the Power Pages runtime.

    967 GitHub stars~18k tokensUpdated today
    Auto-check: notes

Works with

Categories

Questions about Debug Flow

What does Debug Flow do?

Debug a failed Power Automate flow run. An agent skill from microsoft/power-platform-skills. Debug Flow is an agent skill from microsoft/power-platform-skills, published by the product's own GitHub organization. Debug a failed Power Automate flow run.

When should I use Debug Flow?

Debug Flow fits situations like: the user wants to troubleshoot a run.

How do I install Debug Flow in Claude Code?

Run `npx skills add microsoft/power-platform-skills --skill debug-flow -a claude-code`. Or copy the skill folder (plugins/power-automate/skills/debug-flow in microsoft/power-platform-skills) into .claude/skills/debug-flow in your project. Claude Code loads it when a task matches its description.

How do I install Debug Flow in Codex?

Run `npx skills add microsoft/power-platform-skills --skill debug-flow -a codex`. Or copy the skill folder (plugins/power-automate/skills/debug-flow in microsoft/power-platform-skills) into .agents/skills/debug-flow in your project. Codex loads it when a task matches its description.

Can I use Debug Flow in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft/power-platform-skills --skill debug-flow -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debug-flow, .gemini/skills/debug-flow, .github/skills/debug-flow and .opencode/skills/debug-flow in your project.

What does Debug Flow need to run?

SKILL.md names no scripts, command-line tools or credentials: Debug Flow is instructions for the agent only. Its frontmatter pre-approves these 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.

Does Debug Flow access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Debug Flow safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Debug Flow use?

Debug Flow is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Debug Flow use?

About 1.8k tokens (SKILL.md is roughly 7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Debug Flow?

Skills that share tags, products or a category with Debug Flow: Flowstudio Power Automate Debug (github/awesome-copilot, 40k stars), Flowstudio Power Automate Governance (github/awesome-copilot, 40k stars), Flowstudio Power Automate Monitoring (github/awesome-copilot, 40k stars) and Power Platform Architect (github/awesome-copilot, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Flow?

microsoft (a GitHub organization, an official publisher) maintains it in microsoft/power-platform-skills, which has 967 GitHub stars. The repository holds 87 skills in this directory. The repository was last updated on October 6, 2026.

Source: microsoft/power-platform-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.