agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/skills/power-bi/pbir-report-workflow/SKILL.md

pbir-report-workflow

Skill1 starsChanged 34 days agoMITView on GitHub

Use for any work on a Power BI report in PBIR format, a `.Report` folder: building one on a published semantic model, laying out its pages and visuals, filters, bookmarks, themes and conditional formatting, by the `pbir` CLI (pbir-cli) or by hand-editing `visual.json`, `page.json`, `pages.json`, `report.json`, `reportExtensions.json` or a theme file, then validating, publishing and checking the rendered pages; and its design: tone, chart choice, colour, typography, layout, accessibility.

  • Sends data out

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep visuals from overlapping

    line 47
  2. Distinctive:

    Always create reports inside a named project folder

    line 50
  3. Very specific:

    Run pbir validate after every mutation

    line 51
  4. Distinctive:

    Use PascalCase for project / report / page / visual names

    line 52
  5. Very specific:

    Add no PBI_* annotations by hand

    line 54
  6. Very specific:

    Ask the user (via AskUserQuestion) to confirm whichever of these the request leaves open:

    line 65
  7. Very specific:

    Every existing visual's position.x, position.y, position.width, position.height.

    line 120
  8. Distinctive:

    All subsequent coordinates should be derived from those measured values, not hardcoded from this doc.

    line 124
  9. Very specific:

    Every layout starts from four constants: (page_width, page_height, margin, gap).

    line 128
  10. Distinctive:

    After placing visuals, verify the arithmetic yourself:

    line 198
  11. Very specific:

    If either equation fails, adjust before saving.

    line 205
  12. Very specific:

    Prefer extension measures returning theme tokens ("good", "bad") over hex strings so the theme can be rebranded centrally.

    line 240
  13. Distinctive:

    Default to monthly when unsure.

    line 259
  14. Very specific:

    After publishing, render the report server-side and review the PNGs — this is the visual feedback loop, no Power BI Desktop involved.

    line 276
  15. Very specific:

    If a scripts/data/report-png.sh wrapper is deployed in the repo (an internal local-cli template), prefer it over raw curl.

    line 314
  16. Distinctive:

    Use prior-year measures as targets when available.

    line 330

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PBIR Report Workflow

End-to-end workflow for building Power BI reports from a published semantic model using pbir CLI. Requires the model to already exist in a Fabric/Power BI workspace.

Read the reference first

The steps below build a report through the pbir CLI. Anything they do not cover has a reference in references/, and nothing loads one for you: read it before acting.

Before a hand edit of report JSON, read the file's reference:

Before editingRead
visual.jsonvisual-json.md; for a colour rule, gradient, data bar or icon, conditional-formatting.md too
reportExtensions.json, the extension measuresconditional-formatting.md
page.json or pages.jsonpages.md
a filterConfig, in report.json, page.json or visual.json, or the filter pane's visibilityfilters.md
a theme file under StaticResources/, or report.json's themeCollectionthemes.md
bookmarks.json or a *.bookmark.jsonbookmarks.md

Before a pbir command the steps do not show, find its verb in pbir-cli.md and its flags in pbir-cli-commands.md.

Before a design decision (tone, chart choice, colour, typography, layout, accessibility) or a redesign, restyle or critique, read design/design.md. Its Design Brief comes back to these steps to be built.

Workflow Steps

The Step sections below are the workflow, in order. Step 3 measures the scaffold before any layout is computed.

Rules

  • Keep visuals from overlapping
  • Favor theme changes over per-visual overrides
  • Favor extension measures (_Fmt) with theme tokens (good/bad) for conditional formatting
  • Always create reports inside a named project folder
  • Run pbir validate after every mutation
  • Use PascalCase for project / report / page / visual names
  • Edit PBIR JSON directly or with pbir set, not with Tabular Editor
  • Add no PBI_* annotations by hand

Step 1 — Requirements & Model Discovery

pbir model                                                               # List reports + models
pbir model "Sales.Report" -d                                             # Model definition
pbir model "Sales.Report" -d -t Sales                                    # Filter to table
pbir model "Sales.Report" -q "EVALUATE VALUES('Date'[Year])"             # Query for filter values

