agentleFS
santoshkanthetysantoshkanthety/powerbi-agent/skills/powerbi-pbir-format-enhanced/SKILL.md

powerbi-pbir-format-enhanced

Skill3 starsChanged 7 months agoMITView on GitHub

Format reference for Power BI Enhanced Report (PBIR) JSON schemas and patterns. Automatically invoke when the user asks about PBIR JSON structure, visual.json properties, PBIR expressions, objects vs visualContainerObjects, theme inheritance, conditional formatting patterns, extension measures, bookmarks, field references, filter formatting, query roles, PBIR page structure, report wallpaper, or any PBIR metadata format question.

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow within reason the mental model when working with reports.

    line 11
  2. Distinctive:

    Check examples: Check examples for a valid report

    line 17
  3. Distinctive:

    PBIR files are strict JSON: No comments allowed

    line 22
  4. Distinctive:

    DON'T MAKE ASSUMPTIONS: Check the Microsoft documentation and other reputable resources for context if needed, or ask the user.

    line 23
  5. Distinctive:

    Follow within reason the mental model when reviewing or providing feedback on reports.

    line 59
  6. Very specific:

    Check the connected semantic model.

    line 65
  7. Very specific:

    Ensure definition.pbir is configured properly (byPath or byConnection)

    line 72
  8. Very specific:

    Use a theme.json file. Recommended: the SQLBI/Data Goblins theme

    line 73
  9. Very specific:

    Add appropriate filters to report.json or page.json.

    line 74
  10. Very specific:

    Use a custom theme; push formatting to the theme over bespoke visual.json unless the user specifies otherwise

    line 80
  11. Distinctive:

    Every page needs a title (textbox or background image).

    line 82
  12. Distinctive:

    Follow the 3-30-300 rule: KPIs/cards at top, breakdowns in middle, detail at bottom.

    line 83
  13. Distinctive:

    Prefer Deneb, Python, or R custom visuals over SVG or heavily customized core visuals -- balance elegance against technical debt

    line 84
  14. Distinctive:

    Use report extensions (thin report measures, visual calculations) only when model measures are not feasible

    line 85
  15. Distinctive:

    Use consistent colors to direct attention, not to decorate.

    line 87
  16. Very specific:

    Use consistent fonts. Set altText for accessibility.

    line 89

≈ “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 Format Reference

Skill that teaches Claude about the Power BI Enhanced Report (PBIR) JSON format to read and use it. Doesn't support legacy report.json or layout report metadata. To convert from legacy to PBIR format, users have to open and save their reports in Power BI Desktop.

Follow within reason the mental model when working with reports.

WARNING: The PBIR format is brittle and easily corrupted. Direct JSON file modification can lead to corruption. Prefer using the pbir CLI tool if available (uv tool install pbir-cli or pip install pbir-cli), as it has built-in safeguards against breaking report files. Only fall back to direct JSON modification if the user explicitly requests it or if pbir is not available.

General, critical guidance

  • Check examples: Check examples for a valid report
  • Take a backup: Make a copy of the report before modifying it
  • PBIX vs PBIP vs PBIR: So long as report metadata is in PBIR format, any of these formats works. PBIX is just a zip file; unzip and rezip to work with it. Do not work with PBIT (Power BI Template) file types. Note that PBIP and PBIX contain PBIR, but a "thin" report can be PBIR only.
  • Valid JSON vs. Rendering JSON: Valid JSON does not guarantee rendering. A visual might not render if the bound field is invalid (missing, wrong table, or misspelled) in the visual.json, if the visual elements are cropped by their container, if a model performance issue causes the dax query to time out, if a model data quality issue results in (Blank) or empty values, etc. Check whether a visual rendered using tools like the chrome or chrome devTools MCP server if the report was published to Power BI, but it's often faster to just ask the user to check in Power BI Desktop or the browser.
  • Hierarchical formatting cascade: In Power BI reports, formatting is determined by the following order of operations: defaults --> Theme wildcards (*) --> Theme visualTypes --> bespoke visual.json configuration. Theme overwrites defaults, visualType overrides wildcards in themes, and visual.json overrides all theme formatting. Prefer putting as much of the formatting in the theme as possible over bespoke visual.json formatting because then changes only need to happen in one place
  • PBIR files are strict JSON: No comments allowed
  • DON'T MAKE ASSUMPTIONS: Check the Microsoft documentation and other reputable resources for context if needed, or ask the user.

Report Structure

