zdx-compare-location-experience
Compare digital experience across locations, departments, and geolocations using ZDX data. Identifies which offices or regions have the best and worst experience for specific applications, detects location-specific issues, and provides optimization recommendations. Aligned with ZDX Copilot analytics and optimization use cases. Use when an administrator asks: 'Which office has the worst experience?', 'Compare application performance between locations', 'Is the Dallas office having network issues?', or 'Show me ZDX scores by department.'
What this skill does
# ZDX: Compare Location Experience
## Keywords
compare locations, location experience, office comparison, department comparison, regional performance, site health, location score, office performance, worst office, best practices, optimization, geographic analysis, location ranking
## Overview
Compare digital experience across different locations, departments, and geolocations to identify which sites perform best and worst. This skill uses ZDX filtering capabilities to break down application scores, metrics, alerts, and device health by organizational dimensions, enabling proactive optimization and targeted remediation.
**Use this skill when:** An administrator wants to compare application experience across offices, identify the worst-performing locations, investigate whether an issue is location-specific, or optimize network configuration for underperforming sites.
**ZDX Copilot alignment:** This skill covers the Analytics and Optimization categories -- comparing performance across organizational dimensions and recommending improvements.
---
## 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 the performance differences between locations and what they indicate
2. **Root cause identification** for underperforming locations (DNS, ISP, WiFi, device fleet age, etc.)
3. **Next steps / resolution** with site-specific remediation actions prioritized by impact and feasibility
Use color-coded rows based on location ranking:
- Green: Top-performing locations (score 66-100)
- Yellow: Borderline locations (score 34-65)
- Red: Worst-performing locations (score 0-33)
## ⚠ 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–7 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 `location_comparison_report_<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.
```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": {
"totalLocations": "<int>",
"bestLocation": "<location name>",
"worstLocation": "<location name>",
"avgScore": "<int, 0-100>",
"alertCount": "<int>"
},
"tables": {
"locations": [
{
"severity": "critical | warning | good",
"rank": "<int>",
"name": "<location name>",
"score": "<0-100>",
"pft": "<page fetch time, e.g. '1.8s'>",
"dns": "<dns time, e.g. '18ms'>",
"availability": "<percentage, e.g. '100%'>",
"poorUsers": "<e.g. '0/120'>",
"alerts": "<int>"
}
]
},
"analysis": {
"summary": "...",
"rootCause": "...",
"remediation": [
{ "priority": "Immediate | Investigate | Monitor | Communicate", "action": "..." }
]
}
}
```
Map each row's `severity` from its tier: top (score ≥ 80) → `good`, borderline (50–79) → `warning`, poor (< 50) → `critical`.
## Output Artifacts — MANDATORY
You MUST generate BOTH files below. Both are REQUIRED output for every location comparison.
### 1. Word Document (.docx) — REQUIRED
Write a Word document to disk named `location_comparison_report_<YYYYMMDD-HHMMSS>.docx` containing:
- Executive summary with best/worst performing locations
- Location ranking table (rank, location, score, PFT, DNS, availability, poor users, alerts)
- Per-location analysis for underperforming sites with metric breakdowns
- Root cause analysis for worst performers (DNS, ISP, WiFi, device fleet)
- Cross-location metric comparison for each application
- Site-specific remediation actions prioritized by impact
### 2. Interactive HTML Web Page (.html) — REQUIRED
Generated by the template-substitution flow described in the **HTML OUTPUT** section above. Filename: `location_comparison_report_<YYYYMMDD-HHMMSS>.html`. Do not hand-author HTML or CSS — the template ships everything the report needs.
---
## Workflow
### Step 1: List Available Locations and Departments
First, enumerate the organizational dimensions available for comparison.
**List locations:**
```text
zdx_list_locations()
```text
**List departments:**
```text
zdx_list_departments()
```text
Note the IDs returned -- these are used as filters in subsequent calls.
---
### Step 2: Compare Application Scores Across Locations
For each application of interest, retrieve scores filtered by different locations.
**Location A:**
```text
zdx_list_applications(location_id=["<location_a_id>"], since=24)
```text
**Location B:**
```text
zdx_list_applications(location_id=["<location_b_id>"], since=24)
```text
**Location C:**
```text
zdx_list_applications(location_id=["<location_c_id>"], since=24)
```text
Compile the scores side by side to identify which locations are underperforming.
---
### Step 3: Drill Into Score Trends for Underperforming Locations
For the worst-performing location, check the score trend.
```text
zdx_get_application_score_trend(
app_id="<app_id>",
location_id=["<worst_location_id>"],
since=24
)
```text
Compare with a healthy location:
```text
zdx_get_application_score_trend(
app_id="<app_id>",
location_id=["<healthy_location_id>"],
since=24
)
```text
**What to look for:**
- Does the underperforming location show a consistent low score or a sudden drop?
- Does the score correlate with specific times of day (peak hours)?
- Are multiple applications affected at this location, or just one?
---
### Step 4: CRelated in Data & Analytics
clawarr-suite
IncludedComprehensive management for self-hosted media stacks (Sonarr, Radarr, Lidarr, Readarr, Prowlarr, Bazarr, Overseerr, Plex, Tautulli, SABnzbd, Recyclarr, Unpackerr, Notifiarr, Maintainerr, Kometa, FlareSolverr). Deep library exploration, analytics, dashboard generation, content management, request handling, subtitle management, indexer control, download monitoring, quality profile sync, library cleanup automation, notification routing, collection/overlay management, and media tracker integration (Trakt, Letterboxd, Simkl).
querying-soql
IncludedSOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use handling-sf-data), Apex DML logic (use generating-apex), or report/dashboard queries.
app-store-optimization
IncludedApp Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store. Use when the user asks about ASO, app store rankings, app metadata, app titles and descriptions, app store listings, app visibility, or mobile app marketing on iOS or Android. Supports keyword research and scoring, competitor keyword analysis, metadata optimization, A/B test planning, launch checklists, and tracking ranking changes.
habit-flow
IncludedAI-powered atomic habit tracker with natural language logging, streak tracking, smart reminders, and coaching. Use for creating habits, logging completions naturally ("I meditated today"), viewing progress, and getting personalized coaching.
app-store-optimization
IncludedApp Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store. Use when the user asks about ASO, app store rankings, app metadata, app titles and descriptions, app store listings, app visibility, or mobile app marketing on iOS or Android. Supports keyword research and scoring, competitor keyword analysis, metadata optimization, A/B test planning, launch checklists, and tracking ranking changes.
visualizing-data
IncludedBuilds dashboards, reports, and data-driven interfaces requiring charts, graphs, or visual analytics. Provides systematic framework for selecting appropriate visualizations based on data characteristics and analytical purpose. Includes 24+ visualization types organized by purpose (trends, comparisons, distributions, relationships, flows, hierarchies, geospatial), accessibility patterns (WCAG 2.1 AA compliance), colorblind-safe palettes, and performance optimization strategies. Use when creating visualizations, choosing chart types, displaying data graphically, or designing data interfaces.