AI Analyst Plus

An AI-powered product analyst that lives inside Claude Code. Ask business questions in plain English, get validated analyses, branded charts, and stakeholder-ready slide decks — in minutes, not days.

18 agents | 55 skills | 40 helper modules | DAG-based parallel execution | PDF + HTML + Google Docs export

---

What This Is

AI Analyst Plus turns Claude Code into a product analytics system. It combines:

• Skills (.claude/skills/) — standards Claude follows automatically (chart styling, data validation, question framing, stakeholder communication)
• Agents (agents/) — multi-step analytical workflows orchestrated by a DAG engine (question framing → data exploration → analysis → storytelling → deck creation)
• Helpers (helpers/) — Python modules for charting, SQL validation, data connectivity, statistical tests, and more
• Knowledge (.knowledge/) — persistent memory for dataset context, corrections, proven SQL patterns, and business glossary

You interact by talking to Claude. Ask a question, invoke a slash command, or let Claude figure out which skills and agents to apply.

---

Quick Start

1. Clone and install

git clone https://github.com/ai-analyst-lab/ai-analyst-plus.git
cd ai-analyst-plus
pip install -e ".[dev]"

2. Connect your data (optional)

In Claude Code, run /connect-data to wire up a warehouse (DuckDB, Postgres, BigQuery, Snowflake) or a CSV directory. Curated public datasets with guides live in data/examples/.

3. Start Claude Code

claude

4. Ask a question

What's our conversion rate by device?

Or run the full pipeline:

/run-pipeline question="Why is conversion dropping on mobile?"

---

Don’t Know What to Do? Just Ask.

Claude knows the entire system — every agent, skill, command, and dataset. If you’re stuck:

What can I do with this data?
What should I run to refresh the deck?
How do I connect my own CSV files?
Which agents handle root cause analysis?
Re-run just the chart maker and deck creator.

You don’t need to memorize anything in this README. Think of it as a reference — Claude is the guide.

---

Five Things You Can Do

1. Ask a quick question

What's our conversion rate by device?

Claude queries the data and returns an answer with a chart. Simple questions get answered in under 2 minutes without running the full pipeline.

2. Run a full analysis

/run-pipeline question="What's driving the decline in conversion?"

The pipeline runs 18 agents across 4 phases: Frame the question, Analyze the data, Build the story, Create the deck. You get a validated analysis, branded charts, a narrative, and a slide deck with speaker notes. Exports to PDF, HTML, and Google Docs.

3. Explore a dataset

/explore

Interactive data browsing without committing to a full analysis. Preview tables, check distributions, spot patterns, form hypotheses.

4. Connect your own data

/connect-data

Guided wizard for CSV files, local DuckDB, Postgres, BigQuery, or Snowflake. Auto-profiles your data, creates schema docs, and remembers context across sessions.

5. Make a single chart

Make a funnel chart of the checkout flow, highlighting the biggest drop-off step.

Charts follow Storytelling with Data methodology: warm off-white background, decluttered axes, action title, direct labels instead of legends.

---

How It Works: The Pipeline

When you run /run-pipeline, Claude orchestrates 18 agents across 4 phases:

1. FRAME              2. ANALYZE                          3. STORY                 4. DECK
+-----------------+   +-----------------------------+   +--------------------+   +------------------+
| Question        |   | Data Explorer               |   | Story Architect    |   | Storytelling     |
|   Framing       |   |   > Source Tie-Out           |   |   > Coherence      |   |   > Deck Creator |
|   > Hypothesis  |   |   > Descriptive Analytics    |   |     Reviewer       |   |   > Slide Review |
|     Generation  |   |   > Root Cause Investigator  |   |   > Chart Maker    |   |   > Close the    |
|                 |-->|   > Validation               |-->|   > Design Critic  |-->|     Loop         |
+-----------------+   |   > Opportunity Sizer        |   +--------------------+   +------------------+
                      +-----------------------------+

Phase 1 — Frame: Structures your business question into analytical questions with testable hypotheses.

Phase 2 — Analyze: Explores the data, verifies loading integrity, runs segmentation/funnel/drivers analysis, drills to root cause, validates findings, and sizes the opportunity.

Phase 3 — Story: Designs a storyboard (Context-Tension-Resolution arc), generates charts with collision detection, and reviews visual quality.

Phase 4 — Deck: Writes a stakeholder narrative, builds a branded Marp slide deck, reviews design, and ensures every recommendation has a follow-up plan. Exports to PDF, HTML, and Google Docs.

Five execution plans let you run just the part you need:

/run-pipeline question="..." plan=deep_dive

If the pipeline gets interrupted, resume where you left off:

/resume-pipeline

---

All Commands

Or just ask in plain English. “Show me conversion by device” works as well as any command.

---

Your Data

This repo ships clean — no bundled datasets. Connect your own data and the system builds context around it.

Connect your own

Run /connect-data for a guided wizard, or /setup for full onboarding. Supported sources:

• CSV files — drop them in a directory, point Claude at it
• DuckDB — local or MotherDuck
• Postgres — any Postgres-compatible database
• BigQuery — Google BigQuery with service account
• Snowflake — Snowflake with user/password or key pair

The system auto-profiles your data, creates schema documentation, and remembers context across sessions in .knowledge/datasets/.

Sample data

Bring your own data via /connect-data (DuckDB, Postgres, BigQuery, Snowflake, or a CSV directory). Curated public datasets with README guides are available in data/examples/.

---

Architecture

ai-analyst-plus/
├── CLAUDE.md                    # AI persona, skills table, rules, workflow
├── agents/                      # 18 agent prompt templates (markdown)
│   ├── registry.yaml            # DAG dependencies and execution order
│   └── CONTRACT_TEMPLATE.md     # Template for writing new agents
├── .claude/skills/              # 55 skill definitions
├── helpers/                     # 40 Python modules
│   ├── chart_helpers.py         # SWD charting (swd_style, highlight_bar, etc.)
│   ├── data_helpers.py          # Data source abstraction
│   ├── sql_helpers.py           # SQL sanity checks
│   └── ...
├── .knowledge/                  # Persistent memory (dataset context, corrections, patterns)
│   ├── active.yaml              # Currently active dataset
│   └── datasets/                # Per-dataset manifest, schema, quirks
├── themes/                      # Marp CSS themes (light + dark)
├── templates/                   # Marp deck templates, HTML components
├── outputs/                     # Final deliverables (analyses, charts, decks)
└── working/                     # Intermediate files (gitignored)

Skills vs Agents

Skills are standards Claude follows automatically. When you make a chart, the Visualization Patterns skill activates. When you start an analysis, Data Quality Check runs. You never invoke them — they apply when their trigger condition matches. Multiple skills can fire at once.

Agents are multi-step workflows for specific tasks. They’re markdown prompt templates with {{VARIABLES}} that get substituted at runtime. The pipeline orchestrates them in dependency order using a DAG engine.

Knowledge System

.knowledge/ persists across sessions:

• Dataset context — schema, quirks, connection details per dataset
• Corrections — logged mistakes so the same SQL error never happens twice
• Query archaeology — proven SQL patterns retrieved before writing new queries
• Business glossary — organization-specific terms, metrics, products, teams (importable from Notion)

---

Customization

---

Requirements

• Python 3.10+
• Claude Code with a Claude Pro or Max subscription
• Node.js 18+ (for Marp PDF/HTML export)
• Internet connection (for Claude API and optional cloud data sources)

---

Getting Help

• Setup guide: docs/setup-guide.md
• Theming: docs/theming.md
• Questions or bugs: Ask in the #help channel on Slack