Ask the user (via AskUserQuestion) to confirm whichever of these the request leaves open:

  • Which KPIs to surface (measures + targets)
  • Trend granularity (daily / weekly / monthly / quarterly)
  • Categorical breakdowns
  • Detail table/matrix hierarchies
  • Report-level vs page-level filters

Step 2 — Scaffold Report

mkdir -p SalesDashboard && cd SalesDashboard
pbir new report "Sales.Report" -c "MyWorkspace/Sales.SemanticModel"
pbir pages rename "Sales.Report/Page 1.Page" --to Overview -f
pbir pages active-page "Sales.Report" "Overview"

The rename moves the folder and displayName only. Set page.json name and pages.json pageOrder and activePageName to the new folder name by hand, then pbir validate (0.9.29 and 0.9.32, 2026-10-08).

Resulting layout:

SalesDashboard/
  Sales.pbip
  Sales.Report/
    definition.pbir
    definition/
      version.json
      report.json
      pages/
        pages.json
        Overview/
          page.json
          visuals/Title.Visual/visual.json
    StaticResources/

Step 3 — Measure the Scaffold Before Laying Out

pbir new report produces a default page with some combination of a pre-placed title textbox, a baked-in theme, and canvas defaults. Exact coordinates, theme name, and visual positions depend on the CLI version and the chosen --from-template. Before planning anything, read the actual scaffold instead of assuming:

pbir cat "Sales.Report/Overview.Page"                                    # Full page.json (width, height, displayOption)
pbir ls  "Sales.Report/Overview.Page"                                    # Existing visuals on the page
pbir tree "Sales.Report" -v                                              # Every visual + bindings
pbir cat "Sales.Report/theme"                                            # Active theme name + palette

From the output, record:

  1. Canvas width / height from page.json, which the base theme and the template set (Common Page Sizes, below).
  2. Every existing visual's position.x, position.y, position.width, position.height. For bulk reads use jq '.position' <path>/visual.json across the visuals/ folder.
  3. The tallest y + height among existing visuals — the first safe y for a new row you add.
  4. Active base and custom theme names — so you don't accidentally re-apply a default over meaningful styling.

All subsequent coordinates should be derived from those measured values, not hardcoded from this doc.

Step 4 — Layout Math (3-30-300)

Every layout starts from four constants: (page_width, page_height, margin, gap).

Example (1280 x 720 canvas with margin=24, gap=16):

usable_width  = page_width  - (2 * margin) = 1232
usable_height = page_height - (2 * margin) = 672
3 equal columns = (usable_width - 2*gap) / 3 = 400
2 equal columns = (usable_width - gap) / 2 = 608

Substitute your measured page_width / page_height — do not hardcode 1280/720.

3-30-300 visual hierarchy — design for three viewing distances:

DistanceViewPayload
3 secondsGlanceHeadline KPIs + target delta
30 secondsScanTrend direction + top-1 breakdown
300 secondsInvestigateDetail table with hierarchies + conditional formatting

Standard 3-row composition — compute each row from the measured scaffold:

RowContent
Top regionExisting title / header visuals already in the scaffold
Row 13 KPI visuals side-by-side
Row 2Line chart + bar chart (2 columns)
Row 3Full-width tableEx detail

Row heights, the gap between rows, and y offsets all come from the measured scaffold plus your chosen margin / gap. Verify the total fits inside page_height before placing any visual.

Step 5 — Add Visuals (Coordinates Explicit)

The coordinates below are illustrative — computed from a measured 1280x720 scaffold with a ~90 px header region, margin=24, gap=16. Substitute values from your actual measurement before running these commands.

# Row 1: KPIs
pbir add visual kpi "Sales.Report/Overview.Page" --title "Revenue" \
  -d "Indicator:Invoices.Turnover" -d "Goal:Invoices.Turnover 1YP" \
  -d "TrendLine:Date.Calendar Month (ie Jan)" \
  --x 24 --y 120 --width 400 --height 140