Report.Report/
+-- .pbi/localSettings.json                # Local-only, gitignored
+-- .platform                              # Fabric Git integration
+-- definition.pbir                        # Semantic model connection (byPath or byConnection) can open this file in Power BI Desktop to open the report
+-- mobileState.json                       # Mobile layout (niche)
+-- semanticModelDiagramLayout.json        # Model diagrams
+-- CustomVisuals/                         # Private custom visuals only
+-- definition/
|   +-- version.json                       # REQUIRED -- PBIR version
|   +-- report.json                        # REQUIRED -- report-level config, including theme, report filters, settings
|   +-- reportExtensions.json              # Extension measures and visual calculations (report- and visual-level DAX)
|   +-- pages/
|   |   +-- pages.json                     # Page order, active page
|   |   +-- [PageName]/                    # Power BI Desktop may generate names with spaces; recommend no spaces for human-authored names
|   |       +-- page.json                  # Page-level properties, including size, background, filters
|   |       +-- visuals/
|   |           +-- [VisualName]/
|   |               +-- visual.json        # Visual config, formatting, and field data bindings <-- most important and complex file for report dev and formatting
|   |               +-- mobile.json        # Mobile formatting of the visual (niche)
|   +-- bookmarks/                         # Bookmarks are a bad practice and should be avoided if possible!
|       +-- bookmarks.json                 # Bookmark order and groups
|       +-- [id].bookmark.json             # Individual bookmark state containing a snapshot of the report basically
+-- StaticResources/
    +-- RegisteredResources/               # Custom themes, images
        +-- [ThemeName].json               # Custom theme <-- second most important and complex file for formatting
    +-- SharedResources/BaseThemes/        # Microsoft base themes

Rules

Follow within reason the mental model when reviewing or providing feedback on reports.

Modifying a report

  1. Understand the user's request. Ask questions if necessary to clarify the business context -- focus on the business process, the users, and the model
  2. Explore the report efficiently to locate relevant pages and visuals
  3. Check the connected semantic model. For thin reports (byConnection), use fab, pbir, or te CLI tools to explore the model. For byPath, connect to the local model in Power BI Desktop. Understanding the model reveals available fields and calculation logic
  4. Identify the appropriate visuals and pages to modify. Ask the user for clarification if needed
  5. Plan modifications with the correct PBIR structure and property values

Creating a report

  1. Same workflow as modifying, except files are generated from scratch. Use pbir new if the pbir CLI is available; otherwise, check the example reports thoroughly
  2. Ensure definition.pbir is configured properly (byPath or byConnection)
  3. Use a theme.json file. Recommended: the SQLBI/Data Goblins theme
  4. Add appropriate filters to report.json or page.json; see filter pane reference

Additional validation

For detailed report design guidance (layout, spacing, visual hierarchy, color, accessibility), see the pbi-report-design skill. Key rules enforced during validation:

  • Use a custom theme; push formatting to the theme over bespoke visual.json unless the user specifies otherwise
  • Visuals must not overlap; maintain equal spacing between visuals and page edges
  • Every page needs a title (textbox or background image). Ensure textboxes are tall enough to render (24-28 pt)
  • Follow the 3-30-300 rule: KPIs/cards at top, breakdowns in middle, detail at bottom. Maximum 2-3 slicers per page; use the filter pane for additional filtering
  • Prefer Deneb, Python, or R custom visuals over SVG or heavily customized core visuals -- balance elegance against technical debt
  • Use report extensions (thin report measures, visual calculations) only when model measures are not feasible
  • Centralize conditional formatting in extension or model measures referencing theme semantic colors ("bad", "good")
  • Use consistent colors to direct attention, not to decorate. Avoid pie charts beyond 5 categories
  • Sort visuals logically (typically descending by measure). Start chart axes at zero unless there is an explicit reason not to
  • Use consistent fonts. Set altText for accessibility. Name visuals descriptively (revenue_bar_chart not a1b2c3d4)
  • Eliminate redundant visuals. Consider the "Apply" button on high-cardinality slicers
  • See the Data Goblins report checklist for pre-deployment validation

What to Read for Common Tasks

