Tableau Dashboard Creator

Tableau Dashboard Creator

A multi-step workflow that transforms a human-language dashboard request into an implementable Tableau specification with an interactive HTML mock and an optional generated workbook.

Prerequisites

Before starting, scan the user's project root for:

Checklist (all paths are inside the project directory the skill is executed in, except `.env` — see note below):
- [ ] QUERIES.md — SQL queries grouped under database type headings (e.g., PostgreSQL)
      OR sample-data/ directory with CSV files
- [ ] <DASHBOARD-NAME>-PRD.md — Human-language dashboard request
- [ ] .env — Database credentials (skip if using sample-data/). Does **not** need to live
      inside the project directory — `load_dotenv()` walks upward from the current
      working directory and picks up the closest `.env` it finds, so the user can keep
      credentials in a parent directory and avoid copying secrets into the project.
      Required variables (PostgreSQL): `PG_HOST`, `PG_DATABASE`, `PG_USER`, `PG_PASSWORD`,
      and optionally `PG_PORT` (defaults to `5432`).
- [ ] branding/ directory (required) containing ONE of:
      - branding.md — brand spec (palette, fonts, padding, sizing)
      - template.twb — Organization's Tableau template workbook
      Optionally, a logo (.svg or .jpg) can be added to branding/ in either case.

If any are missing, immediately run Project Scaffolding (below) before doing anything else. Do NOT ask the user to manually provide files — scaffold first, then let them customize.

Only check for the files listed above. Do NOT check for design-tokens.md, DS-ARCHITECTURE.md, DASHBOARD-PLAN.md, or any files inside mock-version/ — those are outputs generated by the workflow steps, not user-provided inputs.

QUERIES.md Format

Queries must be grouped under a heading matching the database type:

## PostgreSQL
SELECT * FROM public.table2

The agent selects the correct query script based on the heading.

Adding other databases: The skill ships with PostgreSQL support. To add other databases (Databricks, Snowflake, MySQL, BigQuery, etc.), create a matching query_<dbtype>.py script in the installed skill's scripts/ directory following the same pattern as query_postgresql.py, add the corresponding heading to QUERIES.md, and update references/step-a-data-exploration.md.

Required Python packages

# PostgreSQL
psycopg2-binary, python-dotenv, pandas

Workflow Overview

[Scaffolding] ──[user approval]──> Step 0: Brand Setup
Step 0: Brand Setup ──[user approval]──> Step A: Data Exploration
Step A: Data Exploration ──[user approval]──> Step B: Dashboard Planning
Step B: Dashboard Planning ──[user approval]──> Step C: HTML Mock
Step C: HTML Mock ──[user approval]──> Step D: Implementation Spec
Step D: Implementation Spec ──[user approval]──> Step E: TWB Generation (Experimental)

Do NOT skip steps. Wait for explicit user approval before moving to the next step.

Project Scaffolding

When to run: Automatically when the prerequisites check finds missing files. Skip only if all prerequisite files already exist.

Process:

1. Ask the user for permission to scaffold their project directory
2. Read each file from skeleton/ in the skill directory and write its contents into the user's project root, preserving the directory structure. This creates:
   • sample-data/ — starter CSV files (sales orders, customer segments, monthly targets) for immediate testing
   • .env.example — database credentials template (rename to .env when ready)
   • EXAMPLE-PRD.md — blank PRD template with section headers and placeholder examples
   • QUERIES.md — SQL query template with database type headings
   • branding/branding.md — branding spec template with section headers and placeholder values
   • SalesPerformance-PRD.md — partially filled Sales Performance PRD as a starting reference
3. List every file created and briefly explain what the user should fill in or customize
4. Be explicit about scaffold state:
   • sample-data/ means the project is immediately usable in demo mode
   • database mode is only ready after the user fills in .env and QUERIES.md
   • branding mode is only ready after the user finishes branding/branding.md and optionally adds a logo or icons
5. Encourage the user to explore the demo/ directory in the skill repository for a complete worked example with all steps already generated
6. If both sample-data/ and a real database setup exist, explicitly tell the user which source will be used in Step A and why before proceeding
7. Wait for the user to confirm they have reviewed/customized the files, then proceed to Step 0

Important: Do NOT use shell cp commands — the skeleton directory is inside the skill installation, not the user's project. Read each skeleton file with the Read tool and write it to the user's project root with the Write tool.

Every step is iterative. The agent will not produce a perfect result in a single pass — this is expected and by design. Encourage the user to review each artifact carefully, request changes, and iterate until satisfied. This is especially true for Step C (HTML mock) and Step E (TWB generation). For Step C, encourage the user to share the mock with stakeholders for validation before approving — a well-reviewed mock prevents costly rework downstream.

Step 0: Brand Setup

Identity: Tableau design systems engineer.

Read references/step-0-brand-setup.md for detailed instructions.

Summary:

1. Ask the user for the minimum target Tableau Desktop version first (2024.2 – 2025.x default, or 2026.1+). Record the answer in design-tokens.md — it controls Step E's XML emission.
2. Detect branding source inside branding/: branding.md OR template.twb
3. Extract design tokens from branding.md (or from the .twb XML), plus optional logo if present
4. If fallback defaults are used for any missing brand decision, call out each fallback decision explicitly in design-tokens.md
5. Generate design-tokens.md in the project root
6. Present design-tokens.md to the user for approval

Step A: Data Exploration

Identity: Senior Data Engineer.

Read references/step-a-data-exploration.md for detailed instructions.

Summary:

1. Check for local data first: If sample-data/ directory exists with CSV files and the user has not clearly signaled database intent, scan those files directly
2. If QUERIES.md or .env clearly indicates DB intent, say which source you are using and why before continuing
3. If using the database path, read QUERIES.md, identify the database type from headings, and execute each query via the matching script from the installed skill:
   • PostgreSQL: run the installed skill's scripts/query_postgresql.py; it permits one read-only SELECT, WITH, or plain EXPLAIN query and enforces a hard 500-row cap
   • Other databases: add a query_<dbtype>.py script following the same read-only-by-default pattern
4. Analyze schema and sample data
5. Create DS-ARCHITECTURE.md with datasource and field descriptions
6. Present DS-ARCHITECTURE.md to the user for approval

Step B: Dashboard Planning

Identity: Senior Data Analyst specialized in informative graphs and dashboards.

Read references/step-b-dashboard-planning.md for detailed instructions.

Summary:

1. Read the PRD file, DS-ARCHITECTURE.md, and design-tokens.md
2. Identify KPIs and chart types from the user request
3. Map each visualization to specific columns from DS-ARCHITECTURE.md
4. Assign stable IDs for KPIs, charts, filters, and actions so later steps can reuse the same identifiers
5. Suggest additional KPIs and interesting data patterns
6. Propose filter strategy and dashboard actions
7. Present the dashboard plan to the user with approval criteria before moving to Step C