amplitude/builder-skills

Create Amplitude Chart

Create charts from natural language by discovering events, building chart definitions, and verifying results.

Planning First (Critical)

Before any tool calls, decompose the request:

1. Identify chart components:

• Chart type and metric (what's being measured)
• Time range (default: Last 30 Days if not specified)
• Primary event (the action being counted)
• Segment conditions (user filters/groups)
• Filters, groupings, breakdowns
• Funnel steps (if conversion analysis)

2. Plan event searches:

• ONE search per distinct event concept
• Never combine multiple concepts in one search
• Example: "purchase" and "signup" need separate searches

3. Plan parallel tool calls:

• Get context, search events, find cohorts can run together
• Wait for results before building definition

Event Discovery (Critical: Discovery First)

IMPORTANT: Cast a wide net before narrowing down

When the user's request is ambiguous or could map to multiple events:

1. Search BROADLY first to discover relevant options
2. Review relevant results - look for related events, custom events, meta events
3. Present options to user OR explain your selection rationale
4. Try not to assume a single event is the only answer without exploration

Search for events:

Amplitude:search with entity_types=['EVENT', 'CUSTOM_EVENT']

• Search ONE concept at a time
• Use broad search terms first (e.g., "AI" not just "AI chat")
• ✓ Good: "user completes purchase"
• ✗ Bad: "signup or purchase events"

Make informed decisions, then explain:

1. Search broadly to discover all options
2. Review results and identify the most comprehensive/accurate approach
3. Make your best judgment call (prefer aggregated custom events over single events)
4. Always explain: "I found X, Y, Z options. I chose [X] because [reason]. This includes/excludes [scope]."
5. User can correct if your assumption was wrong

Decision criteria:

• Prefer custom events that aggregate related activity (e.g., "[2026] Activation Metric [AI events only]")
• If no aggregated event exists, choose the primary interaction event
• Consider what "active user" typically means for that product area
• Default to broader scope unless user specifies narrow focus

Examples:

• ❌ BAD: User asks "weekly AI users" → immediately pick "ai-chat: send message" without exploring, no explanation
• ✅ GOOD: User asks "weekly AI users" → search "AI", find Ask AI, Agents, Visibility, custom aggregated event. Respond: "I found AI activity across Ask AI, Agents, and Visibility. I'm using the '[2026] Activation Metric [AI events only]' custom event which includes all AI product interactions. This gives you total AI users across all features. Let me know if you want to focus on a specific AI product instead."

Verify before use:

• Get existing charts using the event via search
• Check event has actual volume (not zero/stale)
• Look for custom events that aggregate related activity
• If zero results, search for alternatives

Get properties:

Amplitude:get_event_properties for exact property names/values

Find cohorts:

Amplitude:search with entity_types=['COHORT']
Amplitude:get_cohorts to get full definitions

Chart Type Selection

Chart Type	Use When
eventsSegmentation	Counting events/users over time, trends, comparisons, KPIs, distributions, property analytics
funnels	Multi-step conversion analysis with a known sequence, drop-off analysis, time between specific events, time-to-convert metrics
retention	User return behavior, cohort retention curves, churn analysis
dataTableV2	Tabular comparisons, rankings, multi-dimensional breakdowns
customerJourney	Path exploration, discovering unknown paths users take, comparing converted vs dropped-off paths
sessions	Session duration, session frequency, time spent per user, session length distributions

Quick Reference

eventsSegmentation - Most versatile. Use for:

• User counts (DAU, WAU, MAU) with uniques metric
• Event totals, averages, sums of properties
• Percentiles, distributions, formulas
• Time series with rolling windows

Aggregation Scope (eventsSegmentation):

• PROPSUM(A) / metric: "sums" = Global sum across ALL events
• metric: "frequency" = Distribution of per-user event counts (how many users did it 1x, 2x, 3x)
• For "distribution of property sum per user": Amplitude does not support this directly. Use metric: "frequency" for event count distributions, or use dataTableV2 grouped by user_id with PROPSUM, then export for external analysis.

funnels - Conversion analysis with predefined steps. Use for:

• Step-by-step conversion rates when you know the expected sequence
• Ordered or unordered sequences
• Time-to-convert (median time between events)
• Exclusion events, conversion windows
• Overlapping events: To find users who performed multiple events (in any order), use a funnel with "any order" and set the conversion window to match the chart date range
• Note: If you want to discover what paths users take, use customerJourney instead

retention - Return behavior. Use for:

• N-day or rolling retention curves
• Cohort analysis (new vs returning users)
• Start event → Return event patterns

dataTableV2 - Tabular data. Use for:

• Breakdowns by dimensions (country, platform, etc.)
• Multi-metric comparisons in table format

customerJourney - Path exploration and discovery. Use for:

• Understanding the actual paths users take (vs. expected paths in funnels)
• Analyzing paths starting with, ending with, or between two specific events
• Comparing converted vs dropped-off user paths side by side
• Discovering unexpected navigation patterns or friction points
• Exploring path frequency, similarity, or average time to complete
• Bridging the gap between ideal customer journeys and actual user behavior

sessions - Session-based engagement metrics. Use for:

• Session duration analysis (average length, time spent, distributions)
• Session frequency (average sessions per user, total sessions)
• Time spent per user over time
• Events performed within sessions (average events per session)
• Comparing session behavior across user segments

Special metrics:

• User counts: metric: "uniques"
• Event counts: metric: "totals"
• Property sums: metric: "sums" with property in group_by
• Rates/percentages: Use when comparing groups of different sizes

Meta events:

• _active: Any active event (DAU, MAU)
• _new: New users (first-time event)
• _any_revenue_event: Revenue events

Chart Definition Structure

Core parameters (all chart types):

{
  "name": "Descriptive Chart Title",
  "projectId": "12345",
  "definition": {
    "app": "12345",
    "type": "eventsSegmentation",
    "params": {
      "range": "Last 30 Days",
      "events": [{
        "event_type": "Purchase Completed",
        "filters": [],
        "group_by": []
      }],
      "metric": "uniques",
      "countGroup": "User",
      "interval": 1,
      "segments": [{"conditions": []}]
    }
  }
}

Key parameters:

• countGroup: "User" (unique users) or "Event" (event occurrences)
• interval: 1 (daily), 7 (weekly), 30 (monthly)
• segments: User filters/groups (empty array = all users)

Event filters (inline OR logic):

"filters": [{
  "group_type": "User",
  "subprop_key": "country",
  "subprop_op": "is",
  "subprop_type": "event",
  "subprop_value": ["United States", "Canada"]
}]

User segments (conditions AND logic):

"segments": [{
  "name": "Active Users",
  "conditions": [{
    "type": "property",
    "group_type": "User",
    "prop_type": "user",
    "prop": "plan",
    "op": "is",
    "values": ["Pro", "Enterprise"]
  }]
}]

Cohort segments: Search for cohort, get ID, then:

"segments": [{
  "name": "My Cohort",
  "conditions": [{
    "type": "cohort",
    "group_type": "User",
    "cohort_id": "abc123",
    "op": "is_in"
  }]
}]

Workflow: Create Chart

1. Get context:

Amplitude:get_context (for projectId)

2. Discover events (BROAD search first):

Amplitude:search for each distinct concept
- Use broad search terms initially
- Look for all related events, custom events, cohorts
- Review ALL results before selecting

3. Evaluate and decide:

• Review all discovered events and custom events
• Make informed decision (prefer aggregated events)
• Prepare clear explanation of what you found and your choice

4. Find similar charts (see examples):

Amplitude:search entity_types=['CHART'] query="similar concept"
Amplitude:get_charts to see definition structure

5. Get properties if needed:

Amplitude:get_event_properties

6. Build definition using discovered names

• Explain event selection rationale in response

7. Create chart:

Amplitude:query_dataset with full definition

8. Verify results - check data makes sense

9. Save chart:

Amplitude:save_chart_edits with editId from query_dataset

Error Handling

If query_dataset fails:

• Read error message carefully
• Common issues: incorrect event names, invalid filters, wrong parameter types
• Fix definition and retry
• Verify events exist via search first

If zero results:

• Check filters aren't too restrictive
• Verify event has data (search for charts using it)
• Try broader time range
• Check segment conditions

Best Practices

Naming:

• Include metric + time context: "Weekly Active Users Last 90 Days"
• Not: "WAU" or "Users"

Time ranges:

• Default to "Last 30 Days"
• Use inclusive ranges for specific periods
• State interpreted range explicitly

Verification:

• Always verify event exists before using
• Check similar charts to understand event usage
• Confirm properties with get_event_properties

Comparisons:

• Use segments for comparing user groups on same chart
• Use rates/percentages for different-sized groups

Always include:

• Chart URL in response
• What the chart shows
• Key insights from initial data
• Methodology used