How to use the Power Automate Flow Debugger agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file and optional reference files and scripts. When a request matches the skill's description, the AI agent loads its instructions and follows them. Skills give the agent a repeatable procedure for a specific task instead of relying on general knowledge alone.

What does this skill make the agent do?

Power Automate cloud flows are automated workflows built in Microsoft's low-code tool. When one fails, the standard status only shows a generic error code such as ActionFailed, NotSpecified or InternalServerError. With this skill, the agent follows a fixed diagnostic sequence: it finds the flow, locates the failed run, identifies which action failed, and then reads that action's actual inputs and outputs, such as HTTP responses, expressions and null values, to pinpoint the true cause and suggest a fix.

• Find the flow by name in a Power Automate environment
• Find the most recent failed run
• Get the top-level error and identify the root failing action
• Inspect that action's inputs and outputs, including HTTP status codes and response bodies
• Decode common error codes using the included reference notes

How do you install the skill?

The skill is published in github/awesome-copilot under skills/flowstudio-power-automate-debug and is licensed MIT. Download the ZIP from the skill's page on our site and unzip it. Then place the folder in one of these locations:

• Personal skills: unzip into ~/.claude/skills/
• Project skills: unzip into the .claude/skills/ folder of your project
• Claude apps: upload the skill under Settings → Capabilities → Skills

What does the skill need before it works?

The skill cannot read run data without a FlowStudio MCP server connection. FlowStudio MCP is a paid, third-party service, so you need your own subscription and a valid JWT token. Subscribe at https://mcp.flowstudio.app. The companion skill flowstudio-power-automate-mcp explains how to set up that connection.

• A FlowStudio MCP server subscription and JWT token
• Access to the target Power Automate environment ID
• Python 3 with the standard library (the example helper uses urllib and json)
• The companion skill flowstudio-power-automate-mcp for connection setup

How do you trigger the skill with a natural request?

You do not need special syntax. Describe the problem as you would to a colleague. The skill's description lists trigger phrases the agent matches against, including: debug a flow, investigate a failed run, why is this flow failing, inspect action outputs, find the root cause of a flow error, diagnose a timeout, trace a DynamicOperationRequestFailure, check connector auth errors, and troubleshoot expression failures.

Name the flow and, if you know it, the environment. The agent will confirm available tool names with the server before it starts.

• Why is my "Invoice Sync" flow failing in environment Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?
• Investigate the latest failed run of the Onboarding flow and tell me the root cause.
• Diagnose the timeout in my approval flow and suggest a fix.
• Check the connector auth error in the HR sync flow and read the error details from the run.

What does a debugging session look like?

The skill's workflow has four steps. First the agent lists live flows and matches your flow name to a flow ID. Second it lists recent runs and picks the newest failed one. Third it reads the top-level error, which names the failed actions in order from outer to inner. The last entry is treated as the root cause. Fourth it reads the root action's outputs, which is where HTTP status codes, response bodies and expression errors appear.

The source is explicit that you must call both the error tool and the action outputs tool. Stopping at the error alone is the most common way to miss the real cause.

• Error codes like ActionFailed are wrappers; the cause is in the action's outputs
• If a failed action sits inside a loop, the agent can inspect individual iterations
• The built-in decision tree routes InvalidTemplate, ConnectionAuthorizationFailed and HTTP failures to different checks

What safety points should you know about?

This skill runs scripts and uses the network. The example helper sends requests to https://mcp.flowstudio.app/mcp with your JWT token in an x-api-key header. Run data can contain sensitive inputs and outputs, so the skill is not suited to production environments where an agent should not read that data without oversight. Keep your token out of shared files and chat logs, and review what the agent reads before sharing results.

• Scripts and network access are required
• Run inputs and outputs may contain personal or confidential data
• Do not use it in production without oversight
• Not for desktop flows or non-Power Automate platforms