adobe avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 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 suite
  • setSessionDefaults — set session context (reportSuiteId + globalCompanyId)
  • findDimensions — discover page/event dimensions for step definition
  • findMetrics — find visits or orders as the counting metric
  • searchDimensionItems — validate page names or event values
  • findSegments — find existing step segments if available
  • upsertSegment — create visit-level step segments if not found
  • runReport — run visits count for each step segment

Phase 0 — Setup

  1. Confirm report suite with findReportSuites / setSessionDefaults.
  2. 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:

  1. Product page viewed
  2. Add to cart
  3. Checkout started
  4. Payment info entered
  5. 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: searchDimensionItems uses searchOr or searchAnd for filtering — not searchTerm. 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 (not metricId) and segmentIds (not segmentId). Use startDate/endDate (ISO 8601) rather than a dateRange object. Always read totals from summaryData.totals[0], not from rows.


Phase 5 — Compute Funnel Metrics

For each step, compute:

MetricFormula
Step visitsRaw count from runReport
Step conversion rateStep visits / Total visits × 100
Step-to-step rateStep N visits / Step N-1 visits × 100
Step-to-step drop-offStep N-1 visits - Step N visits
Drop-off rate100 - 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 &mdash; {ORG_NAME} &mdash; {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">&#128197;</span> {DATE_RANGE}</span>
      <span><span class="icon">&#128202;</span> {REPORT_SUITE}</span>
      <span><span class="icon">&#128340;</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">&#9662;</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">&#9662;</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">&#9662;</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'})">
  &#8679;
</button>
<footer>Funnel Health &mdash; {ORG_NAME} &mdash; 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 findSegments first.
  • 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."

  1. Confirm report suite and date range (last 30 days).
  2. Define 5 steps: Product View → Add to Cart → Checkout → Payment → Purchase.
  3. Validate page names with searchDimensionItems.
  4. Find existing step segments or create new ones (with user approval).
  5. Run 6 reports (5 steps + total).
  6. Compute: 100% → 42% (add to cart) → 28% (checkout) → 19% (payment) → 11% (purchase). Overall conversion: 11%.
  7. Worst step: Add-to-Cart to Checkout (33% drop-off rate).
  8. Drill in: Mobile users have only 18% checkout rate vs. 31% on Desktop.
  9. Generate and open HTML report.
  10. 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), not metricId; dates as YYYY-MM-DDTHH:mm:ss
  • findMetrics → expansions is a required parameter (use "componentType")
  • describeAa → parameter is guideType, not guide; REPORT_SUITE_CONTEXT_GUIDE may return empty for some report suites — skip gracefully and proceed
  • metrics/uniquevisitors is often unauthorized — use metrics/visits instead
  • setSessionDefaults is the correct tool name (not setDefaultReportSuite)

AA MCP Tools Used

  • findReportSuites — select report suite
  • setSessionDefaults — 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 it
  • findMetrics(expansions: "componentType") — resolve metric IDs (expansions parameter is required)
  • listComponentUsage(componentType: "metric") — identify most-used metrics if not specified by the user
  • runReport — current and comparison period with all metrics batched in one call (metricIds accepts comma-separated IDs); dimension breakdowns for top movers
  • searchDimensionItems — validate dimension values for driver callouts

Phase 0 — Setup

  1. Confirm report suite.
  2. 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:

  1. 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 requestPERIOD_TYPECurrent periodComparison period
"last week"weeklyMost 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-date1st of current month → today1st of prior month → same day-of-month as today
"last month"monthlyPrior full calendar monthThe month before that
"this quarter" / "QTD"quarter-to-dateStart of current fiscal quarter → today; fiscal quarters derived from FISCAL_YEAR_START_MONTHSame days into the prior fiscal quarter
"last quarter" / "Q[N]"quarterlyPrior full fiscal quarterThe fiscal quarter before that
Custom date rangecustomUse as specifiedEqual-length window ending the day before current.startDate
Universal invariants (must hold for every period type)

Before calling runReport, verify all six:

  1. current.startDate < current.endDate
  2. comparison.startDate < comparison.endDate
  3. comparison.endDate < current.startDate (no overlap)
  4. The day after comparison.endDate equals current.startDate (contiguous)
  5. current and comparison have the same length in days
  6. The alignment rule for PERIOD_TYPE is satisfied:
    • weekly: both startDates fall on WEEK_START_DOW
    • monthly: both startDates fall on the 1st of a month
    • month-to-date: both startDates fall on the 1st; both endDates have the same day-of-month
    • quarterly: both startDates fall on the first day of a fiscal quarter
    • quarter-to-date: both startDates fall on a fiscal quarter start; both endDates are the same number of days into the quarter
    • custom: 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 requestPERIOD_TYPECurrentComparison
