tableau-dashboard-creator

Files (60)

• LICENSE
• SKILL.md
• fallback-design-tokens.md · assets/
• top-level-workbook-example.twb · examples/
• local.patch
• DASHBOARD.md · references/snippets/dashboard/
• action-filter.twb · references/snippets/dashboard/
• highlight-action.twb · references/snippets/dashboard/
• multi-sheet-layout.twb · references/snippets/dashboard/
• parameter-action.twb · references/snippets/dashboard/
• single-sheet-layout.twb · references/snippets/dashboard/
• DATA_MODEL.md · references/snippets/data-model/
• multi-csv-join.twb · references/snippets/data-model/
• multi-csv-relationship.twb · references/snippets/data-model/
• single-csv.twb · references/snippets/data-model/
• FEATURES.md · references/snippets/features/
• calculated-field.twb · references/snippets/features/
• lod-expression.twb · references/snippets/features/
• parameter-control.twb · references/snippets/features/
• reference-line.twb · references/snippets/features/
• tablea-calculation.twb · references/snippets/features/
• SCAFFOLD.md · references/snippets/scaffold/
• workbook-skeleton.twb · references/snippets/scaffold/
• WORKSHEETS.md · references/snippets/worksheets/
• area-chart.twb · references/snippets/worksheets/
• bar-chart-filtered.twb · references/snippets/worksheets/
• bar-chart-sorted.twb · references/snippets/worksheets/
• bar-chart-styled.twb · references/snippets/worksheets/
• bar-chart.twb · references/snippets/worksheets/
• combo-chart.twb · references/snippets/worksheets/
• custom-tooltip.twb · references/snippets/worksheets/
• dual-axis.twb · references/snippets/worksheets/
• histogram.twb · references/snippets/worksheets/
• line-chart.twb · references/snippets/worksheets/
• map-chart.twb · references/snippets/worksheets/
• pie-chart.twb · references/snippets/worksheets/
• scatter-plot.twb · references/snippets/worksheets/
• stacked-bar-chart.twb · references/snippets/worksheets/
• text-table.twb · references/snippets/worksheets/
• step-0-brand-setup.md · references/
• step-a-data-exploration.md · references/
• step-b-dashboard-planning.md · references/
• step-c-mock-creation.md · references/
• step-d-implementation-spec.md · references/
• step-e-twb-generation.md · references/
• tableau-design-tokens.md · references/
• twb_2026.1.0.xsd · references/xsd/
• user.xsd · references/xsd/
• xml.xsd · references/xsd/
• query_postgresql.py · scripts/
• validate_twb.py · scripts/
• validate_twb_xsd.py · scripts/
• .env.example · skeleton/
• EXAMPLE-PRD.md · skeleton/
• QUERIES.md · skeleton/
• SalesPerformance-PRD.md · skeleton/
• branding.md · skeleton/branding/
• customer_segments.csv · skeleton/sample-data/
• monthly_targets.csv · skeleton/sample-data/
• sales_orders.csv · skeleton/sample-data/

SKILL.md (first lines)

# 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:

```markdown
## 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](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](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

From Kilo-Org/kilo-marketplace, Apache-2.0.

More from Kilo-Org/kilo-marketplace