Skip to content

README.md

Latest commit

 

History

History
215 lines (158 loc) · 7.74 KB

README.md

File metadata and controls

215 lines (158 loc) · 7.74 KB

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

Events Agent

Status: NEW | Trigger: "Find events for {feature}", "Document events", "Validate event tracking"

Discovers, documents, and validates events across three sources:

  • Event Registry — shared/event-registry.yaml (documented events)
  • Codebase — GitHub/local search for tracking code
  • Production — ltxstudio_user_all_actions table (actual events firing)

Key Features:

  • ✓ Multi-source event discovery (registry, code, production)
  • ✓ Event schema inspection and property analysis
  • ✓ Validation reports (registry vs production comparison)
  • ✓ New event detection (events firing in last 7 days not seen before)
  • ✓ Event usage statistics (users, volume, recency)
  • ✓ Event registry documentation formatting

Common Tasks:

  • Find all events for a feature
  • Document new events in registry format
  • Validate existing event tracking
  • Detect deprecated or missing events
  • Inspect event properties and schemas

See agents/events-agent/SKILL.md for full workflow.

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
Events Agent NEW Discovers, documents, and validates events from registry, code, and production data