"last week"weeklyMay 17 (Sun) – May 23 (Sat)May 10 (Sun) – May 16 (Sat)
"this month" / "MTD"month-to-dateMay 1 – May 26Apr 1 – Apr 26
"last month"monthlyApr 1 – Apr 30Mar 1 – Mar 31
"this quarter" / "QTD"quarter-to-dateApr 1 – May 26Jan 1 – Feb 24
"last quarter"quarterlyJan 1 – Mar 31Oct 1 – Dec 31 (2025)
Custom: "May 15–22"customMay 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.

  1. 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).
  2. 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.

  3. Supporting metrics — "What other metrics should be included? (up to 5)"

  4. 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: findMetrics requires the expansions parameter (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. Prefer metrics/visits for 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:

  1. If the user named metrics explicitly, resolve each to ONE specific metric ID via findMetrics. On ambiguity, pick the metric with the highest usageCount from listComponentUsage and document the choice.
  2. Otherwise, take listComponentUsage(componentType: "metric") results, sort by usageCount descending with metric ID alphabetical as the tiebreak (stable secondary sort), and take the top 6 metric IDs.
  3. Use describeMetric to resolve to display names.
  4. 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/orders vs 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 runReport parameter is metricIds (plural), not metricId. 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. Use variables/daterangeday as dimensionId to get a day-by-day breakdown; totals for each metric are in summaryData.totals[0], totals[1], etc. in order. If a metric is unauthorized, it surfaces in columnErrors — 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

  1. 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."

  2. North-star metric — 2–3 sentences on the most important KPI: value, change, context, what drove it.

  3. Supporting highlights — 1 sentence per additional metric (positive first, then concerns).

  4. 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."

  5. Risk or watch item — 1–2 sentences on anything concerning: "Bounce rate on mobile increased 4pp, suggesting friction in the mobile experience worth investigating."

  6. 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 like K or M, 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 class flat, pill text ⚠ N/A, and prior text = 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 class flat, pill text ⚠ N/A, and prior text = 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.note above 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 of Weekly, Monthly, Quarterly, or Performance (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

AudienceToneMetricsLength
C-suiteHigh-level, business outcomes, 1-2 sentences per metric3–5 max1 page
VP/DirectorOperational detail, channel context, trend narrative5–71.5 pages
Marketing leadershipCampaign and channel depth, attribution, segment5–82 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_GUIDE identifies 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."

  1. Confirm report suite; load context guide.
  2. Identify period: last 7 days vs. prior 7 days. Audience: VP level.
  3. Confirm metrics: revenue, visits, orders, conversion rate, bounce rate.
  4. Run 2 reports (all 5 metrics batched in one call per period).
  5. Run channel breakdown for revenue.
  6. 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."
  7. Generate HTML briefing and open.
  8. 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 suite
  • setSessionDefaults — set session context (reportSuiteId + globalCompanyId)
  • describeAa(REPORT_SUITE_CONTEXT_GUIDE) — load org context, top metrics, calendar config, and timezone
  • findMetrics — discover and validate metric IDs
  • listComponentUsage — identify top-used metrics if user hasn't specified
  • runReport — all KPIs batched in one call per period (current + comparison)
  • searchDimensionItems — find top contributors for top-mover callouts

Phase 0 — Setup

  1. Confirm report suite with findReportSuites / setSessionDefaults.
  2. 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 as WEEK_START_DOW and the report suite timezone as TIMEZONE — you will use both when computing reporting periods in Phase 2. If the context guide returns no WEEK_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:

RequestCurrent PeriodComparison Period
"this week"Last 7 daysPrior 7 days
"this month"Month-to-dateSame period last month
"last month"Last full calendar monthSame month prior year
"this quarter"Quarter-to-dateSame period last quarter
"YTD"Jan 1 to todaySame 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: metricIds accepts comma-separated IDs — pass all KPIs at once. startDate/endDate (not dateRange); no granularity parameter. Use variables/daterangeday for day-by-day breakdown. summaryData.totals[0], totals[1], etc. correspond to each metric in order. Unauthorized metrics surface in columnErrors; 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 like K or M, 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 class flat, pill text ⚠ N/A, and prior text = 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 class flat, pill text ⚠ N/A, and prior text = 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."

  1. Confirm report suite with findReportSuites and setSessionDefaults.
  2. Load context with describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE").
  3. Identify top 6 metrics from listComponentUsage(componentType: "metric") or user input.
  4. Confirm: last 7 days vs prior 7 days.
  5. Run 12 runReport calls (2 per metric) — use metricIds, startDate, endDate, and dimensionId: "variables/daterangeday". Sum summaryData.totals[0] for each period total.
  6. Run dimension breakdown for 2 biggest movers (use dimensionId: "variables/marketingchannel").
  7. Generate HTML report, open it, deliver inline summary.
  8. 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 runReport accepts a single segmentId per 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 suite
  • setSessionDefaults — set session context (reportSuiteId + globalCompanyId)
  • findSegments — discover and select comparison segments
  • findMetrics — resolve metric IDs
  • runReport — one call per segment per metric, plus one unsegmented call for sizing context

Phase 0 — Setup

  1. 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: findSegments does not accept a searchTerm parameter. Retrieve all segments and filter by name locally. Built-in template segments have short IDs like "Paid_Search" that can be passed directly as segmentIds in runReport.

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/visits is 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] (not rows[]). dimensionId is required — use any dimension with limit: 1 for aggregate totals. Segment IDs are the raw id field from findSegments.

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 ValueFormula
Segment valueRaw from runReport
WinnerSegment with the best value for this metric
LoserSegment 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."

  1. Confirm report suite.
  2. Find segments: "Mobile Devices" and "Desktop" (or offer to create them).
  3. Confirm metrics: visits, bounce rate, orders, conversion rate, revenue.
  4. Date range: last 30 days.
  5. Preview: "2 segments × 5 metrics + 1 sizing call = 11 reports. Proceed?"
  6. Run all reports; announce progress.
  7. Context: Mobile = 48.2k visits (38.7%), Desktop = 72.4k visits (58.2%).
  8. Matrix: Desktop wins 3 of 5 metrics. Conversion rate spread 61%.
  9. Generate HTML report and open.
  10. 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 suite
  • setSessionDefaults — set session context (reportSuiteId + globalCompanyId)
  • describeAa(REPORT_SUITE_CONTEXT_GUIDE) — load calendar/timezone context
  • findMetrics — resolve the key metric ID
  • findDimensions — discover available breakdown dimensions
  • runReport — period A and period B for each dimension
  • searchDimensionItems — validate specific items if needed

Phase 0 — Setup

  1. Confirm report suite with findReportSuites / setSessionDefaults.

  2. 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 same WEEK_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 from describeAa, "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:

  1. Metric — "Which metric should I rank movers by? (visits, revenue, conversions, page views, etc.)" If not specified, default to metrics/visits.

  2. 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.
  3. 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_DOW from Phase 0 — both periods' startDate fall 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: confirm periodA.startDate and periodB.startDate are the same day-of-week and that periodA.startDate - periodB.endDate == 1 day. If not, recompute.

  4. Item limit — how many top gainers and losers to show (default: 10 each).

  5. 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: findMetrics requires the expansions parameter (use "componentType" or "categories"). findDimensions requires page and limit.

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: runReport uses metricIds (not metricId) and startDate/endDate in ISO 8601 format (YYYY-MM-DDTHH:mm), not a dateRange parameter.

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:

  1. Period A value (or 0 if not in results)
  2. Period B value (or 0 if not in results)
  3. Absolute delta: Period A - Period B
  4. Percent change: delta / Period B × 100 (or "+100% new" if Period B = 0)
  5. 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 like K or M, 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 class flat, pill text ⚠ N/A, and prior text = 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 class flat, pill text ⚠ N/A, and prior text = 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 &mdash; {ORG_NAME} &mdash; {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">&#128197;</span> {PERIOD_A} vs {PERIOD_B}</span>
      <span><span class="icon">&#128202;</span> {REPORT_SUITE}</span>
      <span><span class="icon">&#128340;</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} &nbsp;|&nbsp;
    <strong>Period A:</strong> {PERIOD_A} &nbsp;|&nbsp;
    <strong>Period B:</strong> {PERIOD_B} &nbsp;|&nbsp;
    <strong>Materiality:</strong> &ge;{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>&#9650; 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>&#9660; 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'})">
  &#8679;
</button>
<footer>Top Movers Watchlist &mdash; {ORG_NAME} &mdash; 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?"

  1. Confirm report suite.
  2. Confirm metric: page views. Dimension: page name. Period: last 7 days vs prior 7 days. Limit: top 10 each.
  3. Run 2 reports for page × visits.
  4. Compute deltas, apply materiality (min 500 page views in either period).
  5. Generate HTML report and deliver inline summary.
  6. "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