diagnose-deployment
Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches against a known failure catalog, and optionally auto-fixes identified issues
Install / Use
npx skills add microsoft/power-platform-skills --skill diagnose-deploymentInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of diagnose-deployment
diagnose-deployment scores 89/100 on our quality scale, 342nd of 763 Operations skills we index (top 45%).
Its SKILL.md is 10 KB long, well organised into 15 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
It has 919 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so diagnose-deployment is actively maintained.
- Our last check on 2026-11-22 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
diagnose-deployment compared with similar skills
All 4 of these similar skills score higher than diagnose-deployment; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| diagnose-deployment (this skill)by microsoft | 89 | 919 | 59d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.5k | today | CLAUDE.md |
Frequently asked questions
- How do I install diagnose-deployment?
- Run
npx skills add microsoft/power-platform-skills --skill diagnose-deployment. The install tabs above show the steps for each supported agent. - Which AI agents does diagnose-deployment work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is diagnose-deployment safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is diagnose-deployment still maintained?
- The repository was last updated about 2 months ago, so diagnose-deployment is actively maintained.
Skill content
View source on GitHubname: diagnose-deployment description: >- Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches against a known failure catalog, and optionally auto-fixes identified issues. Use when asked to: "diagnose deployment", "debug deployment", "deployment failed", "show deployment errors", "fix deployment issues", "show upload logs", "why did my deploy fail", or "troubleshoot upload". user-invocable: true allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch model: opus
Plugin check: Run
node "${PLUGIN_ROOT}/scripts/check-version.js"— if it outputs a message, show it to the user before proceeding.
diagnose-deployment
Surfaces and pattern-matches deployment errors against a known failure catalog. For each identified error with an available auto-fix, asks explicit user permission before applying any changes. Never auto-applies fixes without confirmation.
Prerequisites
- Project root with
powerpages.config.json - PAC CLI installed (will report if missing)
Phases
Phase 1 — Verify Prerequisites and Locate Project
Create all tasks upfront at the start of this phase.
Tasks to create:
- "Verify prerequisites and locate project"
- "Collect deployment artifacts"
- "Surface upload errors"
- "Query solution import status"
- "Diagnose and categorize findings"
- "Offer auto-fixes"
- "Present findings summary"
Steps:
- Locate project root: search for
powerpages.config.jsonin cwd and parent directories - Check PAC CLI:
pac --version(report version or "not installed") - Check PAC CLI auth:
pac env who(report environment URL or "not authenticated") - Check Azure CLI:
az account show(report subscription or "not logged in")
Auth failures are non-blocking — report them as findings, continue collecting other artifacts.
Phase 1.5 — Ground in current ALM documentation
Reference:
${PLUGIN_ROOT}/references/alm-docs-grounding.md
Cap this step at ~30 seconds. If MCP search / fetch errors out, log a one-line note and continue — this skill must remain runnable offline.
- Run
microsoft_docs_searchwith the query:Power Pages deployment errors solution import troubleshooting. - Fetch
https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm(and at most one sister page on troubleshooting or known import errors) in parallel viamicrosoft_docs_fetch. - Extract a one-paragraph summary of what Microsoft Learn currently says about common deployment failures and their resolution. Compare against
${PLUGIN_ROOT}/references/deployment-error-catalog.mdand flag any new error patterns not yet captured in the catalog. - Use the summary to inform pattern-matching in Phase 5. If a new pattern is documented on Learn that isn't in the catalog, surface it to the user as a candidate addition rather than silently extending the catalog.
Phase 2 — Collect Deployment Artifacts
Gather all available context:
- Read
powerpages.config.json— extractsiteName,websiteRecordId,compiledPath - Check
.powerpages-site/folder exists - Glob for manifest files:
.powerpages-site/*-manifest.yml— list all found, note their environment hostnames - Check if
.solution-manifest.jsonexists (for solution-related diagnostics) - Check if
docs/alm/last-import.jsonexists (for recent import failures) - Check build output: confirm
{compiledPath}/exists and is non-empty
Report: "Found project: {siteName}. Artifacts collected."
Phase 3 — Surface Upload Errors
Re-run pac pages upload-code-site in capture mode to get fresh error output:
pac pages upload-code-site --rootPath "." 2>&1
Note: This intentionally triggers the upload to capture any errors. If the upload succeeds cleanly, that is also a valid diagnostic result ("no errors found").
Capture stdout+stderr as a single string. Pass to scripts/parse-deployment-errors.js:
echo "{escaped-output}" | node "${PLUGIN_ROOT}/scripts/parse-deployment-errors.js"
Parse the JSON findings array. If the upload succeeded with no errors, note this and skip to Phase 5 with an empty findings list.
Phase 4 — Query Solution Import Status
Only run if .solution-manifest.json exists.
- Acquire Azure CLI token for environment URL
- Check recent async operations (last 24 hours):
GET {envUrl}/api/data/v9.2/asyncoperations?$filter=statecode eq 3 and statuscode eq 31 and createdon gt {yesterday}&$select=asyncoperationid,name,message,friendlymessage,statuscode,completedon&$orderby=completedon desc&$top=5 - Check recent import jobs:
GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3 - If failed operations found, pass each
messagefield throughparse-deployment-errors.js
Skip gracefully if auth is not available (auth failure in Phase 1).
Phase 5 — Auto-Diagnose Known Issues
Consolidate all findings from Phases 3 and 4. For each finding, categorize:
- Error: Blocks deployment
- Warning: May cause issues
- Info: Informational
Also add findings for missing artifacts discovered in Phase 2:
- Missing
websiteRecordId→ Error (patternId:missing-website-record-id) - Empty build output → Error (patternId:
empty-build) - Multiple environment manifests → Warning (may indicate environment confusion)
Present all findings in a table:
| # | Severity | Type | Issue | Auto-fix? | |---|---|---|---|---| | 1 | Error | upload | JavaScript uploads blocked | Yes | | 2 | Warning | config | Multiple manifest files found | No |
Phase 6 — Offer Auto-Fixes
For each Error finding with autoFixAvailable: true, in order:
🚦 Gate (consent · diagnose-deployment:6.auto-fix): Per-finding consent before applying any auto-fix. Loops once per Error finding with
autoFixAvailable: true— each finding gets its own Yes / No / Skip-allAskUserQuestion. The pattern ID surfaces in the prompt. Never batch fixes — three findings = three separate consent prompts (unless the user picks "Skip all" on the first, which short-circuits the loop). The Yes from finding 1 does NOT cover finding 2; each fix has its own blast radius (different files, different settings, different reversibility).
-
Explain the issue and proposed fix
-
Ask explicit permission via
AskUserQuestion:"Issue: {message} Proposed fix: {suggestedFix} Apply this fix? Yes / No / Skip all auto-fixes"
-
If approved, execute the fix:
stale-manifest: Delete*-manifest.ymlfile(s) in.powerpages-site/# Ask which manifest to delete if multiple found, then: rm ".powerpages-site/{manifestFile}"blocked-js: Updateblockedattachmentssetting# Get current setting first pac env list-settings | grep -i blocked # Remove .js from the blocked list (preserve other blocked types) pac env update-settings --name blockedattachments --value "{updated-value}"missing-website-record-id: Retrieve and update record IDpac pages list # Parse output, find matching site by name, then update powerpages.config.jsonauth-expired: Guide re-authenticationpac auth create --environment "{envUrl}" az loginempty-build: Run buildnpm run build -
After each fix, re-run the relevant check to verify it resolved the issue. Update finding status to "Fixed" or "Manual required".
Key Constraint: Never apply any fix without explicit user permission. Each fix requires a separate confirmation.
Phase 7 — Present Findings Summary
Display a final summary table of all findings:
| # | Severity | Type | Issue | Status | |---|---|---|---|---| | 1 | Error | upload | JS uploads blocked | Fixed | | 2 | Error | config | Missing websiteRecordId | Manual required | | 3 | Warning | config | Multiple manifest files | Informational |
Status values:
- Fixed: Auto-fix was applied and verified
- Manual required: No auto-fix available — show manual steps
- Skipped: User declined the fix
- Informational: Warning/Info, no action needed
If all errors are resolved: suggest retrying deployment with /power-pages:deploy-site.
If manual steps remain: list them explicitly with commands or links.
Record Skill Usage
Reference:
${PLUGIN_ROOT}/references/skill-tracking-reference.md
Follow the skill tracking instructions in the reference to record this skill's usage. Use --skillName "DiagnoseDeployment".
Key Decision Points (Wait for User)
- Phase 6: Each individual auto-fix requires explicit confirmation before applying
- Phase 6: If user says "Skip all auto-fixes", stop offering fixes and go to summary
Error Handling
- If
pac pages upload-code-siteproduces no output: report "No upload errors detected in current state" - If Azure CLI token unavailable: skip Phase 4, note in summary
- If
parse-deployment-errors.jsreturns no findings: report "No known error patterns detected" and show raw output for manual review
Progress Tracking Table
| Task subject | activeForm | Description | |---|---|---| | Verify prerequisites and locate project | Verifying prerequisites | Check PAC CLI, Azure CLI, locate project root and powerpages.config.json | | Collect deployment artifacts | Collecting deployment artifacts | Read config, list manifests, check build output, check solution manifest | | Surface upload errors | Surfacing upload errors | Re-run pac pages upload-code-site in capture mode, parse stdout/stderr | | Query solution import status | Querying solution import status | Check recent failed async operations and import jobs in Dataverse | | Diagnose and categorize findings | Diagnosing findings | Pattern-match all errors against deployment-error-catalog, assign severity | | Offer auto-fixes | Applying auto-fixes | For each fixable error, ask permission and execute fix, verify result | | Present findings summary | Presenting summary | Show all findings table with severity and fix status, list manual steps |
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.5kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