pbir add visual kpi "Sales.Report/Overview.Page" --title "OrderLines" \
  -d "Indicator:Orders.Order Lines" -d "Goal:Orders.Order Lines 1YP" \
  --x 440 --y 120 --width 400 --height 140

pbir add visual kpi "Sales.Report/Overview.Page" --title "MarginPct" \
  -d "Indicator:Invoices.Selling Margin (%)" -d "Goal:Invoices.Selling Margin (%) 1YP" \
  --x 856 --y 120 --width 400 --height 140

# Row 2: Trend + Breakdown
pbir add visual lineChart "Sales.Report/Overview.Page" --title "MonthlyTrend" \
  --x 24 --y 276 --width 608 --height 208
pbir visuals bind "Sales.Report/Overview.Page/MonthlyTrend.Visual" \
  -a "Category:Date.Calendar Month (ie Jan)" -a "Y:Invoices.Turnover"

pbir add visual barChart "Sales.Report/Overview.Page" --title "ByRegion" \
  -d "Category:Regions.Territory" -d "Y:Invoices.Turnover" \
  --x 648 --y 276 --width 608 --height 208

# Row 3: Detail
pbir add visual tableEx "Sales.Report/Overview.Page" --title "DetailByAccount" \
  --x 24 --y 500 --width 1232 --height 196
pbir visuals bind "Sales.Report/Overview.Page/DetailByAccount.Visual" \
  -a "Values:Customers.Key Account Name" -a "Values:Invoices.Turnover" -a "Values:Orders.Order Lines"

Step 6 — Spacing Sanity-Check

After placing visuals, verify the arithmetic yourself:

left_margin + usable_width + right_margin == page_width
top_region + Σ(row_heights) + (n-1) * gap + bottom_margin == page_height

If either equation fails, adjust before saving. pbir tree "Sales.Report" -v lists every visual's position in one command.

Step 7 — Sort, Filters, Theme Overrides

# Charts auto-sort descending by first measure. Set explicitly after bind.
pbir visuals sort "Sales.Report/Overview.Page/ByRegion.Visual" \
  -f "Invoices.Turnover" -d Descending

# Report-level filters (apply to all pages)
pbir add filter Date Year     -r "Sales.Report" --values 2025
pbir add filter Geography Region -r "Sales.Report"

# Page-level filters
pbir add filter Products Category -p "Sales.Report/Overview.Page"

Step 8 — Title Hierarchy

Distribute meaning across the title hierarchy — never say the same thing twice.

LevelContent
Page title (textbox)The subject — "OrderLines"
Visual titlesThe differentiator — "byKeyAccount", "MonthlyTrend"
SubtitlesHide — almost always redundant
pbir visuals subtitle "Sales.Report/Overview.Page/MonthlyTrend.Visual" --no-show

Hide axis titles when the axis is self-evident (month names on x-axis). Hide category labels on cards when the visual title describes the metric.

Step 9 — Conditional Formatting via Extension Measures

Prefer extension measures returning theme tokens ("good", "bad") over hex strings so the theme can be rebranded centrally.

pbir dax measures add "Sales.Report" -t _Fmt -n "RevenueStatusColor" \
  -e 'IF([Turnover] >= [Turnover 1YP], "good", "bad")' --data-type Text

pbir visuals cf "Sales.Report/Overview.Page/ByRegion.Visual" \
  --measure "dataPoint.fill _Fmt.RevenueStatusColor"

Step 10 — Inferring Time Granularity from Filter Context

Active FilterTrend GranularityDate Column
Year (e.g., 2025)MonthlyDate.Calendar Month (ie Jan)
QuarterMonthly or WeeklyDate.Calendar Month (ie Jan) / Date.Calendar Week EU
MonthDaily or WeeklyDate.Date / Date.Calendar Week EU
No date filterMonthly or QuarterlyDate.Calendar Month Year / Date.Calendar Quarter Year

Default to monthly when unsure.

Step 11 — Validate, Publish, Open

pbir validate "Sales.Report"
pbir tree     "Sales.Report" -v
pbir publish  "Sales.Report" "MyWorkspace.Workspace/Sales.Report" -o     # Publish + open
pbir open     "Sales.Report"                                             # Local in Desktop

