Agent skill power bi dashboard

Power BI Dashboard

Produce Power BI PBIP projects that open in Power BI Desktop on the first try. The strategy is simple: never author fragile file formats from memory. Start every new build from the bundled template (already proven to render in Desktop), make every report edit through the helper CLI or validated snippets, and run the deterministic linter after each change so mistakes surface immediately, not at delivery.

Core Loop

1. Resolve requirements without stalling

Read the request for: data source, pages, KPIs/metrics, and audience. Where the prompt is silent, choose a sensible default and record it as an assumption in the manifest instead of asking:

• No data source given: generate deterministic mock data and say so prominently.
• Pages: default to a single overview page; add detail pages when the request implies them.
• Calendar: calendar year. Capacity: Pro. Refresh: import with manual refresh. RLS: none.

Only stop to ask when the task is impossible to do safely: a named source file/endpoint is missing, credentials would have to be embedded, or RLS is requested without rules.

2. Start from a proven baseline

New project: scaffold from the bundled template — a complete PBIP project (Sales fact, Product dimension, marked Date dimension, one Overview page with title, cards, slicer, line chart, bar chart, table) that has been opened and rendered in Power BI Desktop:

python scripts/scaffold_pbip.py --name <ProjectName> --dest <short-path-outside-OneDrive>

It copies the template, renames everything, rewrites Power Query paths, and lints. Then transform the scaffold into the requested dashboard: rename/replace tables, swap the sample data, adjust measures and visuals. Renaming a healthy project beats authoring PBIP/TMDL/report metadata from scratch — from-scratch report JSON regularly passes schema checks yet fails Desktop hydration.

Existing project: edit in place with the smallest safe diff. Read files before editing, preserve unknown-but-valid files and existing object names, and never rewrite whole artifacts for small changes. Match the project's existing report format: PBIR folder projects (definition.pbir version 4.0+ with definition/) stay PBIR; only projects already using root report.json stay PBIR-Legacy.

3. Wire the data

Replace the template's sample CSVs or partition source expressions per source mode (patterns in references/model-report-rules.md): File.Contents + parser for local files, Folder.Files for folders, Web.Contents with RelativePath/Query for APIs, connector expressions for databases. Two non-negotiables: no secrets in any file ever (ApiKeyName names keys; values live in Power BI credential storage), and prefer build-time local extracts under data/ for demos — live refresh only when explicitly requested, because it adds credential prompts and breaks reproducibility.

Keep generated M mechanically simple (the linter checks this): single row selectors, nested {name, type} lists for Table.TransformColumnTypes, list arguments for Table.ExpandTableColumn.

4. Shape the model

Edit TMDL directly, following the template's idiom: tabs for indentation, measures with single-line DAX expressions and format strings, summarizeBy: none on non-aggregatable columns, hidden keys, single-direction relationships, marked Date table. Read references/model-report-rules.md before modeling beyond these patterns (date table spec, DAX rules, chart/slicer selection, Desktop-compatible TMDL subset).

Never name a measure the same as any column — Desktop refuses to load the model (PFE_XL_MEASURE_COLUMN_ALREADY_EXIST). The linter catches this.

5. Author the report

