Create and modify Power BI report files in PBIR/PBIP format using the `powerbi-report-author` and `powerbi-desktop` CLIs. Use when the user wants to: (1) implement an approved report spec or design brief, (2) add or edit pages, visuals, filters, slicers, bookmarks, themes, or formatting, (3) validat

CRITICAL NOTES 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering Power BI Report Authoring Skill (PBIR/PBIP Format) This skill enables reading, editing, and creation of Power BI report definition files in the PBIR (Power BI Report) format used by PBIP (Power BI Project) files. Must/Prefer/Avoid MUST Use this skill only for concrete PBIR/PBIP report file mechanics such as pages, visuals, filters, slicers, navigation, bookmarks, themes, formatting, validation, Desktop reloads, and screenshots. Validate PBIR with powerbi report author validate after each logical batch. Use powerbi desktop reload/screenshot workflows for rendered output changes. Use CLI capability lookup before writing visual roles, formatting objects, enum values, selectors, or expression encodings. PREFER Start from an approved Design Brief: or brief/report spec.md for greenfield report builds. Route visual design uncertainty to powerbi report design before writing files. For semantic model metadata or model side changes, use a semantic model authoring skill, Power BI Modeling MCP, or local TMDL files when available. AVOID Do not guess PBIR JSON from memory when CLI metadata or reference files are available. Do not use only this skill for open ended design, report planning, or Fabric report item CRUD; pair it with powerbi report design , powerbi report planning , or powerbi report management . Quick Start Workflow 0. Plan/design routing → for greenfield builds, read powerbi report planning first; for theming, visual style, layout, redesigns, or critiques, read powerbi report design . Return here for PBIR mechanics. Before authoring, use the Design Brief: yaml block from brief/report spec.md (or an approved inline Design Brief: block in the conversation) as implementation context. 1. Set up/update CLIs → before first use, confirm powerbi report author and the global powerbi desktop command are available; see [CLI Setup]( cli setup). 2. Understand the model → use the Semantic Model MCP Server/skill if available, or read TMDL files directly for table/column/measure names 3. Desktop context → for live Desktop status, opening PBIP/PBIX files, reloads, screenshots, or visual verification, use the powerbi desktop CLI from @microsoft/powerbi desktop bridge cli ; see [Edit → Validate → Reload → Screenshot Loop]( edit validate reload screenshot loop). 4. Route by intent → use [Topic Files and Examples]( topic files and examples) to pick the relevant guide. 5. Use CLI metadata → use [Authoring Metadata & Validation CLI]( authoring metadata validation cli) for exact visual roles, formatting objects, property names, enum values, and selector requirements; do not infer these from memory. 6. Check common pitfalls → read [Anti Patterns and Pitfalls]( anti patterns and pitfalls) before editing or validating when the change touches visuals, bindings, filters, formatting, layout, or Desktop rendering. 7. Validate → run powerbi report author validate <path to .Report dir after every logical batch of PBIR changes; see [Validation]( validation). 8. Verify rendering → for any rendered output change, use powerbi desktop reload + screenshots; see [Edit → Validate → Reload → Screenshot Loop]( edit validate reload screenshot loop) and [Screenshot Review]( screenshot review). Do not proceed until both validation and visual review pass. For dashboard/report builds, page scaffolding is not completion — each requested page needs data bound visuals. 9. Report back → give the user a concise summary of what was done and any issues encountered (major and minor). Topic Files and Examples Use the user's intent to choose the relevant topic file(s) before editing: File When to read [ authoring.md ](references/authoring.md) Adding/modifying pages, visuals, drillthrough, interactions — includes complete JSON examples [ powerbi desktop.md ](references/powerbi desktop.md) Live Desktop verification — powerbi desktop commands, PID selection, reload, screenshots, errors, troubleshooting [ screenshot review.md ](references/screenshot review.md) Screenshot review checklist and rendered output troubleshooting after Desktop screenshot capture [ formatting overview.md ](references/formatting overview.md) Read first for appearance changes — cascade model, encoding rules, selectors, routing to other formatting files [ formatting.md ](references/formatting.md) Editing visual.json appearance — selectors, VCOs, encoding mechanics, background image routing, cascade [ color strategy.md ](references/color strategy.md) Chart data point colors — theme dataColors vs dataPoint.defaultColor vs dataPoint.fill with selectors, cross visual measure color consistency [ conditional formatting.md ](references/conditional formatting.md) Data driven formatting — color gradients (FillRule), rules based, icon sets, data bars, web URL, field value [ page formatting.md ](references/page formatting.md) Editing page.json appearance — canvas background, wallpaper, page background images [ filter pane.md ](references/filter pane.md) Filter pane ( outspacePane ) and filter card ( filterCard ) chrome — Applied/Available state styling, pane width, search/checkbox colors [ theming.md ](references/theming.md) Creating or editing theme.json — dataColors, textClasses, visualStyles, style presets, ThemeDataColor reference [ re theming.md ](references/re theming.md) Switching themes on a report with existing visuals — re theming workflow (color mapping + bulk sweep), dark mode checklist, dark↔light polarity changes. Pair with theming.md when changing colors on a report with per visual overrides. [ expressions.md ](references/expressions.md) Building field references (Column, Measure, Aggregation, Hierarchy) and sort definitions [ filters.md ](references/filters.md) Adding/modifying filters — includes complete JSON examples [ slicers.md ](references/slicers.md) Read first when adding/modifying slicers or slicer selections — agent workflow, JSON templates, selection config [ cartesian.md ](references/cartesian.md) Adding bar, column, line charts — families, roles, query patterns (multi measure, drill hierarchy, date hierarchy), formatting [ map.md ](references/map.md) Adding map visuals — template, roles, geocoding workflow, handling render failures [ card.md ](references/card.md) Adding or formatting KPI/card visuals — cardVisual , id selectors, callout/value sizing, accent bars [ table.md ](references/table.md) Adding or formatting tables/matrices — tableEx , pivotTable , grow to fit columns, row banding [ image.md ](references/image.md) Adding image visuals — local resources, URLs, data bound images, ImageUrl validation/refusal workflow; also plot area background images for chart visuals [ shape.md ](references/shape.md) Adding shape visuals — containers, dividers, backgrounds, reference image matching [ textbox.md ](references/textbox.md) Adding static or dynamic textbox visuals — paragraphs, text runs, and bound value expressions [ version control.md ](references/version control.md) Git branching, committing, reverting — read when the task involves version control or safe rollback planning Greenfield / Design Handoff This skill owns PBIR file mechanics once the work is concrete: page/visual JSON, bindings, filters, slicers, themes, formatting, navigation, bookmarks, validation, Desktop reloads, and screenshots. Use powerbi report planning before authoring for new report/dashboard requests, requirements gathering, dependency checks, approval, or end to end build sequencing. Use powerbi report design for open ended visual design, redesign/restyle, brand/theme direction, chart selection, or layout critique. Return here once there is an approved spec/design brief or a concrete PBIR edit to implement — see Quick Start step 0 for how to consume the brief. Large Build Execution For full report/PBIP builds, do not delegate complete PBIP generation to a subagent — the owning agent must keep the design brief, model inventory, cross page consistency, validation loop, and Desktop verification coordinated. When context or repetition is the constraint, prefer a deterministic Node.js generator that reads the approved design brief and writes PBIR JSON. If delegation is still useful, split it by page or visual family and give each subagent the relevant brief excerpt, exact fields/measures, and layout/visual contract; have it return scoped PBIR JSON or a patch for the owning agent to integrate and validate. CLI Setup Prerequisite: Node.js 20 or later. Check with node version . If missing or older, install from [nodejs.org](https://nodejs.org/) or via your package manager — Windows: winget install OpenJS.NodeJS.LTS ; macOS: brew install node ; Linux: distro package or [nodesource](https://github.com/nodesource/distributions). Before using the CLIs in a session, ensure the latest global versions are installed: Confirm both are on PATH : PBIR File Layout A PBIP project on disk looks like this: Key Files File Purpose Agent rule .platform Fabric/PBIP report item metadata Keep it with the .Report folder definition.pbir Report → semantic model binding via byPath or byConnection Preserve schema/version unless intentionally migrating version.json PBIR format metadata Preserve the full scaffolded file, including $schema report.json Report level settings, themes, resources Edit through references and validate after changes pages.json Page order and active page Add every new page to pageOrder ; preserve activePageName page.json Page metadata, size, filters Preserve dimensions unless resizing is approved visual.json Visual type, position, query, formatting Validate roles and formatting with CLI metadata localSettings.json User local settings Do not commit or rely on it Schema URLs use the prefix developer.microsoft.com/json schemas/fabric/item/report/definition/ . The suffixes are versioned PBIR contracts that Power BI Desktop bumps with most releases (e.g. visualContainer/2.9.0 , page/2.1.0 , report/3.3.0 at the time of writing — newer values may appear in any user's PBIP). When editing, always preserve the existing $schema value ; when adding a new file, copy the $schema URL from an existing file of the same type in the same report. Do not invent or bump versions on your own. Validate with powerbi report author validate . Authoring Metadata & Validation CLI Use powerbi report author whenever you need PBIR facts that should not be guessed: visual types, data roles, formatting objects, property names, enum values, selectors, expression/value encodings, and report validation. The CLI is the source of truth for PBIR authoring details; examples and memory are not. Command Purpose When to use catalog list List all built in visual types (and any deprecated entries) Choosing a visual type catalog describe <type Roles, formatting keys, cardinality Before creating/editing a visual formatting list objects <type Valid objects. keys + VCO keys; flags objects needing id selectors Before applying formatting formatting describe object <type <object Property names, types, enum values, descriptions; selectorHint when id selector required Finding exact property names and allowed values formatting describ

powerbi-report-authoring