Skip pbir open for Direct Lake models — opening the PBIP forces Desktop into remote modeling and offers to overwrite the live workspace model. Use the service-side check below instead.

Step 12 — Visual Verification (Service-Side PNG Export)

After publishing, render the report server-side and review the PNGs — this is the visual feedback loop, no Power BI Desktop involved. Uses the Power BI exportToFile API.

Prerequisites: workspace on Fabric/Premium capacity; for PNG the tenant setting "Export reports as image files" must be enabled (off by default — fall back to PDF, which is on by default). Token audience is the Power BI API, not Fabric.

TOKEN=$(az account get-access-token --resource https://analysis.windows.net/powerbi/api --query accessToken -o tsv)
BASE="https://api.powerbi.com/v1.0/myorg/groups/<workspaceId>/reports/<reportId>"

# 1. Start the export job (202 Accepted)
EXPORT_ID=$(curl -s -X POST "$BASE/ExportTo" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"format":"PNG"}' | jq -r '.id')

# 2. Poll until status == "Succeeded" (percentComplete shows progress)
curl -s "$BASE/exports/$EXPORT_ID" -H "Authorization: Bearer $TOKEN" | jq '.status'

# 3. Fetch the file — multi-page reports return a .zip with one PNG per page
curl -s "$BASE/exports/$EXPORT_ID/file" -H "Authorization: Bearer $TOKEN" -o report.zip
unzip -o report.zip -d report-pages/

Then read each PNG (the agent can view images), check against the layout plan — overlaps, truncated titles, sort order, empty visuals, theme colors — and iterate: edit PBIR → pbir validate → pbir publish → re-export.

Notes:

  • Page file names match the Get Pages API names (ReportSection...), not display names — map via GET $BASE/pages.
  • A specific page or a bookmark state can be exported via the powerBIReportConfiguration body (pages, defaultBookmark).
  • Empty visuals in the export usually mean a binding mismatch — see fabric-rest-api's references/gotchas.md (byConnection rebind / TMDL binding diff).
  • If a scripts/data/report-png.sh wrapper is deployed in the repo (an internal local-cli template), prefer it over raw curl.

Common Page Sizes

TypeWidth x HeightUse Case
Default 16:9, Fluent 2 base theme (new reports)1920 x 1080Screen dashboards
Default 16:9, Classic 2018 / Classic 2026 base themes1280 x 720Screen dashboards
Large (16:9)1920 x 1080High-density executive dashboards
Letter portrait816 x 1056Print/PDF reports
Tooltip320 x 240Hover tooltip pages
Custom tall1280 x 2400Scrollable operational pages

KPI Target Measures

Use prior-year measures as targets when available. Add via TMDL if missing:

measure 'Turnover 1YP' = CALCULATE([Turnover], DATEADD('Date'[Date], -1, YEAR))

Gotchas

IssueCauseFix
Visual overlaps existing scaffold elementPlaced y before measuring scaffoldRun pbir ls + inspect position of every pre-existing visual first
Extra blank page on report openpbir add page called instead of renamepbir pages rename "<Name>.Report/Page 1.Page" --to Overview -f, then align the page ids — see Step 2
Charts show wrong sort orderDefault auto-sort not set after bindpbir visuals sort -f ... -d Descending
Theme overridden by visual formattingInline formatting appliedpbir visuals clear-formatting --only-containers -f
Publish 401Wrong Fabric token audienceaz account get-access-token --resource https://api.fabric.microsoft.com
Page doesn't fit canvasdisplayOption set to integerMust be string: "FitToPage" etc.
Extension measure CF not renderingreferences.measures missing a depEvery measure used in DAX must appear in references.measures
Trend chart has wrong granularityGranularity not matched to filterConsult granularity table
Right margin looks offLayout math not verifiedPrint spacing verification (left + usable + right = width)

Reference

See also

  • pbip-project-structure — project file layout
  • pbir-cli.md — CLI command reference
  • pages.md — page JSON structure
  • fabric-tmdl — TMDL measure authoring

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.