LTX Analytics Agents

AI agents for the LTX Analytics team. Each agent automates a different workflow (dashboards, monitoring, reports). All agents share a common knowledge base about our data, products, and metric standards.

Repo Structure

CLAUDE.md                              ← Agent dispatcher — routes requests to the right agent
shared/                                ← Shared knowledge (all agents read from here)
  product-context.md                   ← What LTX is, products, user types, business model
  bq-schema.md                        ← BigQuery tables, columns, joins, segmentation queries
  event-registry.yaml                  ← Known events per feature with status and types
  metric-standards.md                  ← How every metric is calculated (SQL templates)
  slack-channels.md                    ← Channel directory for posting results and alerts (WIP)
agents/                                ← One folder per agent
  dashboard-builder/                   ← Creates feature dashboards in Hex Threads
    SKILL.md                           ← 4-phase flow: Discover → Plan → Build → Validate
    hex-prompts/patterns.md            ← Tested prompt patterns for Hex Threads
    templates/feature-brief.md         ← Phase 1 output template
    templates/dashboard-spec.md        ← Phase 2 output template
  linear/                              ← Creates and manages Linear issues for analytics work
    SKILL.md                           ← 4-phase flow: Gather → Confirm → Create → Report
  monitoring/                          ← (Planned) Anomaly detection and alerts
  enterprise-reporter/                 ← (Planned) Enterprise account reports
  prompt-reviewer/                     ← (Planned) Prompt quality review

How It Works

Two layers:

shared/ contains everything true across all agents — BQ schema, events, metric definitions, product context, GPU cost queries and analysis patterns. Write once, every agent reads from it.

agents/{name}/ contains agent-specific instructions. Each agent has a SKILL.md that defines its workflow step by step.

CLAUDE.md is the dispatcher. It routes user requests to the right agent ("create a dashboard" → agents/dashboard-builder/SKILL.md) and lists rules that apply to all agents.

Setup

Claude Code

git clone {repo-url}
cd ltx-analytics-agents

# Add MCP connections
claude mcp add --transport http hex https://app.hex.tech/mcp
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Start
claude

Claude.ai Project

1. Create a new Project
2. Upload all files from shared/ and CLAUDE.md as project knowledge
3. Upload the agent folder(s) you need (e.g., agents/dashboard-builder/)
4. Enable connectors: Hex, Figma, Slack

Syncing Changes

Claude Code: git pull — agent picks up changes immediately.

Claude.ai: Manual — download updated files from repo, re-upload to your project.

MCP Connections

MCP	Purpose	Required?
Hex	Create dashboards via Threads	Yes (for dashboard agent)
Linear	Create and manage issues	Yes (for linear agent)
Figma	Read feature designs and flows	Recommended
Slack	Post results and alerts	Recommended
GitHub	Search codebase for events	Recommended (Claude Code only)

Adding a New Agent

1. Create the folder

agents/{agent-name}/
  SKILL.md
  {any agent-specific files}

2. Write the SKILL.md

Follow these principles (see shared/writing-guide.md or the existing dashboard-builder SKILL.md as a reference):

• Start with a frontmatter block: name and description (tells Claude when to activate)
• Write steps as numbered lists, not paragraphs
• Use imperatives: "DO read bq-schema.md" not "You might want to consider reading..."
• Reference shared files by path: "Read shared/metric-standards.md before generating SQL"
• Show what the output should look like (include a template or example)
• Add a "Rules" section with hard constraints

Minimal SKILL.md structure:

---
name: {agent-name}
description: {What this agent does. When to activate it.}
---

# {Agent Name}

## When to use
{Trigger phrases and use cases}

## Steps
1. {First step}
2. {Second step}
3. {Present to user for approval}
4. {Execute}
5. {Report results}

## Reference files
| File | Read when |
|------|-----------|
| shared/bq-schema.md | Before writing SQL |
| shared/event-registry.yaml | Before referencing events |
| shared/metric-standards.md | Before defining metrics |

## Rules
- DO {critical requirement}
- DO NOT {critical constraint}

3. Add a routing entry in CLAUDE.md

Open CLAUDE.md and add a row to the agent routing table:

| {trigger phrases} | **{Agent Name}** | `agents/{agent-name}/SKILL.md` |

4. Test on a real task

Run the agent on a real use case. Compare its output against what a human would produce. Fix the SKILL.md based on where it fails.

Contributing

When to update this repo

• New feature ships with events → add to shared/event-registry.yaml
• BQ schema changes → update shared/bq-schema.md
• New dataset or table available → add to shared/bq-schema.md with full column reference, add SQL patterns to shared/metric-standards.md
• Agent got something wrong → fix the relevant SKILL.md or reference file
• New metric type needed → add to shared/metric-standards.md
• Hex prompt pattern improved → update agents/dashboard-builder/hex-prompts/patterns.md

How to update

git pull
# Make changes
git add -A
git commit -m "fix: update retention SQL to exclude same-day returns"
git push

Current Agents

Dashboard Builder

Status: WIP | Trigger: "Create a dashboard for {feature}"

Creates feature dashboards in Hex Threads with a 4-phase workflow:

1. Discover — Find events from registry, code, and Figma
2. Plan — Generate SQL and dashboard spec for human approval
3. Build — Create charts in Hex Thread (one prompt per metric)
4. Validate — QA report with automated data quality checks

Key Features:

• ✓ Automated data quality validation (NULLs, gaps, invalid values, sample sizes)
• ✓ Inline warnings in dashboard for quality issues
• ✓ Standard metrics (Usage, Funnel, Retention, Segmentation)
• ✓ Follows metric standards and BQ best practices (partition pruning)

See agents/dashboard-builder/SKILL.md for full workflow.

Monitoring Agent

Status: NEW | Trigger: "Monitor {metric}", "Alert on {condition}"

Monitors key metrics and sends alerts across 5 specialized sub-agents:

• Revenue Monitor — MRR, ARR, subscriptions, churn, refunds
• Usage Monitor — DAU, feature adoption, generation volume, engagement
• Enterprise Monitor — Account health, quota consumption, churn risk
• BE Cost Monitor — GPU costs, utilization, cost per feature/user
• API Runtime Monitor — Latency, errors, throughput, performance

Key Features:

• ✓ Specialized monitoring per domain (revenue, usage, costs, performance)
• ✓ Baseline comparison and anomaly detection
• ✓ Integration with GPU cost attribution table
• ✓ Enterprise account health tracking

See agents/monitoring/SKILL.md for routing and individual sub-agent workflows.

---

Agent	Status	What it does
Dashboard Builder	WIP	Creates feature dashboards in Hex Threads with automated data quality validation
Linear Issue Manager	Ready	Creates and manages Linear issues for analytics work across PA teams
Monitoring Agent	NEW	Monitors revenue, usage, enterprise accounts, backend costs, and API performance with specialized sub-agents