TaskRead
Add or modify a visualreferences/visual-json.md -- expression syntax, field references, query roles, position, objects vs visualContainerObjects, selectors
Change formatting or colorsreferences/visual-container-formatting.md (container chrome) + references/theme.md (theme-level formatting). Prefer theme changes over bespoke visual formatting
Add conditional formattingreferences/schema-patterns/conditional-formatting.md + references/measures.md (extension measures for CF)
Add or configure filtersreferences/filter-pane.md -- all 7 filter types, default values, filter discovery
Work with the themereferences/theme.md -- inheritance, wildcards, visual-type overrides, filter pane styling, inspecting and modifying with jq
Push visual formatting to themereferences/theme.md -- promote bespoke visual formatting into theme defaults for that visual type (copy from visual.json objects/visualContainerObjects into theme visualStyles)
Change page layout/backgroundreferences/page.md -- dimensions, background, wallpaper, visualInteractions
Create a tooltip pagereferences/page.md -- tooltip page setup (type, size, visibility) + visualTooltip opt-in on visuals
Create a drillthrough pagereferences/page.md -- drillthrough filter in page filterConfig
Change report settingsreferences/report.md -- themeCollection, resourcePackages, settings, outspacePane
Add extension measuresreferences/measures.md -- reportExtensions.json structure, DAX patterns, referencing
Add annotations / metadatareferences/annotations.md -- custom name-value metadata on reports, pages, and visuals for deployment scripts, documentation, and external tooling
Add images or SVGsreferences/images.md -- RegisteredResources, base64 in themes, SVG measures
Add or modify textboxesreferences/textbox.md -- paragraphs, textRuns, textStyle
Sort a visualreferences/sort-visuals.md -- sortDefinition inside query
Sync slicers across pagesreferences/visual-json.md -- syncGroup (groupName, fieldChanges, filterChanges)
Edit visual interactionsreferences/visual-json.md + references/page.md -- visualInteractions in page.json (NoFilter, Filter, Highlight)
Change table/matrix column widthsreferences/visual-json.md -- columnWidth with metadata selector
Group visualsreferences/visual-json.md -- visualGroup, parentGroupName, groupMode
Hide visuals or fieldsreferences/visual-json.md -- isHidden at root level, query projection control
Format chart elements (labels, markers, lines)references/visual-json.md -- labels, markers, lineStyles, dataPoint
Add analytics lines (reference, trend, error, forecast)references/visual-json.md -- y1AxisReferenceLine, trend, error, forecast
Work with bookmarksreferences/bookmarks.md -- bookmark state, filter snapshots, visual show/hide
Find model fieldsreferences/semantic-model/finding-fields.md -- pbir model, te, fab commands
Rebind to different modelreferences/semantic-model/report-rebinding.md -- byPath vs byConnection conversion
Understand schema versionsreferences/schemas.md -- all schema types and current versions
Understand how visuals generate DAX queriesreferences/semantic-model/inferring-queries-from-visuals.md -- visual metadata → SUMMARIZECOLUMNS mapping, data roles, IGNORE() context
Build or verify DAX query patternsreferences/semantic-model/model-queries.md -- SUMMARIZECOLUMNS patterns, ROW(), query execution methods
Rename a table or field across visual JSONreferences/rename-patterns.md -- Entity/Property/queryRef patterns in visual.json, filterConfig, reportExtensions
Fix broken field references after model changesreferences/how-to/fix-broken-field-references.md -- diagnosis, repair workflow for renamed/moved/removed fields, slicer value pitfalls
Convert legacy report.json to PBIR formatreferences/how-to/convert-legacy-to-pbir.md -- format differences, step-by-step conversion, projections-to-queryState mapping, validation
Understand reportExtensions.json schemareferences/report-extensions.md -- file schema structure, entities, visual calculations; see references/measures.md for DAX authoring patterns

definition.pbir

A report must be connected to a semantic model. There are two ways to do this:

  • byPath -- Local PBIP reference/thick report: {"byPath": {"path": "../Model.SemanticModel"}} (schema 2.0.0)
  • byConnection -- Remote/thin report: {"byConnection": {"connectionString": "Data Source=powerbi://..."}} (schema 2.0.0)

Related Skills

  • pbip -- PBIP project operations: rename cascades, project forking, report JSON patterns
  • tmdl -- TMDL file format, authoring, and editing

References

Fetching Docs: To retrieve current Power BI developer/report format docs, use microsoft_docs_search + microsoft_docs_fetch (MCP) if available, otherwise mslearn search + mslearn fetch (CLI). Search based on the user's request and run multiple searches as needed to ensure sufficient context before proceeding.

Examples:

  • examples/K201-MonthSlicer.Report/ -- Real PBIR report with 7 visual types (slicer, advancedSlicerVisual, kpi, lineChart, scatterChart, tableEx, textbox), extension measures, bookmarks, conditional formatting
  • examples/visuals/ -- 54 standalone visual.json examples; see examples/visuals/__index.md for a catalog. Split into default/ (minimal, theme-only) and formatted/ (bespoke formatting, conditional formatting, gradients, filters)

Core references:

  • references/visual-json.md -- visual.json: expressions, field refs, query roles, position, objects vs vCO, selectors, sorting, filters
  • references/pbir-structure.md -- PBIR folder structure details
  • references/schemas.md -- Schema versions and URLs
  • references/enumerations.md -- Valid property enumerations
  • references/version-json.md -- version.json format (concise)
  • references/platform.md -- .platform file format (concise)
  • references/bookmarks.md -- Bookmark structure and state snapshots

Formatting & expressions:

  • references/theme.md -- Theme wildcards, inheritance, color system, filter pane styling, visual-type overrides. Includes jq patterns for inspecting and modifying theme JSON directly
  • references/schema-patterns/ -- Expressions, selectors, conditional formatting, visual calculations
  • references/visual-container-formatting.md -- objects vs visualContainerObjects deep-dive
  • references/measures-vs-literals.md -- When to use measure expressions vs literal values
  • references/measures.md -- Extension measure patterns

Visual & page configuration:

  • references/textbox.md -- Textbox visual format
  • references/page.md -- Page configuration and backgrounds
  • references/report.md -- Report-level settings
  • references/wallpaper.md -- Report wallpaper/canvas background
  • references/filter-pane.md -- Filter pane formatting
  • references/sort-visuals.md -- Visual sort configuration
  • references/images.md -- Static images, base64 in themes, SVG measures
  • references/report-extensions.md -- reportExtensions.json format
  • references/annotations.md -- Custom metadata on reports, pages, and visuals

Semantic model integration:

  • references/semantic-model/ -- Field references, model structure, report rebinding, query inference

How-to guides:

  • references/how-to/ -- Advanced conditional formatting, SVG in visuals, fix broken field references, convert legacy to PBIR

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.