Customer Cohort Analysis

Purpose

Groups customers by the month of their first purchase and tracks how each cohort performs over time: how many customers repurchase, how many orders they place, and how much revenue each cohort generates in subsequent months. Cohort analysis is the gold standard for measuring retention and the health of a subscription or loyalty program. Read-only — no mutations.

Prerequisites

Parameters

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

Inputs: query: "created_at:>=''", first: 250, select id, createdAt, numberOfOrders, pagination cursor

Expected output: Customers acquired in the cohort window

Inputs: query: "created_at:>=''", first: 250, select customer { id }, createdAt, totalPriceSet, pagination cursor

Expected output: All orders to build per-customer purchase timeline

GraphQL Operations

# customers:query — validated against api_version 2025-01
query CohortCustomers($query: String!, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
        defaultEmailAddress {
          emailAddress
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# orders:query — validated against api_version 2025-01
query CohortOrders($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Customer Cohort Analysis             ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
CUSTOMER COHORT ANALYSIS
  Cohort months analyzed:  <n>
  Total customers tracked: <n>

  Cohort      Acquired  M+1 Repeat  M+2 Repeat  M+3 Repeat
  ──────────────────────────────────────────────────────────
  2026-01     <n>       <pct>%       <pct>%       <pct>%
  2026-02     <n>       <pct>%       <pct>%       <pct>%
  Output: cohort_analysis_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "customer-cohort-analysis",
  "store": "<domain>",
  "cohorts": [],
  "output_file": "cohort_analysis_<date>.csv"
}

Output Format

CSV file cohort_analysis_.csv with columns:

cohort_month, customers_acquired, repeat_purchasers, repeat_rate_pct, total_revenue, revenue_per_customer, month_offset

Error Handling

Best Practices