
adobe-analytics
Practitioner skills for Adobe Analytics via the AA MCP server
- version
- 1.0.0
- GitHub stars
- 332
Install
/plugin install adobe-analytics@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 5
Conversion Funnel Analysis (Adobe Analytics)
Analyze a multi-step conversion funnel to identify where visitors drop off, which steps have the worst leakage, and what drives visitors to convert or abandon. Uses AA visit-level segment-based reporting to simulate funnel steps.
AA Container Model: AA funnels use hit, visit, and visitor containers — not CJA's event/session/person. Funnel steps are defined as visit-level segments (visitors who completed the step during a visit).
Reporting approach: AA does not have a native sequential fallout API accessible via MCP. This skill approximates fallout by creating or finding visit-level segments for each funnel step, then running the metric for each step segment to compute pass-through rates.
AA MCP Tools Used
findReportSuites— select report suitesetSessionDefaults— set session context (reportSuiteId + globalCompanyId)findDimensions— discover page/event dimensions for step definitionfindMetrics— find visits or orders as the counting metricsearchDimensionItems— validate page names or event valuesfindSegments— find existing step segments if availableupsertSegment— create visit-level step segments if not foundrunReport— run visits count for each step segment
Phase 0 — Setup
- Confirm report suite with
findReportSuites/setSessionDefaults. - Ask the user about the overall funnel scope (visit or visitor level):
- Visit-level funnel: all steps happen within a single visit (typical for checkout funnels)
- Visitor-level funnel: steps can span multiple visits (typical for lifecycle funnels)
findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
Phase 1 — Define the Funnel Steps
Ask the user to describe each step of the funnel in plain language. Prompt for 3–8 steps. Example:
- Product page viewed
- Add to cart
- Checkout started
- Payment info entered
- Order confirmed (purchase)
For each step, ask:
- "Is this defined by a page view (page name or URL), a custom event, or a combination?"
- "Should this step be at the hit level (single page/event) or visit level (any visit where this happened)?"
Phase 2 — Discover Components
2.1 Validate page names
For page-based steps:
findDimensions(page: 1, limit: 500) # returns all available dimensions; look for variables/page
searchDimensionItems(
dimensionId: "variables/page",
searchOr: "<step page keywords>", # space-separated keywords OR'd together
startDate: "<start>",
endDate: "<end>",
page: 1,
limit: 20
)
Common page dimension IDs: variables/page, variables/entrypage, variables/exitpage.
Confirm the correct page name value with the user if multiple matches exist.
Note:
searchDimensionItemsusessearchOrorsearchAndfor filtering — notsearchTerm. If no rows return, try a wider date range — some report suites only have historical data.
2.2 Validate events/metrics
For event-based steps (add to cart, checkout, purchase):
findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter results locally by name: visits, orders, pageviews, etc.
Phase 3 — Find or Create Step Segments
For each funnel step, search for an existing segment:
findSegments(searchTerm: "<step description>")
If an appropriate visit-level segment exists, use it directly.
If not, create a new visit-level segment for each step:
upsertSegment(
definition: {
"name": "Visit: Checkout Started",
"description": "Visits where the visitor reached the checkout page",
"reportSuiteID": "<rsid>",
"container": {
"func": "segment",
"context": "visits",
"pred": {
"func": "streq",
"val": "/checkout",
"str": "/checkout",
"dimension": "variables/page"
}
},
"tags": [{ "name": "funnel" }]
}
)
Create all step segments before running reports. Record each segment id.
Important: Only create new segments with explicit user confirmation. Present the list of segments to be created and ask: "I need to create N visit-level segments to define your funnel steps. Is that OK?"
Phase 4 — Run Funnel Step Reports
For each step segment, run the visits count over the analysis period:
runReport(
dimensionId: "variables/page", # required by AA runReport
metricIds: "metrics/visits", # note: plural field name "metricIds"
segmentIds: "<step segment id>", # note: plural field name "segmentIds"
startDate: "<start>",
endDate: "<end>",
limit: 1
)
# summaryData.totals[0] is the total visits for this segment
This is 1 call per funnel step. For a 5-step funnel = 5 calls.
Also run total visits (no segment) as the 100% baseline:
runReport(
dimensionId: "variables/page",
metricIds: "metrics/visits",
startDate: "<start>",
endDate: "<end>",
limit: 1
)
# Use summaryData.totals[0] as the baseline visit count
AA runReport field names: Use
metricIds(notmetricId) andsegmentIds(notsegmentId). UsestartDate/endDate(ISO 8601) rather than adateRangeobject. Always read totals fromsummaryData.totals[0], not fromrows.
Phase 5 — Compute Funnel Metrics
For each step, compute:
| Metric | Formula |
|---|---|
| Step visits | Raw count from runReport |
| Step conversion rate | Step visits / Total visits × 100 |
| Step-to-step rate | Step N visits / Step N-1 visits × 100 |
| Step-to-step drop-off | Step N-1 visits - Step N visits |
| Drop-off rate | 100 - step-to-step rate |
Identify the biggest leakage step (highest absolute drop-off count) and the weakest conversion step (lowest step-to-step rate).
Phase 6 — Drill Into the Worst Step
For the step with the highest drop-off, run a dimension breakdown to find what differentiates visitors who progressed vs. those who dropped:
runReport(
dimensionId: "variables/mobiledevicetype",
metricIds: "metrics/visits",
segmentIds: "<worst step segment>",
startDate: "<start>",
endDate: "<end>",
limit: 10
)
runReport(
dimensionId: "variables/mobiledevicetype",
metricIds: "metrics/visits",
segmentIds: "<next step segment>",
startDate: "<start>",
endDate: "<end>",
limit: 10
)
Compare the device-type mix between visitors who completed the worst step and those who made it to the next step. Repeat for 1–2 other dimensions (e.g., traffic source, new vs. returning).
Phase 7 — Generate HTML Report
Build the funnel report inline and write to
/tmp/aa_funnel_analysis_report_<YYYY-MM-DD_HHMMSS>.html.
HTML template
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Funnel Health — {ORG_NAME} — {FUNNEL_NAME}</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
:root {
--bg: #f5f4f1;
--surface: #ffffff;
--ink: #1a1a1a;
--ink-muted: #6b6b6b;
--border: #e5e2dc;
--header-bg: #0e0e10;
--header-warm: #3a1010;
--accent-red: #c8312f;
--accent-red-bright: #ff6b68;
--accent-red-soft: #fdecea;
--accent-green: #1f7a4d;
--accent-yellow: #d4a017;
}
body { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
background: var(--bg); color: var(--ink); line-height: 1.5;
-webkit-font-smoothing: antialiased; }
/* === Header === */
header { background: linear-gradient(120deg, var(--header-bg) 0%, #1a0d0d 55%, var(--header-warm) 100%);
color: #fff; padding: 56px 56px 44px; position: relative; overflow: hidden; }
header::after { content: ""; position: absolute; right: -140px; top: -140px;
width: 460px; height: 460px;
background: radial-gradient(circle, rgba(200,49,47,.35) 0%, transparent 70%);
pointer-events: none; }
.header-inner { max-width: 1080px; margin: 0 auto; position: relative; z-index: 1; }
.eyebrow { display: inline-flex; align-items: center; gap: 8px;
padding: 6px 14px; border: 1px solid rgba(255,107,104,.55);
border-radius: 999px; color: var(--accent-red-bright);
font-size: 11px; font-weight: 600; letter-spacing: 1.2px;
text-transform: uppercase; margin-bottom: 24px;
background: rgba(200,49,47,.10); }
.eyebrow::before { content: ""; width: 6px; height: 6px;
background: var(--accent-red-bright); border-radius: 50%; }
header h1 { font-family: "Playfair Display", Georgia, serif;
font-size: 56px; font-weight: 700; letter-spacing: -1.5px;
line-height: 1.05; margin-bottom: 14px; color: #fff; }
header .lede { font-size: 16px; max-width: 600px;
color: rgba(255,255,255,.80); margin-bottom: 24px;
line-height: 1.55; }
header .meta { display: flex; flex-wrap: wrap; gap: 22px;
font-size: 13px; color: rgba(255,255,255,.60); }
header .meta span { display: inline-flex; align-items: center; gap: 6px; }
header .meta .icon { opacity: .8; }
/* === Tabs === */
nav { background: var(--surface); border-bottom: 1px solid var(--border);
padding: 0 56px; display: flex; gap: 28px;
position: sticky; top: 0; z-index: 50; }
nav a { display: block; padding: 16px 0; font-size: 14px;
color: var(--ink); text-decoration: none;
border-bottom: 2px solid transparent;
transition: border-color .15s ease; }
nav a:hover { border-bottom-color: var(--accent-red); }
/* === Container === */
.container { max-width: 1080px; margin: 0 auto; padding: 36px 56px 60px; }
/* === Section label === */
.section-label { font-size: 11px; font-weight: 700;
text-transform: uppercase; letter-spacing: 1.4px;
color: var(--ink-muted); margin-bottom: 14px;
padding-bottom: 10px; border-bottom: 1px solid var(--border); }
/* === Funnel visualization (horizontal stepped bars) ===
Bar color is set per step by tier:
.tier-strong = green (rate >= 70% pass-through)
.tier-mid = yellow (40-69%)
.tier-weak = red (< 40%)
The biggest-leakage step also gets .step-bar.worst (red, regardless of tier). */
.funnel-wrap { background: var(--surface); border-radius: 8px;
padding: 28px 32px; margin-bottom: 28px;
box-shadow: 0 1px 3px rgba(0,0,0,.04); }
.funnel-step { display: flex; align-items: center; margin-bottom: 10px; }
.step-label { width: 220px; font-size: 14px; font-weight: 600;
text-align: right; padding-right: 16px; white-space: nowrap;
overflow: hidden; text-overflow: ellipsis; color: var(--ink); }
.step-bar-wrap { flex: 1; position: relative; height: 44px;
background: #f4f1eb; border-radius: 4px; }
.step-bar { height: 44px; border-radius: 4px;
display: flex; align-items: center; padding: 0 14px;
color: #fff; font-size: 13px; font-weight: 700;
transition: width 0.4s ease;
background: var(--accent-green); }
.step-bar.tier-strong { background: var(--accent-green); }
.step-bar.tier-mid { background: var(--accent-yellow); color: #3a2a05; }
.step-bar.tier-weak { background: var(--accent-red); }
.step-bar.worst { background: var(--accent-red); color: #fff; }
.step-meta { width: 200px; padding-left: 16px; font-size: 12px;
color: var(--ink-muted); }
.step-meta .rate { font-family: "Playfair Display", Georgia, serif;
font-size: 18px; font-weight: 700;
color: var(--ink); line-height: 1; }
.step-meta .drop { color: var(--accent-red); font-weight: 600;
display: block; margin-top: 4px; }
/* === Collapsible sections === */
.section { background: var(--surface); border-radius: 8px;
box-shadow: 0 1px 3px rgba(0,0,0,.04);
margin-bottom: 22px; overflow: hidden; }
.section-header { padding: 18px 28px; border-bottom: 1px solid var(--border);
display: flex; justify-content: space-between;
align-items: center; cursor: pointer; user-select: none; }
.section-header h2 { font-family: "Playfair Display", Georgia, serif;
font-size: 18px; font-weight: 700; }
.toggle { font-size: 16px; color: var(--accent-red); }
/* === Tables === */
table { width: 100%; border-collapse: collapse; font-size: 13px; }
thead th { background: #faf8f4; padding: 12px 22px;
text-align: left; font-weight: 600;
text-transform: uppercase; letter-spacing: .6px;
font-size: 11px; color: var(--ink-muted);
border-bottom: 1px solid var(--border); }
tbody td { padding: 12px 22px; border-bottom: 1px solid #f4f1eb; }
tbody tr:last-child td { border-bottom: none; }
/* === Badges === */
.badge { display: inline-block; padding: 3px 9px; border-radius: 4px;
font-size: 11px; font-weight: 600; }
.badge.green { background: #ebf5ef; color: var(--accent-green); }
.badge.yellow { background: #fef6e3; color: #b67a08; }
.badge.red { background: var(--accent-red-soft); color: var(--accent-red); }
/* === Insight callout === */
.insight { background: var(--accent-red-soft);
border-left: 4px solid var(--accent-red);
border-radius: 6px; padding: 16px 22px;
margin: 16px 28px; font-size: 14px; line-height: 1.6;
color: #4a2222; }
.back-top { position: fixed; bottom: 24px; right: 24px; background: var(--accent-red);
color: #fff; width: 44px; height: 44px; border-radius: 50%; border: none;
font-size: 20px; cursor: pointer;
box-shadow: 0 4px 12px rgba(200,49,47,.35); }
footer { text-align: center; padding: 32px 24px;
font-size: 12px; color: var(--ink-muted); }
/* === Print === */
@media print {
nav { display: none; position: static; }
header { padding: 36px 32px 28px; }
header h1 { font-size: 42px; }
.section-header { cursor: default; }
.back-top { display: none; }
.funnel-wrap, .section {
box-shadow: none; border: 1px solid var(--border); break-inside: avoid;
}
}
</style>
</head>
<body>
<header>
<div class="header-inner">
<div class="eyebrow">Funnel Health Report</div>
<h1>{ORG_NAME} Funnel Health</h1>
<p class="lede">Step-by-step pass-through for the {FUNNEL_NAME} funnel during {DATE_RANGE}.</p>
<div class="meta">
<span><span class="icon">📅</span> {DATE_RANGE}</span>
<span><span class="icon">📊</span> {REPORT_SUITE}</span>
<span><span class="icon">🕔</span> Prepared {GENERATED_DATE}</span>
</div>
</div>
</header>
<nav>
<a href="#funnel">Funnel</a>
<a href="#steps">Step Detail</a>
<a href="#leakage">Leakage Analysis</a>
<a href="#recommendations">Recommendations</a>
</nav>
<div class="container">
<!-- Funnel Visualization -->
<div class="section-label">Funnel Pass-Through</div>
<div id="funnel" class="funnel-wrap">
<!-- One .funnel-step per step:
- Bar width = (step visits / total visits) * 100%
- Apply tier class to .step-bar based on step pass-through rate:
tier-strong (>=70%), tier-mid (40-69%), tier-weak (<40%)
- Worst step also gets .step-bar.worst (red, always)
-->
</div>
<!-- Step Detail Table -->
<div id="steps" class="section">
<div class="section-header" onclick="toggle('steps-body')">
<h2>Step Detail</h2>
<span class="toggle" id="steps-body-icon">▾</span>
</div>
<div id="steps-body">
<table>
<thead><tr>
<th>Step</th><th>Visits</th><th>% of Total</th>
<th>Step Rate</th><th>Drop-off</th>
</tr></thead>
<tbody><!-- step rows with badge coloring on step rate --></tbody>
</table>
</div>
</div>
<!-- Leakage Analysis -->
<div id="leakage" class="section">
<div class="section-header" onclick="toggle('leak-body')">
<h2>Leakage Analysis (Worst Step: {WORST_STEP_NAME})</h2>
<span class="toggle" id="leak-body-icon">▾</span>
</div>
<div id="leak-body">
<div class="insight">{LEAKAGE_INSIGHT_TEXT}</div>
<table>
<thead><tr>
<th>Dimension</th><th>Entered Step</th><th>Completed Step</th>
<th>Step Rate</th><th>vs. Average</th>
</tr></thead>
<tbody><!-- leakage breakdown rows --></tbody>
</table>
</div>
</div>
<!-- Recommendations -->
<div id="recommendations" class="section">
<div class="section-header" onclick="toggle('rec-body')">
<h2>Recommendations</h2>
<span class="toggle" id="rec-body-icon">▾</span>
</div>
<div id="rec-body">
<!-- insight divs with specific recommendations per step -->
</div>
</div>
</div>
<button class="back-top" onclick="window.scrollTo({top:0,behavior:'smooth'})">
⇧
</button>
<footer>Funnel Health — {ORG_NAME} — Generated {GENERATED_DATE}</footer>
<script>
function toggle(id) {
var el = document.getElementById(id);
var ic = document.getElementById(id + '-icon');
if (el.style.display === 'none') { el.style.display = ''; ic.textContent = '\u25be'; }
else { el.style.display = 'none'; ic.textContent = '\u25b8'; }
}
</script>
</body>
</html>
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "Funnel Overview" not "Phase 2 — Funnel Overview", "Drop-off Analysis" not "Phase 3 — Drop-off Analysis").
Write to /tmp/aa_funnel_analysis_report_<YYYY-MM-DD_HHMMSS>.html and open:
open /tmp/aa_funnel_analysis_report_<YYYY-MM-DD_HHMMSS>.html
Guardrails
- Always present the list of segments to be created (step 3) and get user
confirmation before calling
upsertSegment. - If the user already has named segments for funnel steps, prefer using those
rather than creating new ones — check
findSegmentsfirst. - Limit funnel to 8 steps maximum for practical API call budgets.
- Funnel conversion rates using visit segments are approximations — they count visits that touched each step, not strict sequential fallout. Note this limitation to the user.
Example Interaction
"Analyze our checkout funnel — I want to see where visitors drop off."
- Confirm report suite and date range (last 30 days).
- Define 5 steps: Product View → Add to Cart → Checkout → Payment → Purchase.
- Validate page names with
searchDimensionItems. - Find existing step segments or create new ones (with user approval).
- Run 6 reports (5 steps + total).
- Compute: 100% → 42% (add to cart) → 28% (checkout) → 19% (payment) → 11% (purchase). Overall conversion: 11%.
- Worst step: Add-to-Cart to Checkout (33% drop-off rate).
- Drill in: Mobile users have only 18% checkout rate vs. 31% on Desktop.
- Generate and open HTML report.
- Key insight: "Mobile is your funnel's biggest liability. Consider simplifying the mobile checkout experience."
Executive Briefing (Adobe Analytics)
Generate a concise, executive-ready performance summary with narrative context, metric highlights, and key drivers. Designed for leadership audiences — no raw data dumps, just clear signals and business implications.
Key parameter facts validated during implementation:
runReport→metricIds(plural), notmetricId; dates asYYYY-MM-DDTHH:mm:ssfindMetrics→expansionsis a required parameter (use"componentType")describeAa→ parameter isguideType, notguide;REPORT_SUITE_CONTEXT_GUIDEmay return empty for some report suites — skip gracefully and proceedmetrics/uniquevisitorsis often unauthorized — usemetrics/visitsinsteadsetSessionDefaultsis the correct tool name (notsetDefaultReportSuite)
AA MCP Tools Used
findReportSuites— select report suitesetSessionDefaults— set session context (reportSuiteId + globalCompanyId)describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")— load org context; note: may return no output for some report suites — proceed without itfindMetrics(expansions: "componentType")— resolve metric IDs (expansions parameter is required)listComponentUsage(componentType: "metric")— identify most-used metrics if not specified by the userrunReport— current and comparison period with all metrics batched in one call (metricIdsaccepts comma-separated IDs); dimension breakdowns for top moverssearchDimensionItems— validate dimension values for driver callouts
Phase 0 — Setup
- Confirm report suite.
- Load organizational context:
findReportSuites()
setSessionDefaults(reportSuiteId: "<rsid>", globalCompanyId: "<companyId>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE") # may return empty — proceed if so
Use the context guide to understand:
- The organization's name and industry
- Which metrics are most used (top KPIs)
- Calendar conventions and timezone. Record these values — they are
inputs to every date computation in Phase 1:
WEEK_START_DOW— day of week each week starts on. Default: Monday (ISO 8601).FISCAL_YEAR_START_MONTH— month the fiscal year begins. Default: January (calendar year).TIMEZONE— for example,America/Los_Angeles.CALENDAR_SOURCE— one of"context guide","default fallback", or"user override".
- Any active report suite segments
Phase 1 — Clarify the Briefing
Ask the user:
- Period — "What time period should this briefing cover?"
- Last week
- Last month
- Month-to-date (MTD)
- This quarter / QTD
- Last quarter
- Custom date range
The principle
Two runs of this skill on the same report suite, period type, and prompt MUST
produce identical current and comparison date ranges. Determinism comes
from (a) reading calendar conventions from Phase 0 instead of improvising, and
(b) applying the alignment rule for the period type without taste calls.
Period type → alignment rule
Pick exactly one period type from the user's request:
| User request | PERIOD_TYPE | Current period | Comparison period |
|---|---|---|---|
| "last week" | weekly | Most recent full week ending before today, aligned to WEEK_START_DOW (exactly 7 days) | The week immediately before, same alignment |
| "this month" / "MTD" | month-to-date | 1st of current month → today | 1st of prior month → same day-of-month as today |
| "last month" | monthly | Prior full calendar month | The month before that |
| "this quarter" / "QTD" | quarter-to-date | Start of current fiscal quarter → today; fiscal quarters derived from FISCAL_YEAR_START_MONTH | Same days into the prior fiscal quarter |
| "last quarter" / "Q[N]" | quarterly | Prior full fiscal quarter | The fiscal quarter before that |
| Custom date range | custom | Use as specified | Equal-length window ending the day before current.startDate |
Universal invariants (must hold for every period type)
Before calling runReport, verify all six:
current.startDate < current.endDatecomparison.startDate < comparison.endDatecomparison.endDate < current.startDate(no overlap)- The day after
comparison.endDateequalscurrent.startDate(contiguous) currentandcomparisonhave the same length in days- The alignment rule for
PERIOD_TYPEis satisfied:weekly: bothstartDates fall onWEEK_START_DOWmonthly: bothstartDates fall on the 1st of a monthmonth-to-date: bothstartDates fall on the 1st; bothendDates have the same day-of-monthquarterly: bothstartDates fall on the first day of a fiscal quarterquarter-to-date: bothstartDates fall on a fiscal quarter start; bothendDates are the same number of days into the quartercustom: lengths match; contiguity holds
If ANY invariant fails, recompute the dates. Never paper over a mismatch by editing the footer.
Worked examples — today is Tuesday, May 26, 2026
Assumes WEEK_START_DOW = Sunday and FISCAL_YEAR_START_MONTH = January. Numbers change for other calendars — that's the point.
| User request | PERIOD_TYPE | Current | Comparison |
|---|---|---|---|
| "last week" | weekly | May 17 (Sun) – May 23 (Sat) | May 10 (Sun) – May 16 (Sat) |
| "this month" / "MTD" | month-to-date | May 1 – May 26 | Apr 1 – Apr 26 |
| "last month" | monthly | Apr 1 – Apr 30 | Mar 1 – Mar 31 |
| "this quarter" / "QTD" | quarter-to-date | Apr 1 – May 26 | Jan 1 – Feb 24 |
| "last quarter" | quarterly | Jan 1 – Mar 31 | Oct 1 – Dec 31 (2025) |
| Custom: "May 15–22" | custom | May 15 – May 22 (8 days) | May 7 – May 14 (8 days) |
If WEEK_START_DOW = Monday instead, the weekly row becomes May 18 (Mon) – May 24 (Sun) vs May 11 (Mon) – May 17 (Sun). The other rows are unchanged.
A common AI failure mode
The AI may "know" from training data that weeks are Mon–Sun (ISO 8601) or that
quarters are Q1=Jan–Mar (calendar). Silently overriding the context guide with
those defaults is exactly the determinism bug this section exists to prevent.
The footer's methodology line MUST accurately describe the dates you computed
— if footer says "weeks start Sunday" but current.startDate is a Monday,
that's a bug to fix in the dates, not in the footer.
-
Audience — "Who is this briefing for?"
- C-suite / board (highest level, fewest metrics, most context)
- VP/Director level (more detail, some dimension context)
- Marketing leadership (channel and campaign focus) Default: C-suite tone (concise, business-focused).
-
North-star metric — "What is the single most important metric for this briefing?" (e.g., revenue, conversions, retention rate) If not specified, use the most-used metric from
listComponentUsage. -
Supporting metrics — "What other metrics should be included? (up to 5)"
-
Specific topic focus — "Is there anything you want to highlight or investigate? (e.g., mobile performance, campaign results)"
Phase 2 — Resolve Metrics
findMetrics(expansions: "componentType") # expansions required
listComponentUsage(componentType: "metric") # if metrics not specified
Important:
findMetricsrequires theexpansionsparameter (use"componentType"as a safe default). Without it the call will fail.Avoid
metrics/uniquevisitors— this metric is frequently restricted and returns an "unauthorized_metric" error. Prefermetrics/visitsfor audience size.Reliable standard metrics for AA briefings:
metrics/pageviews,metrics/visits,metrics/orders,metrics/revenue,metrics/bouncerate,metrics/occurrences
Deterministic selection — do not improvise
The KPI set MUST be reproducible across runs. Two runs of this skill on the same report suite + period must produce the same metric values, which requires selecting the same metric IDs every time. Follow this algorithm exactly:
- If the user named metrics explicitly, resolve each to ONE specific metric ID
via
findMetrics. On ambiguity, pick the metric with the highestusageCountfromlistComponentUsageand document the choice. - Otherwise, take
listComponentUsage(componentType: "metric")results, sort byusageCountdescending with metric ID alphabetical as the tiebreak (stable secondary sort), and take the top 6 metric IDs. - Use
describeMetricto resolve to display names. - Do NOT cherry-pick by metric "type" (volume vs conversion vs revenue) and
do NOT swap in an alternative metric because its name reads better in the
narrative. Different runs picking
metrics/ordersvs a calculated metric also called "Orders" produce wildly different numbers and break trust.
Always disclose the metric IDs used
Include a "Metrics included" line in the briefing artifact's footer listing the resolved metric IDs. This makes the report auditable and lets the user confirm a re-run is using the same metrics.
Record metric IDs and display names. Limit to 6 metrics total.
Phase 3 — Fetch Performance Data
Batch all metrics into a single runReport call per period:
runReport(
dimensionId: "variables/daterangeday",
metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
startDate: "<YYYY-MM-DDTHH:mm:ss>",
endDate: "<YYYY-MM-DDTHH:mm:ss>"
)
Critical: The
runReportparameter ismetricIds(plural), notmetricId. It accepts comma-separated IDs — pass all metrics in one call. Dates must be ISO 8601 with time component:2026-03-31T00:00:00/2026-04-06T23:59:59. Usevariables/daterangedayasdimensionIdto get a day-by-day breakdown; totals for each metric are insummaryData.totals[0],totals[1], etc. in order. If a metric is unauthorized, it surfaces incolumnErrors— the overall call still succeeds.
For 6 metrics: 2 calls total (current period + comparison period).
From each pair compute:
- Current total
- Prior total
- Absolute and percent delta
- Trend direction (up/flat/down)
Phase 4 — Driver Context
For the north-star metric and any metric with a change > ±10%, run a marketing channel breakdown to find what drove the movement:
runReport(
metricIds: "<northStarMetricId>",
dimensionId: "variables/marketingchannel",
startDate: "<current period start>T00:00:00",
endDate: "<current period end>T23:59:59",
limit: 8
)
Run the same for the comparison period if needed to identify share shift.
Also check device type if the user mentioned mobile:
runReport(
metricIds: "<northStarMetricId>",
dimensionId: "variables/mobiledevicetype",
startDate: "<current period start>T00:00:00",
endDate: "<current period end>T23:59:59",
limit: 5
)
Phase 5 — Write the Narrative
Compose the executive briefing as a structured narrative, not a data table. Tone: confident, clear, forward-looking. Avoid jargon. Use business language.
Narrative structure
-
Opening headline — 1 sentence capturing the period's overall result. "Q2 performance was strong, with revenue growing 14% and conversion rates reaching a 12-month high."
-
North-star metric — 2–3 sentences on the most important KPI: value, change, context, what drove it.
-
Supporting highlights — 1 sentence per additional metric (positive first, then concerns).
-
Key driver — 2 sentences identifying what primarily caused movement. "Paid Search drove 60% of revenue growth, up from 48% in the prior period. Email performance also improved materially with a 22% lift in conversions."
-
Risk or watch item — 1–2 sentences on anything concerning: "Bounce rate on mobile increased 4pp, suggesting friction in the mobile experience worth investigating."
-
Forward look / ask — optional: what does this imply for next period?
Phase 6 — Generate HTML Briefing Document
Build the executive briefing HTML and write to
/tmp/aa_executive_briefing_<YYYY-MM-DD_HHMMSS>.html.
Rendering rules — apply consistently across runs
Two runs of this skill on the same report suite + period must render identically (modulo the generation timestamp). The rules below pin the formatting choices that the AI would otherwise drift on.
Number formatting
- KPI values (the big number in each tile) — use full digits with
thousands separators (
8,160,77,584,1,250,000). Do NOT use SI suffixes likeKorM, even for large values. Executives want exact numbers, not abbreviations. - Percent change (in pills and narrative bullets) — always one decimal
place, rounded half-away-from-zero. For example,
−23.55%displays as−23.6%, never−23.5%. Compute on full-precision values; round only at display time. - Percentage-point change (for already-percentage metrics like Conversion
Rate or Bounce Rate) — same rounding, suffix
pp. Example:+0.40 pp. - Currency —
$prefix with thousands separators and no decimals for values ≥ $100 ($1,240,000); cents only when value < $100 ($45.20).
Null / missing data handling
A KPI tile must reflect what the report suite actually returned. The AI must not silently substitute a different metric or hide a tile to make the briefing look cleaner.
- Both periods return 0 or NULL for a metric in the resolved set: render
the tile with
kpi-value=Data unavailable, pill classflat, pill text⚠ N/A, andpriortext =Both periods returned no data — validate instrumentation. The tile stays in the grid; do not omit it. - One period returns valid data, the other 0 / NULL: render the tile with
the valid value as
kpi-value, pill classflat, pill text⚠ N/A, andpriortext =Prior {period_noun}: no data. - Never substitute a derived metric (e.g., adding "Conversion Rate" because Revenue came back $0). The visible KPI set MUST match the resolved metric IDs disclosed in the footer.
- If a Revenue / monetary metric is unavailable, surface a
.callout.noteabove the KPI grid explaining the gap. Do not invent a value.
HTML template
Template variables
Populate every {PLACEHOLDER} in the HTML template below using these rules.
The briefing belongs to the customer — never substitute Adobe, AA, or any
vendor language into customer-visible fields.
{ORG_NAME}— The customer's business or brand name, derived from the report suite context loaded in Phase 0. Strip technical/environment suffixes like— Prod,- Demo,Stage,Test,MCP. If the report suite name has no clean brand label, fall back to the report suite display name with suffixes removed. Do not invent a name and do not substitute a vendor name.{PERIOD_TYPE}— One ofWeekly,Monthly,Quarterly, orPerformance(default), chosen from the period inferred in Phase 1.{LEDE_SENTENCE}— Use exactly this pattern, with no vendor names:Leadership readout for the {period type lowercase} of {PERIOD_LABEL} compared to {COMPARISON_LABEL}.{REPORT_SUITE}— Report suite display name. Suffixes are acceptable here — this row is the technical identifier line, not the title.{PERIOD_LABEL}/{COMPARISON_LABEL}— Human-readable date ranges, e.g.,May 12–18, 2026.{GENERATED_DATE}— Today's date in the same human format.{METRIC_LABEL}/{FORMATTED_VALUE}/{PCT_CHANGE}/{PRIOR_VALUE}— Per-KPI values from Phase 3. Use the metric's customer-facing display name, not its internal ID.
HTML Template
Read template.html and use it verbatim. Do not improvise the
HTML structure or CSS — only fill in the {PLACEHOLDER} tokens documented
in Template variables above. Preserve the .up | .down | .flat and
.green | .red | .yellow | .grey modifier classes per the trend rules in
Phase 3.
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "KPI Scorecards" not "Phase 2 — KPI Scorecards", "Narrative" not "Phase 3 — Narrative", "Watch Items" not "Phase 5 — Watch Items").
Write to /tmp/aa_executive_briefing_<YYYY-MM-DD_HHMMSS>.html and open:
open /tmp/aa_executive_briefing_<YYYY-MM-DD_HHMMSS>.html
Tone and Style Guidelines
| Audience | Tone | Metrics | Length |
|---|---|---|---|
| C-suite | High-level, business outcomes, 1-2 sentences per metric | 3–5 max | 1 page |
| VP/Director | Operational detail, channel context, trend narrative | 5–7 | 1.5 pages |
| Marketing leadership | Campaign and channel depth, attribution, segment | 5–8 | 2 pages |
Always:
- Lead with the positive, then address concerns.
- Express deltas as business impact, not just percentages ("revenue grew $42K, up 14%" not just "+14%").
- For metrics that went down, include a possible explanation or next step.
Guardrails
- Do not present raw API output — always narrate the numbers.
- If a metric change is within ±3%, describe as "roughly flat" not a directional story.
- Always identify the comparison period explicitly in the briefing header.
- If context from
REPORT_SUITE_CONTEXT_GUIDEidentifies the company name or industry, use it in the narrative for a more personalized output.
Example Interaction
"Write an exec summary of last week's performance for our leadership team."
- Confirm report suite; load context guide.
- Identify period: last 7 days vs. prior 7 days. Audience: VP level.
- Confirm metrics: revenue, visits, orders, conversion rate, bounce rate.
- Run 2 reports (all 5 metrics batched in one call per period).
- Run channel breakdown for revenue.
- Compose narrative: "Revenue grew 9% WoW to $186K, led by Paid Search which contributed 58% of revenue. Visits grew 18%, but mobile bounce rate increased 4pp, signaling a checkout experience issue worth investigating."
- Generate HTML briefing and open.
- Deliver the narrative as inline text for immediate use.
KPI Pulse (Adobe Analytics)
Produce a compact, digestible KPI digest showing how key metrics changed over
a chosen period, which items drove the change, and what stood out. Batches all
KPIs into two runReport calls (current period + comparison period) and
assembles results into an HTML performance card deck.
AA MCP Tools Used
findReportSuites— select working report suitesetSessionDefaults— set session context (reportSuiteId + globalCompanyId)describeAa(REPORT_SUITE_CONTEXT_GUIDE)— load org context, top metrics, calendar config, and timezonefindMetrics— discover and validate metric IDslistComponentUsage— identify top-used metrics if user hasn't specifiedrunReport— all KPIs batched in one call per period (current + comparison)searchDimensionItems— find top contributors for top-mover callouts
Phase 0 — Setup
- Confirm report suite with
findReportSuites/setSessionDefaults. - Call
describeAa(REPORT_SUITE_CONTEXT_GUIDE)to load organizational context: top metrics, calendar configuration, and timezone. Record the report suite's first-day-of-week asWEEK_START_DOWand the report suite timezone asTIMEZONE— you will use both when computing reporting periods in Phase 2. If the context guide returns noWEEK_START_DOW, default to Monday (ISO 8601).
findReportSuites(globalCompanyId: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")
Phase 1 — Select KPIs
1.1 If the user specified metrics
Resolve each to an AA metric ID:
findMetrics(searchTerm: "<metric name>")
Cap at 8 metrics for a focused pulse. If more are requested, ask the user to prioritize or offer to split into multiple reports.
1.2 If the user has not specified metrics
Use listComponentUsage to find the most-used metrics in the report suite:
listComponentUsage(componentType: "metric")
Select the top 5–7 by usage count. Confirm with the user:
"Based on usage, I'll track: Visits, Page Views, Revenue, Orders, Conversion Rate, Bounce Rate. Does this look right, or would you like to adjust?"
Phase 2 — Select Time Periods
Ask the user what period to report on, or infer from context:
| Request | Current Period | Comparison Period |
|---|---|---|
| "this week" | Last 7 days | Prior 7 days |
| "this month" | Month-to-date | Same period last month |
| "last month" | Last full calendar month | Same month prior year |
| "this quarter" | Quarter-to-date | Same period last quarter |
| "YTD" | Jan 1 to today | Same period prior year |
Confirm: "I'll compare [current period] vs [comparison period]. Is that right?"
Calendar rule (mandatory): the current period and the comparison period
MUST use the same WEEK_START_DOW from Phase 0. For weekly pulses, both
periods' startDate fall on the same day-of-week, both are exactly 7 days
long, and the comparison period ends immediately before the current period
starts. Never mix conventions (e.g., a Mon–Sun current with a Sun–Sat prior)
within the same pulse. For custom date ranges, compute the comparison
period as the equal-length window ending immediately before the current
period starts.
Sanity check before calling runReport: confirm current.startDate and
comparison.startDate are the same day-of-week and that
current.startDate - comparison.endDate == 1 day. If not, recompute.
Edge case: If today is within the first 3 days of a period, note that the current-period data may be incomplete and the comparison may look skewed.
Phase 3 — Fetch KPI Data
Batch all selected metrics into a single call per period:
runReport(
metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
dimensionId: "variables/daterangeday",
startDate: "<current period start>T00:00",
endDate: "<current period end>T23:59"
)
runReport(
metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
dimensionId: "variables/daterangeday",
startDate: "<comparison period start>T00:00",
endDate: "<comparison period end>T23:59"
)
Note:
metricIdsaccepts comma-separated IDs — pass all KPIs at once.startDate/endDate(notdateRange); nogranularityparameter. Usevariables/daterangedayfor day-by-day breakdown.summaryData.totals[0],totals[1], etc. correspond to each metric in order. Unauthorized metrics surface incolumnErrors; the rest of the call still succeeds.
2 calls total regardless of metric count.
From each pair, compute:
- Current value (total over period)
- Prior value (total over comparison period)
- Absolute delta: current - prior
- Percent change: (delta / prior) × 100
- Trend: ↑ if positive, ↓ if negative, → if within ±2%
Phase 4 — Top Mover Context
For the 1–2 metrics with the largest percent changes (positive or negative), run a dimension breakdown to find the top contributor:
runReport(
metricIds: "<metricId>",
dimensionId: "variables/marketingchannel",
startDate: "<current period start>T00:00",
endDate: "<current period end>T23:59",
limit: 5
)
Repeat for a second dimension if relevant (e.g., pages for a traffic spike, products for a revenue change).
Use results to write a 1–2 sentence driver narrative:
"Visits rose 18% WoW, driven primarily by Organic Search (+34%) which offset a decline in Direct traffic (-12%)."
Phase 5 — Generate HTML Report
Build the KPI pulse HTML report inline and write to
/tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html.
Rendering rules — apply consistently across runs
Two runs of this skill on the same report suite + period must render identically (modulo the generation timestamp). The rules below pin the formatting choices that the AI would otherwise drift on.
Number formatting
- KPI values (the big number in each tile) — use full digits with
thousands separators (
8,160,77,584,1,250,000). Do NOT use SI suffixes likeKorM, even for large values. Executives want exact numbers, not abbreviations. - Percent change (in pills and narrative bullets) — always one decimal
place, rounded half-away-from-zero. For example,
−23.55%displays as−23.6%, never−23.5%. Compute on full-precision values; round only at display time. - Percentage-point change (for already-percentage metrics like Conversion
Rate or Bounce Rate) — same rounding, suffix
pp. Example:+0.40 pp. - Currency —
$prefix with thousands separators and no decimals for values ≥ $100 ($1,240,000); cents only when value < $100 ($45.20).
Null / missing data handling
A KPI tile must reflect what the report suite actually returned. The AI must not silently substitute a different metric or hide a tile to make the report look cleaner.
- Both periods return 0 or NULL for a KPI being rendered: render the tile
with
kpi-value=Data unavailable, pill classflat, pill text⚠ N/A, andpriortext =Both periods returned no data — validate instrumentation. The tile stays in the grid; do not omit it. - One period returns valid data, the other 0 / NULL: render the tile with
the valid value as
kpi-value, pill classflat, pill text⚠ N/A, andpriortext =Prior {period_noun}: no data. - Never substitute a derived metric (e.g., adding "Conversion Rate" because Revenue came back $0). The visible KPI set MUST match the metrics selected for this run.
HTML template
Read template.html and use it verbatim. Do not improvise the
HTML structure or CSS — only fill in the {PLACEHOLDER} tokens ({ORG_NAME},
{PERIOD_LABEL}, {COMPARISON_LABEL}, {REPORT_SUITE}, {GENERATED_DATE},
{METRIC_NAME}, {FORMATTED_VALUE_A}, {FORMATTED_VALUE_B}, {PCT_CHANGE},
{VALUE_A}, {VALUE_B}, {DELTA}, {ARROW}) and repeat the KPI tile / detail
row / mover row blocks once per data item. Preserve the .up | .down | .flat
and .green | .red | .yellow | .grey modifier classes per the trend rules in
Phase 3.
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "KPI Scorecards" not "Phase 2 — KPI Scorecards", "Top Movers" not "Phase 4 — Top Movers").
Write the completed HTML to /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html, then open:
open /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html
KPI Card Coloring Rules
- Delta badge green if change >= +2%
- Delta badge red if change <= -2%
- Delta badge grey if between -2% and +2% (flat)
- Border-top on card: green for positive movement, red for negative, grey for flat
Inline Summary (Always Deliver)
In addition to the HTML report, always provide a brief inline text summary:
KPI Pulse — [Period] vs [Comparison]
Report Suite: [Name]
Metric Current Change
───────────────── ─────── ──────
Visits 124,500 ▲ 18%
Revenue $42,800 ▲ 9%
Conversion Rate 2.4% ▼ 0.3pp
Page Views 398,200 ▲ 11%
Bounce Rate 48.2% ▼ 1.8pp
Key driver: Visits growth led by Paid Search (+34%).
Revenue up on strong Mobile performance (+22%).
Guardrails
- Always confirm the time period with the user before fetching data — wrong periods are the most common source of confusion.
- Flag partial periods explicitly (e.g., "This month has only 5 days of data").
- For percentage metrics (conversion rate, bounce rate), report deltas as percentage points (pp), not percent change.
- Cap at 8 metrics for reasonable call volume. Offer a second pulse for additional metrics if needed.
Example Interaction
"Give me a KPI update for last week."
- Confirm report suite with
findReportSuitesandsetSessionDefaults. - Load context with
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE"). - Identify top 6 metrics from
listComponentUsage(componentType: "metric")or user input. - Confirm: last 7 days vs prior 7 days.
- Run 12
runReportcalls (2 per metric) — usemetricIds,startDate,endDate, anddimensionId: "variables/daterangeday". SumsummaryData.totals[0]for each period total. - Run dimension breakdown for 2 biggest movers (use
dimensionId: "variables/marketingchannel"). - Generate HTML report, open it, deliver inline summary.
- Narrative: "Visits were up 18% WoW driven by paid search. Revenue grew 9% with mobile leading. Bounce rate improved 1.8pp."
Segment Performance Comparator (Adobe Analytics)
Compare the performance of two or more audience segments across key metrics side by side to understand how different visitor groups behave. Uses direct segment-vs-segment comparison to determine a winner, loser, and spread for each metric, with a separate context panel showing segment sizing.
AA Call Budget: AA's
runReportaccepts a singlesegmentIdper call. For N segments × M metrics the comparison requires N×M calls, plus 1 baseline call for the segment-size context panel. For 3 segments × 5 metrics = 16 calls. Limit to 4 segments and 6 metrics for practical performance. Always confirm the segment/metric list with the user before starting.
AA MCP Tools Used
findReportSuites— select report suitesetSessionDefaults— set session context (reportSuiteId + globalCompanyId)findSegments— discover and select comparison segmentsfindMetrics— resolve metric IDsrunReport— one call per segment per metric, plus one unsegmented call for sizing context
Phase 0 — Setup
- Confirm report suite with
findReportSuites/setSessionDefaults.
findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
Phase 1 — Select Segments
Ask the user which segments to compare. If not specified, prompt:
"Which visitor audiences would you like to compare? For example: Mobile vs. Desktop, New vs. Returning, Paid Search vs. Organic, or specific named segments from your library."
Search for and confirm each segment:
findSegments(page: 0, limit: 50)
# Filter locally by name. Built-in IDs: "Paid_Search", "Purchasers", "Return_Visits"
Note:
findSegmentsdoes not accept asearchTermparameter. Retrieve all segments and filter by name locally. Built-in template segments have short IDs like "Paid_Search" that can be passed directly assegmentIdsinrunReport.
If the user requests a segment that doesn't exist by name, offer to build it first using the aa-segment-builder skill, or suggest the closest existing segment from search results.
Limit: 4 segments maximum per comparison. Advise this limit upfront.
Phase 2 — Select Metrics
Ask the user which metrics to compare. Suggest a balanced mix:
- Volume:
metrics/visits - Engagement:
metrics/pageviews,metrics/bouncerate,metrics/pagespervisit - Conversion:
metrics/orders, conversion rate calculated metric - Revenue:
metrics/revenue
Call findMetrics to resolve each metric ID:
findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter locally by name. Key IDs: metrics/visits, metrics/revenue, metrics/orders, metrics/bouncerate
Limit: 6 metrics maximum. Confirm the final list with the user:
"I'll compare these 3 segments across 5 metrics. This requires 16 report calls (3 segments × 5 metrics + 1 sizing call). OK to proceed?"
Phase 3 — Select Date Range
Ask for or confirm the analysis period:
- Last 7 days (good for quick comparison)
- Last 30 days (recommended default)
- Last 90 days (for seasonal smoothing)
- Custom range
Phase 4 — Run Comparison Reports
4.1 Segment sizing (context only)
Run a single unsegmented call for metrics/visits to get the total
population size, then one call per segment for metrics/visits to
compute each segment's share of total. These sizing values populate the
context panel — they are not used in the comparison matrix.
runReport(
dimensionId: "variables/page",
metricIds: "metrics/visits",
startDate: "<start>",
endDate: "<end>",
limit: 1
)
# allVisitorVisits = summaryData.totals[0]
runReport(
dimensionId: "variables/page",
metricIds: "metrics/visits",
segmentIds: "<segmentId>",
startDate: "<start>",
endDate: "<end>",
limit: 1
)
# segmentVisits = summaryData.totals[0]; shareOfTotal = segmentVisits / allVisitorVisits × 100
Reuse these results if
metrics/visitsis already a comparison metric.
4.2 Per segment per metric
For each segment × metric combination:
runReport(
dimensionId: "variables/page",
metricIds: "<metricId>", # note: "metricIds" not "metricId"
segmentIds: "<segmentId>", # note: "segmentIds" not "segmentId"
startDate: "<start>",
endDate: "<end>",
limit: 1
)
# Total = summaryData.totals[0]
Read totals from
summaryData.totals[0](notrows[]).dimensionIdis required — use any dimension withlimit: 1for aggregate totals. Segment IDs are the rawidfield fromfindSegments.
Track progress: "Fetching Segment 2 of 3, metric 3 of 5..."
Phase 5 — Build the Comparison Matrix
The matrix compares segments directly to each other — no baseline column.
For each metric row, compute:
| Computed Value | Formula |
|---|---|
| Segment value | Raw from runReport |
| Winner | Segment with the best value for this metric |
| Loser | Segment with the worst value for this metric |
| Spread | (max − min) / max × 100 |
| Significant? | true if spread > 10% |
For metrics where lower is better (bounce rate, cost per acquisition), invert the winner/loser logic — the segment with the lowest value wins. Mark these metrics clearly in the report.
5.1 Segment profile summary
For each segment, compute an overall performance profile:
- Wins: count of metrics where this segment ranks #1
- Losses: count of metrics where this segment ranks last
- Biggest edge: metric where this segment outperforms others by the widest spread
- Visits share: percentage of total visits from the context panel
Phase 6 — Generate HTML Comparison Report
Build the comparison report inline and write to
/tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html.
HTML template
Read template.html and use it verbatim. Do not improvise the
HTML structure or CSS — only fill in the {PLACEHOLDER} tokens ({ORG_NAME},
{DATE_RANGE}, {REPORT_SUITE}, {GENERATED_DATE}, {SEGMENT_NAMES_SUMMARY},
{SEGMENT_NAME}, {COLOR}, {VISITOR_COUNT}, {NUM_SEGMENTS}, {NUM_METRICS},
{NUM_SIGNIFICANT}, {OVERALL_WINNER}, {METRIC_NAME}, {VALUE},
{WINNER_SEGMENT}, {SPREAD}, {INSIGHT_TEXT}) and repeat segment chips,
matrix rows, and insight boxes once per data item. Use the cell-winner /
cell-loser classes per Phase 5 winner/loser rules.
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "Segment Comparison" not "Phase 2 — Segment Comparison", "Metric Details" not "Phase 3 — Metric Details").
Write to /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html and open:
open /tmp/aa_segment_comparator_report_<YYYY-MM-DD_HHMMSS>.html
Inline Summary (Always Deliver)
Always follow the HTML report with a text summary:
Segment Comparison — [Date Range] | Report Suite: [Name]
Segment Context: Mobile 48,200 visits (38.7%) Desktop 72,400 (58.2%)
Mobile Desktop Winner Spread
──────────────── ─────── ──────── ───────── ──────
Visits 48,200 72,400 Desktop 33%
Bounce Rate 61.4% 40.1% ✓ Desktop 35% ✦
Conversion Rate 1.2% 3.1% ✓ Desktop 61% ✦
Revenue $9,400 $31,200 Desktop 70% ✦
✦ = spread > 10% ✓ = winner
Key findings:
- Desktop converts 2.6× better (3.1% vs 1.2%). Prioritize mobile checkout.
- Paid Search (not shown) has highest CVR at 4.8% — most efficient channel.
Guardrails
- Confirm segments and metrics with the user before starting — the call count is N×M and can grow quickly.
- For bounce rate and other "lower is better" metrics, invert the winner logic — the segment with the lowest value wins. Label these metrics clearly in the report (e.g., "↓ lower is better").
- If a segment returns very few visits (< 1,000), note that results may not be statistically reliable.
- Do not show baseline delta percentages (segment vs. All Visitors) in the comparison matrix. Segments are subsets of the total population, so count-metric deltas are always negative and misleading. Use the context panel for segment sizing instead.
Example Interaction
"Compare our mobile and desktop visitors on conversion metrics."
- Confirm report suite.
- Find segments: "Mobile Devices" and "Desktop" (or offer to create them).
- Confirm metrics: visits, bounce rate, orders, conversion rate, revenue.
- Date range: last 30 days.
- Preview: "2 segments × 5 metrics + 1 sizing call = 11 reports. Proceed?"
- Run all reports; announce progress.
- Context: Mobile = 48.2k visits (38.7%), Desktop = 72.4k visits (58.2%).
- Matrix: Desktop wins 3 of 5 metrics. Conversion rate spread 61%.
- Generate HTML report and open.
- Insight: "Desktop is your primary conversion engine. Mobile drives volume (39% of visits) but converts at 1.2% vs. Desktop's 3.1% — a 61% spread. Prioritize mobile checkout optimization for the biggest conversion lift opportunity."
Top Movers Watchlist (Adobe Analytics)
Identify which dimension items had the biggest increases and decreases for a key metric between two time periods. Surface the top gainers and losers across pages, channels, campaigns, products, or any other breakout dimension.
AA MCP Tools Used
findReportSuites— select report suitesetSessionDefaults— set session context (reportSuiteId + globalCompanyId)describeAa(REPORT_SUITE_CONTEXT_GUIDE)— load calendar/timezone contextfindMetrics— resolve the key metric IDfindDimensions— discover available breakdown dimensionsrunReport— period A and period B for each dimensionsearchDimensionItems— validate specific items if needed
Phase 0 — Setup
-
Confirm report suite with
findReportSuites/setSessionDefaults. -
Call
describeAa(REPORT_SUITE_CONTEXT_GUIDE)to load report suite context. Record:WEEK_START_DOW— first-day-of-week from the context guide. If the context guide returns no value, use Monday (ISO 8601) as the explicit deterministic default. This is not a fallback that drifts between runs: every run on the same report suite resolves to the sameWEEK_START_DOW, either from the context guide or from the fixed Monday default.TIMEZONE— report suite timezone.WEEK_START_DOW_SOURCE—"context guide"if the value came fromdescribeAa,"default"if the context guide was silent and Monday was used. Surface this in the artifact footer so the source is auditable.
You will use these values in Phase 1 when defining Period A and Period B.
findReportSuites(globalCompanyId: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")
Phase 1 — Confirm Parameters
Ask the user:
-
Metric — "Which metric should I rank movers by? (visits, revenue, conversions, page views, etc.)" If not specified, default to
metrics/visits. -
Dimension — "Which dimension should I break down?
- Pages
- Marketing Channel
- Campaigns
- Products
- Traffic Sources
- Geographic Regions
- Entry Pages" If not specified, offer the above list.
-
Time periods — "What two periods should I compare?" Common defaults:
- This week vs. last week
- This month vs. last month
- Last 7 days vs. prior 7 days
- Last 30 days vs. prior 30 days
Calendar rule (mandatory): Period A and Period B MUST use the same
WEEK_START_DOWfrom Phase 0 — both periods'startDatefall on the same day-of-week, both are exactly equal length, and Period B ends immediately before Period A starts. Never mix conventions (e.g., a Mon–Sun Period A with a Sun–Sat Period B) within the same run. For custom date ranges, compute Period B as the equal-length window ending immediately before Period A starts.Sanity check before calling
runReport: confirmperiodA.startDateandperiodB.startDateare the same day-of-week and thatperiodA.startDate - periodB.endDate == 1 day. If not, recompute. -
Item limit — how many top gainers and losers to show (default: 10 each).
-
Materiality threshold — minimum absolute value in Period A or B to be included (filters out noise from low-volume items). Default: exclude items with fewer than 100 visits (or equivalent) in both periods.
Confirm: "I'll show the top 10 gainers and losers for [metric] broken down by [dimension], comparing [Period A] vs [Period B]."
Phase 2 — Resolve Components
findMetrics(expansions: "componentType")
findDimensions(page: 1, limit: 100)
Note:
findMetricsrequires theexpansionsparameter (use"componentType"or"categories").findDimensionsrequirespageandlimit.
Record id for the metric and dimension.
Phase 3 — Run Period Reports
Run the metric for the selected dimension in both periods:
runReport(
metricIds: "<metricId>",
dimensionId: "<dimensionId>",
startDate: "<period A start>T00:00",
endDate: "<period A end>T23:59",
limit: 200
)
runReport(
metricIds: "<metricId>",
dimensionId: "<dimensionId>",
startDate: "<period B start>T00:00",
endDate: "<period B end>T23:59",
limit: 200
)
Note:
runReportusesmetricIds(notmetricId) andstartDate/endDatein ISO 8601 format (YYYY-MM-DDTHH:mm), not adateRangeparameter.
Use limit: 200 to capture enough items for a meaningful mover analysis.
Phase 4 — Compute Deltas and Rank
For each dimension item present in either period:
- Period A value (or 0 if not in results)
- Period B value (or 0 if not in results)
- Absolute delta: Period A - Period B
- Percent change: delta / Period B × 100 (or "+100% new" if Period B = 0)
- Apply materiality filter: exclude items where max(Period A, Period B) < materiality threshold
Sort by absolute delta descending for gainers (positive delta). Sort by absolute delta ascending for losers (negative delta).
Take top N from each list.
Special cases
- New items (present in Period A only): flag as "New — no prior period data." Include if materiality threshold met.
- Disappeared items (present in Period B only, 0 in Period A): flag as "Dropped — no current period data."
- Near-zero items: items with <1% of total metric value — consider excluding from the watchlist unless they show very large percent changes.
Phase 5 — Optional Multi-Dimension Watchlist
If the user wants movers across multiple dimensions (e.g., both pages AND
channels), repeat Phase 3–4 for each additional dimension. Each additional
dimension adds 2 more runReport calls.
runReport(metricIds: "<metricId>", dimensionId: "variables/marketingchannel",
startDate: "<A>T00:00", endDate: "<A>T23:59", ...)
runReport(metricIds: "<metricId>", dimensionId: "variables/page",
startDate: "<A>T00:00", endDate: "<A>T23:59", ...)
Group results into separate tables by dimension in the HTML report.
Phase 6 — Generate HTML Report
Build the movers report inline and write to
/tmp/aa_top_movers_report_<YYYY-MM-DD_HHMMSS>.html.
Rendering rules — apply consistently across runs
Two runs of this skill on the same report suite + metric/dimension + period must render identically (modulo the generation timestamp). The rules below pin the formatting choices that the AI would otherwise drift on.
Number formatting
- KPI values (the big number in each summary tile, and per-row mover
values) — use full digits with thousands separators (
8,160,77,584,1,250,000). Do NOT use SI suffixes likeKorM, even for large values. Stakeholders want exact numbers, not abbreviations. - Percent change (in pills and narrative bullets) — always one decimal
place, rounded half-away-from-zero. For example,
−23.55%displays as−23.6%, never−23.5%. Compute on full-precision values; round only at display time. - Percentage-point change (for already-percentage metrics like Conversion
Rate or Bounce Rate) — same rounding, suffix
pp. Example:+0.40 pp. - Currency —
$prefix with thousands separators and no decimals for values ≥ $100 ($1,240,000); cents only when value < $100 ($45.20).
Null / missing data handling
A KPI tile or mover row must reflect what the report suite actually returned. The AI must not silently substitute a different metric or hide a tile to make the report look cleaner.
- Both periods return 0 or NULL for the tracked metric in a summary tile:
render the tile with
kpi-value=Data unavailable, pill classflat, pill text⚠ N/A, andpriortext =Both periods returned no data — validate instrumentation. The tile stays in the grid; do not omit it. - One period returns valid data, the other 0 / NULL: render the tile with
the valid value as
kpi-value, pill classflat, pill text⚠ N/A, andpriortext =Prior {period_noun}: no data. - Never substitute a different metric (e.g., switching from Revenue to Orders because Revenue came back $0). The metric being analyzed MUST be the metric rendered.
HTML template
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Top Movers — {ORG_NAME} — {METRIC_NAME}</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
:root {
--bg: #f5f4f1;
--surface: #ffffff;
--ink: #1a1a1a;
--ink-muted: #6b6b6b;
--border: #e5e2dc;
--header-bg: #0e0e10;
--header-warm: #3a1010;
--accent-red: #c8312f;
--accent-red-bright: #ff6b68;
--accent-red-soft: #fdecea;
--accent-green: #1f7a4d;
--accent-yellow: #d4a017;
}
body { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
background: var(--bg); color: var(--ink); line-height: 1.5;
-webkit-font-smoothing: antialiased; }
/* === Header === */
header { background: linear-gradient(120deg, var(--header-bg) 0%, #1a0d0d 55%, var(--header-warm) 100%);
color: #fff; padding: 56px 56px 44px; position: relative; overflow: hidden; }
header::after { content: ""; position: absolute; right: -140px; top: -140px;
width: 460px; height: 460px;
background: radial-gradient(circle, rgba(200,49,47,.35) 0%, transparent 70%);
pointer-events: none; }
.header-inner { max-width: 1080px; margin: 0 auto; position: relative; z-index: 1; }
.eyebrow { display: inline-flex; align-items: center; gap: 8px;
padding: 6px 14px; border: 1px solid rgba(255,107,104,.55);
border-radius: 999px; color: var(--accent-red-bright);
font-size: 11px; font-weight: 600; letter-spacing: 1.2px;
text-transform: uppercase; margin-bottom: 24px;
background: rgba(200,49,47,.10); }
.eyebrow::before { content: ""; width: 6px; height: 6px;
background: var(--accent-red-bright); border-radius: 50%; }
header h1 { font-family: "Playfair Display", Georgia, serif;
font-size: 56px; font-weight: 700; letter-spacing: -1.5px;
line-height: 1.05; margin-bottom: 14px; color: #fff; }
header .lede { font-size: 16px; max-width: 600px;
color: rgba(255,255,255,.80); margin-bottom: 24px;
line-height: 1.55; }
header .meta { display: flex; flex-wrap: wrap; gap: 22px;
font-size: 13px; color: rgba(255,255,255,.60); }
header .meta span { display: inline-flex; align-items: center; gap: 6px; }
header .meta .icon { opacity: .8; }
/* === Tabs === */
nav { background: var(--surface); border-bottom: 1px solid var(--border);
padding: 0 56px; display: flex; gap: 28px;
position: sticky; top: 0; z-index: 50; }
nav a { display: block; padding: 16px 0; font-size: 14px;
color: var(--ink); text-decoration: none;
border-bottom: 2px solid transparent;
transition: border-color .15s ease; }
nav a:hover { border-bottom-color: var(--accent-red); }
/* === Container === */
.container { max-width: 1080px; margin: 0 auto; padding: 36px 56px 60px; }
/* === Period strip === */
.period-bar { background: var(--surface); border-radius: 8px;
padding: 14px 22px; margin-bottom: 28px;
font-size: 13px; color: var(--ink-muted);
box-shadow: 0 1px 3px rgba(0,0,0,.04);
border-left: 3px solid var(--accent-red); }
.period-bar strong { color: var(--ink); font-weight: 600; }
/* === Dimension section === */
.dim-section { margin-top: 32px; }
.dim-section > h2 { font-family: "Playfair Display", Georgia, serif;
font-size: 22px; font-weight: 700; color: var(--ink);
margin-bottom: 16px; padding-bottom: 10px;
border-bottom: 1px solid var(--border); }
/* === Gainers / Losers dual panels === */
.movers-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 22px;
margin-bottom: 32px; }
.movers-panel { background: var(--surface); border-radius: 8px;
box-shadow: 0 1px 3px rgba(0,0,0,.05); overflow: hidden; }
.movers-panel-header { padding: 18px 24px; border-bottom: 1px solid var(--border); }
.movers-panel-header.gainers { border-top: 3px solid var(--accent-green); }
.movers-panel-header.losers { border-top: 3px solid var(--accent-red); }
.movers-panel-header h2 { font-family: "Playfair Display", Georgia, serif;
font-size: 17px; font-weight: 700; }
.movers-panel-header.gainers h2 { color: var(--accent-green); }
.movers-panel-header.losers h2 { color: var(--accent-red); }
/* === Tables === */
table { width: 100%; border-collapse: collapse; font-size: 13px; }
thead th { background: #faf8f4; padding: 10px 18px;
text-align: left; font-weight: 600;
text-transform: uppercase; letter-spacing: .6px;
font-size: 11px; color: var(--ink-muted);
border-bottom: 1px solid var(--border); }
tbody td { padding: 10px 18px; border-bottom: 1px solid #f4f1eb; }
tbody tr:last-child td { border-bottom: none; }
.delta-pos { color: var(--accent-green); font-weight: 700; }
.delta-neg { color: var(--accent-red); font-weight: 700; }
/* === Rank badges (circular) === */
.rank-badge { display: inline-flex; align-items: center; justify-content: center;
width: 24px; height: 24px;
border-radius: 50%;
background: var(--accent-red); color: #fff;
font-size: 11px; font-weight: 700;
margin-right: 8px; vertical-align: middle; }
.rank-badge.gain { background: var(--accent-green); }
.back-top { position: fixed; bottom: 24px; right: 24px; background: var(--accent-red);
color: #fff; width: 44px; height: 44px; border-radius: 50%; border: none;
font-size: 20px; cursor: pointer;
box-shadow: 0 4px 12px rgba(200,49,47,.35); }
footer { text-align: center; padding: 32px 24px;
font-size: 12px; color: var(--ink-muted); }
@media (max-width: 700px) { .movers-grid { grid-template-columns: 1fr; } }
/* === Print === */
@media print {
nav { display: none; position: static; }
header { padding: 36px 32px 28px; }
header h1 { font-size: 42px; }
.back-top { display: none; }
.movers-grid { page-break-inside: avoid; }
.movers-panel, .period-bar {
box-shadow: none; border: 1px solid var(--border);
}
}
</style>
</head>
<body>
<header>
<div class="header-inner">
<div class="eyebrow">Top Movers Watchlist</div>
<h1>{ORG_NAME} Top Movers</h1>
<p class="lede">Biggest gainers and decliners for {METRIC_NAME} between {PERIOD_A} and {PERIOD_B}.</p>
<div class="meta">
<span><span class="icon">📅</span> {PERIOD_A} vs {PERIOD_B}</span>
<span><span class="icon">📊</span> {REPORT_SUITE}</span>
<span><span class="icon">🕔</span> Prepared {GENERATED_DATE}</span>
</div>
</div>
</header>
<nav>
<a href="#summary">Summary</a>
<!-- one nav link per dimension -->
</nav>
<div class="container">
<div id="summary" class="period-bar">
<strong>Metric:</strong> {METRIC_NAME} |
<strong>Period A:</strong> {PERIOD_A} |
<strong>Period B:</strong> {PERIOD_B} |
<strong>Materiality:</strong> ≥{THRESHOLD} {METRIC_UNIT}
</div>
<!-- One .dim-section per dimension -->
<div id="dim-{DIM_ID}" class="dim-section">
<h2>{DIMENSION_NAME}</h2>
<div class="movers-grid">
<div class="movers-panel">
<div class="movers-panel-header gainers"><h2>▲ Top Gainers</h2></div>
<table>
<thead><tr>
<th>#</th><th>Item</th><th>Period A</th><th>Period B</th>
<th>Delta</th><th>% Change</th>
</tr></thead>
<tbody><!-- gainer rows: use <span class="rank-badge gain">N</span> --></tbody>
</table>
</div>
<div class="movers-panel">
<div class="movers-panel-header losers"><h2>▼ Top Losers</h2></div>
<table>
<thead><tr>
<th>#</th><th>Item</th><th>Period A</th><th>Period B</th>
<th>Delta</th><th>% Change</th>
</tr></thead>
<tbody><!-- loser rows: use <span class="rank-badge">N</span> --></tbody>
</table>
</div>
</div>
</div>
</div>
<button class="back-top" onclick="window.scrollTo({top:0,behavior:'smooth'})">
⇧
</button>
<footer>Top Movers Watchlist — {ORG_NAME} — Generated {GENERATED_DATE}</footer>
</body>
</html>
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only (e.g., "Top Movers" not "Phase 3 — Top Movers", "Dimension Breakdown" not "Phase 4 — Dimension Breakdown").
Write to /tmp/aa_top_movers_report_<YYYY-MM-DD_HHMMSS>.html and open:
open /tmp/aa_top_movers_report_<YYYY-MM-DD_HHMMSS>.html
Inline Summary (Always Deliver)
Always follow the HTML report with a brief text callout:
Top Movers: [Metric] — [Period A] vs [Period B]
GAINERS (by [Dimension])
1. [Item A] +12,400 visits (+34%)
2. [Item B] +8,200 visits (+21%)
3. [Item C] +5,100 visits (+18%)
LOSERS
1. [Item X] -9,800 visits (-41%)
2. [Item Y] -4,200 visits (-18%)
3. [Item Z] -2,900 visits (-12%)
Key takeaway: [1 sentence explanation of the story]
Guardrails
- Always apply a materiality threshold to suppress noise from items with negligible volume.
- Flag new items (no prior period) and disappeared items (no current period) explicitly — they often tell a significant story.
- For percent-change ranking, use absolute delta (not percent) as primary sort to avoid surfacing low-volume items with misleading large percentages.
- Cap dimension list at 6 for call efficiency. Offer to run additional dimensions on request.
Example Interaction
"What pages were up and down the most last week?"
- Confirm report suite.
- Confirm metric: page views. Dimension: page name. Period: last 7 days vs prior 7 days. Limit: top 10 each.
- Run 2 reports for page × visits.
- Compute deltas, apply materiality (min 500 page views in either period).
- Generate HTML report and deliver inline summary.
- "Top gainer: /products/new-feature with +18,200 page views (+312%). Top loser: /promo/expired-campaign with -9,400 page views (-88%)."
MCP servers 1
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/adobe-analytics
- Author
- Adobe
- Category
- Analytics
- License
- Apache-2.0
- Keywords
- adobe, adobe-analytics, analytics, mcp, reporting
More from adobe/skills
All 19- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0
- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0