zdx-troubleshoot-user-experience
Troubleshoot a user's digital experience using ZDX data. Investigates device health, application scores, network path metrics, and active alerts to identify performance bottlenecks. Use when an administrator reports: 'User says app is slow', 'Check user experience', or 'Why is the application score low?'
What this skill does
# ZDX: Troubleshoot User Experience
## Keywords
user experience, slow application, zdx score, digital experience, performance issue, latency, application slow, user complaint, experience score, network path, zdx troubleshoot, deep trace
## Overview
Investigate a user's digital experience using Zscaler Digital Experience (ZDX) metrics. This skill retrieves device information, application experience scores, network path data, and active alerts to pinpoint whether the issue is on the client device, the network, or the application server.
**Use this skill when:** An administrator receives user complaints about application performance, needs to investigate low ZDX scores, or wants to proactively check a user's digital experience.
---
## Data Presentation Requirements
**All tables are rendered by the HTML template, not by hand.** Do not author `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, or `<td>` markup in your reply or in the report. You produce a JSON payload (see *Data Payload Contract*) and the template at `./templates/report.html.template` turns it into the styled, sortable, exportable tables shown in `./example/report.example.html`.
After each table, provide:
1. **Detailed analysis** explaining what the data means in plain language
2. **Root cause identification** based on the metrics and patterns
3. **Next steps / resolution** with specific, actionable recommendations prioritized by impact
Use color-coded status indicators in tables:
- Green/Good: scores 66-100, metrics within normal range
- Yellow/Degraded: scores 34-65, metrics approaching thresholds
- Red/Poor: scores 0-33, metrics exceeding thresholds
## ⚠ HTML OUTPUT — READ THIS BEFORE PRODUCING ANY HTML
There is exactly one acceptable way to produce the HTML output:
1. **Read the template from disk** — do NOT inline a copy in your response. The template lives next to this SKILL.md inside the skill's package, at:
```text
./templates/report.html.template
```
The `./` prefix is intentional: this path is **relative to the skill folder** (the directory containing this SKILL.md), **never** an absolute path. Most agents that load skills from an uploaded `.zip` extract the package into a working directory and expose its contents via that relative path — read the file by joining the skill's own root directory with `./templates/report.html.template`. Do not rewrite this to an absolute path that points at the author's machine.
2. **Build a single JSON object** (`__ZDX_DATA__` payload) shaped exactly as documented in the *Data Payload Contract* section below. Aggregate the responses from the ZDX MCP tool calls (Steps 1–5 of the *Workflow*) into that object.
3. **Replace** the literal token `__ZDX_DATA__` (which appears once, inside `<script type="application/json" id="zdx-data">__ZDX_DATA__</script>`) with the JSON object. Do not edit any other part of the template.
4. **Write** the result to disk as `user_experience_diagnosis_<YYYYMMDD-HHMMSS>.html` next to the .docx, and give the user a `computer://` link to it.
This template already provides: Zscaler header with logo · sticky top bar · scope summary bar · KPI cards with severity-coded top borders · per-table search + filter chips · sortable color-coded tables · per-table CSV export · light/dark theme toggle · top-right language dropdown (EN / ES / PT / FR / JA) · printable PDF view · localStorage prefs · Analysis / Root Cause / Remediation block.
**If you find yourself writing `<html>`, `<style>`, or `<table>` in a code-block destined for the user, stop. Read the template instead.**
A populated reference rendering ships with this skill at `./example/report.example.html` (relative to the skill folder). Open it in a browser to preview the exact layout and depth expected.
### Data Payload Contract
The full `__ZDX_DATA__` payload is one JSON object. Every field below is **required** unless marked optional. This skill emits **two tables**: the device/user summary and the per-metric breakdown.
```json
{
"generated_at": "<ISO 8601 timestamp>",
"scope_en": "Free-form description in English",
"scope_es": "...in Spanish (optional, falls back to scope_en)",
"scope_pt": "...in Portuguese (optional)",
"scope_fr": "...in French (optional)",
"scope_ja": "...in Japanese (optional)",
"kpis": {
"user": "<user name or email>",
"device": "<device hostname or model>",
"score": "<int, 0-100>",
"bottleneck": "DNS | TCP | SSL | Server | Page Load | —",
"alerts": "<int>"
},
"tables": {
"summary": [
{ "severity": "neutral", "field": "User", "value": "<name (email)>" },
{ "severity": "neutral", "field": "Device", "value": "<device_type, os_version>" },
{ "severity": "neutral", "field": "Location", "value": "<location>" },
{ "severity": "neutral", "field": "Department", "value": "<department>" },
{ "severity": "neutral", "field": "ZCC Version","value": "<version>" },
{ "severity": "critical | warning | good", "field": "Experience Score", "value": "<score>/100 (<label>)" }
],
"metrics": [
{
"severity": "critical | warning | good",
"name": "DNS Resolution | TCP Connect | SSL Handshake | Server Response | Page Load",
"current": "<e.g. '850ms' | 'Timeout' | 'N/A'>",
"normal": "<e.g. '< 100ms'>",
"category": "DNS | Network | Server | Client",
"status": "OK | Degraded | Critical",
"impact": "<short user-facing impact, e.g. 'Application unreachable'>"
}
]
},
"analysis": {
"summary": "...",
"rootCause": "...",
"remediation": [
{ "priority": "Immediate | Investigate | Monitor | Communicate", "action": "..." }
]
}
}
```
Map each row's `severity` from `status`: `OK` → `good`, `Degraded` → `warning`, `Critical` → `critical`. The static summary rows are `neutral` except the Experience Score row, which carries the same severity bucket as the user's overall score.
## Output Artifacts — MANDATORY
You MUST generate BOTH files below. Both are REQUIRED output for every user experience diagnosis.
### 1. Word Document (.docx) — REQUIRED
Write a Word document to disk named `user_experience_diagnosis_<YYYYMMDD-HHMMSS>.docx` containing:
- User and device summary (name, email, device type, OS, location, department)
- Application experience scores with trend analysis
- Metric breakdown (DNS, TCP connect, SSL handshake, server response, page load)
- Root cause analysis with supporting evidence
- Alert correlation (if any active alerts match the issue)
- Recommended resolution steps prioritized by impact
### 2. Interactive HTML Web Page (.html) — REQUIRED
Generated by the template-substitution flow described in the **HTML OUTPUT** section above. Filename: `user_experience_diagnosis_<YYYYMMDD-HHMMSS>.html`. Do not hand-author HTML or CSS — the template ships everything the report needs.
---
## Workflow
Follow this 5-step process to troubleshoot user experience.
### Step 1: Find the User's Device
```text
zdx_list_devices(search="<username_or_email>")
```text
Note the device ID, OS, ZDX agent version, and last active timestamp. If multiple devices, confirm which one the user is working on.
```text
zdx_get_device(device_id="<device_id>")
```text
Check device-level health:
- CPU utilization
- Memory usage
- Disk usage
- Network adapter status
- ZCC tunnel status
---
### Step 2: Check Application Experience Scores
**List monitored applications:**
```text
zdx_list_applications()
```text
**Get the score trend for the affected application:**
```text
zdx_get_application_score_trend(app_id="<app_id>")
```text
**Interpret scores:**
- **80-100:** Good experience -- issue may be intermittent or resolved
- **50-79:** Degraded -- one or more metrics are outside normal range
- **0-49:** Poor -- significant performance degradation
**Get application details:**
```text
zdx_get_application(app_id="<app_id>")
```text
---
### Step 3: Analyze Detailed Metrics
``Related in General
modeling-omnistudio-epc-catalog
IncludedSalesforce Industries CME EPC product-modeling skill for Product2-based catalog creation. Use when creating EPC products, configuring product attributes, building offer bundles with Product Child Items, or reviewing EPC DataPack JSON metadata for product catalog changes. TRIGGER when: user creates or updates Product2 EPC records, AttributeAssignment payloads, AttributeMetadata/AttributeDefaultValues, Offer bundles, or ProductChildItem relationships. DO NOT TRIGGER when: designing OmniScripts/FlexCards/Integration Procedures (use building-omnistudio-omniscript, building-omnistudio-flexcard, or building-omnistudio-integration-procedure), implementing Apex business logic (use generating-apex), or troubleshooting deployment pipelines (use deploying-metadata).
relationship-science-coach
IncludedUse this skill for direct, practical adult relationship coaching: couples conflict, repair, trust, marriage, dating, flirting, attachment patterns, emotional connection, sex, desire differences, eroticism, kink negotiation, affection, love languages, breakups, and long-term passion. Draw on Gottman, EFT and Hold Me Tight, attachment science, modern sex research, Perel, Nagoski, Kerner, Schnarch, Love and Stosny, and flexible love-language tools. Be concrete and low-hedge. Redirect only for imminent danger, abuse, coercive control, minors, non-consent, self-harm, stalking, or medical/legal/psychiatric decisions.
building-sf-integrations
IncludedSalesforce integration architecture and runtime plumbing with 120-point scoring. Use this skill to set up Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, and Change Data Capture. TRIGGER when: user sets up Named Credentials, External Services, REST/SOAP callouts, Platform Events, CDC, or touches .namedCredential-meta.xml files. DO NOT TRIGGER when: Connected App/OAuth config (use configuring-connected-apps), Apex-only logic (use generating-apex), or data import/export (use handling-sf-data).
venue-templates
IncludedAccess comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues (Nature, Science, PLOS, IEEE, ACM), academic conferences (NeurIPS, ICML, CVPR, CHI), research posters, and grant proposals (NSF, NIH, DOE, DARPA). This skill should be used when preparing manuscripts for journal submission, conference papers, research posters, or grant proposals and need venue-specific formatting requirements and templates.
let-fate-decide
IncludedDraws the 12 Houses of the Zodiac Tarot spread to inject entropy into planning when prompts are vague, ambiguous, or casually delegated. Interprets the spread to guide next steps. Use when the user says 'let fate decide', 'YOLO', 'whatever', 'idk', or other nonchalant phrases, makes Yu-Gi-Oh references, or when you are about to arbitrarily pick between multiple reasonable approaches. Prefer over ask-questions-if-underspecified when the user's tone is casual or playful rather than precision-seeking.
net-ops
IncludedCross-platform network troubleshooting (Windows, macOS, Linux) via local or remote shell. Use for: DNS broken, can't resolve hostnames, nslookup/dig works but apps fail, NRPT, WFP, scutil, /etc/resolver, systemd-resolved, /etc/resolv.conf, NetworkManager, VPN DNS leak residue (ProtonVPN/Mullvad/WireGuard/AnyConnect), AV/firewall blocking DNS or DoH, Tailscale DNS interaction, intermittent connectivity, remote diagnostics over SSH.