For PBIR-Legacy reports (the template's format), make every edit through the helper CLI so the stringified-JSON-in-JSON shapes stay correct:

python scripts/powerbi_report_helpers.py add-page    <report.json> --name ReportSectionX --display "X"
python scripts/powerbi_report_helpers.py add-textbox <report.json> --section ... --name ... --text ...
python scripts/powerbi_report_helpers.py add-visual  <report.json> --section ... --name ... --type lineChart \
    --column "Date.YearMonth=Category" --measure "Sales.Total Revenue=Y" --x 24 --y 216 --width 608 --height 240
python scripts/powerbi_report_helpers.py validate    <report.json>

Roles, raw shapes, slicer modes, and the layout grid are in references/visual-snippets.md. Use only visual types listed there or found in Desktop-generated examples — guessed visual type strings render as errors. Pick chart types and slicer modes from the data shape (rules in model-report-rules.md), give every visual a unique name and tab order, and keep bounding boxes non-overlapping.

For PBIR folder reports (existing Desktop-created projects), edit the per-page and per-visual JSON files, validating each against its own declared $schema, and keep folder names exactly matching JSON name fields.

6. Validate continuously

python scripts/powerbi_lint.py <project-root> --format json --output <project>/validation/powerbi_lint.json

Run after every meaningful change — it is fast, and a lint error caught next to its cause costs one fix instead of a debugging session at the end. It checks project shape, TMDL presence and hazards, M red flags, measure/column collisions, visual references against the model, layout overlap, tab order, naming, privacy, and more. Zero errors is the bar; surface warnings in the manifest.

When Power BI Desktop is installed and the deliverable targets Desktop, run the smoke test after lint passes (skip only if the user opts out, and then say so):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/powerbi_desktop_smoke.ps1 \
    -ReportPath <project.pbip> -OutputDir <project>/validation -TimeoutSeconds 300 -CloseWhenDone

Add -Refresh to also prove data loads. Only a JSON status of PASS (which requires the window to bind to the project, not just open) counts as Desktop evidence. On any Desktop error, look it up in the triage table in references/powerbi-desktop-compatibility.md before changing anything — most errors have a known one-line remediation.

7. Deliver honestly

Write a BUILD_MANIFEST.md (structure in references/validation-and-delivery.md) recording what was built, the source mode, assumptions, what passed, what was NOT RUN and why, and next steps. Final report ends with exactly one status label:

• DRAFT — files exist, but a required check failed, was skipped, or was unavailable.
• VALIDATED — lint passes with zero errors and all statically checkable gates pass; Desktop validation may still be NOT RUN.
• DESKTOP_VERIFIED — VALIDATED, plus the Desktop smoke (or an equivalent loader) proved the project opens with pages and visuals rendering; with -Refresh, data load was also proven.

Never imply an unavailable validator passed. NOT RUN is an acceptable answer; implied success is not.

Hard Rules

• Never embed secrets, tokens, passwords, or credential-bearing connection strings in any file — projects get committed and shared.
• Never create a measure whose name matches a column name (model will not load).
• Keep generated measure DAX on the same line as measure <name> = — multi-line expressions can deserialize with TMDL metadata polluting the DAX.
• Never emit relationship cardinality:, culture contentType:, or table-level description: in TMDL — Desktop rejects them as unsupported properties.
• If TMDL uses queryGroup:, declare the matching queryGroup object (or omit both).
• Never validate TMDL as JSON; use the linter's static checks (or a TOM/TMDL parser when available).
• Never invent PBIR/report JSON shapes or visual type strings; copy from the template, snippets, or Desktop-generated files.
• Schema-valid does not mean Desktop-renders; only open validation proves rendering.
• Save all project text files as UTF-8 without BOM; keep paths short (<260 chars) and build outside OneDrive/SharePoint folders.
• Never package or commit .pbi/cache.abf or .pbi/localSettings.json; surface .pbi/unappliedChanges.json when present (applying it can overwrite external edits).
• Preserve unknown-but-valid files and Desktop-generated object names when editing existing projects.
• Auto date/time stays disabled; the model uses an explicit, marked Date table.

References

Read on demand, not upfront:

• references/visual-snippets.md — when adding or changing report visuals.
• references/model-report-rules.md — when modeling beyond the template (M patterns, date table, DAX, chart/slicer selection, TMDL subset, anti-patterns).
• references/powerbi-desktop-compatibility.md — when Desktop throws any error (triage table), or when choosing report format for unusual cases.
• references/validation-and-delivery.md — when packaging: manifest structure, deliverable layout, escalation triggers.
• references/microsoft-docs.md — when file contracts or Desktop behavior may have changed, or the user asks about current/latest compatibility.

Reported Output

End every build with: status label, project path, source mode and classification, table/measure/page/visual counts, lint summary, Desktop/open validation result (or NOT RUN with reason), assumptions, known limitations, and next steps.