Powerbi Report Authoring

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.
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.
4. Route by intent → use Topic Files and Examples to pick the relevant guide.
5. Use CLI metadata → use 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 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.
8. Verify rendering → for any rendered-output change, use powerbi-desktop reload + screenshots; see Edit → Validate → Reload → Screenshot Loop and 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:

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 or via your package manager — Windows: winget install OpenJS.NodeJS.LTS; macOS: brew install node; Linux: distro package or nodesource.

Before using the CLIs in a session, ensure the latest global versions are installed:

npm install -g @microsoft/powerbi-report-authoring-cli@latest @microsoft/powerbi-desktop-bridge-cli@latest

Confirm both are on PATH:

powerbi-report-author --version
powerbi-desktop --version

PBIR File Layout

A PBIP project on disk looks like this:

<Report>.pbip                              # Project manifest
├── <Report>.Report/
│   ├── .platform                          # Fabric metadata (type, logicalId)
│   ├── definition.pbir                    # Report → SemanticModel binding
│   ├── definition/
│   │   ├── version.json                   # Format version (e.g. "2.0.0")
│   │   ├── report.json                    # Report-level: themes, settings, resources
│   │   └── pages/
│   │       ├── pages.json                 # Page order + active page name
│   │       └── <pageId>/
│   │           ├── page.json              # Page: displayName, size, type, filters
│   │           └── visuals/
│   │               └── <visualId>/
│   │                   └── visual.json    # Visual: type, position, query, formatting
│   ├── CustomVisuals/                     # Third-party .pbiviz packages
│   └── StaticResources/
│       ├── SharedResources/BaseThemes/    # Built-in base themes
│       └── RegisteredResources/           # User images, custom theme JSON
└── <Report>.SemanticModel/                # OUT OF SCOPE

Key Files

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.

More commands: powerbi-report-author-cli.md.

Validation result handling

Run powerbi-report-author validate <path-to-.Report-dir> after every logical batch of PBIR edits.

• failed / non-zero exit: fix every error before Desktop reload. Desktop may reject or misrender invalid PBIR.
• succeededWithWarnings: review warnings before proceeding. Unknown visual types or theme visual keys usually mean a typo unless the report intentionally uses a custom .pbiviz.
• Diagnostics include file paths and JSON paths. Use them to jump directly to the broken node.
• For large diagnostics, use --pretty for readable output or --out <file> to write the full result to a file.

Visual Capability Guardrails

Use these as pre-edit safety rails. Always confirm exact roles, formatting objects, properties, enum values, and selectors with powerbi-report-author before editing.

Prefer modern visual types

Never create legacy visual types. If repairing an existing legacy visual, migrate to the modern type and rebuild roles/formatting from CLI metadata.

Instance Selectors

Some formatting objects need { id: ... } selectors. Run formatting list-objects and formatting describe-object; follow _selectorHint and the dual-entry pattern in references/formatting.md.

Edit → Validate → Reload → Screenshot Loop

For rendered-output changes, follow this loop. Do not report completion until validation, reload, and screenshot review are clean.

┌──────────────────────────────────────────────────────────┐
│  1. Edit PBIR files                                      │
│  2. Validate           → errors? fix and go to 1         │
│  3. Desktop status     → choose the correct bridge PID   │
│  4. Desktop reload     → error? fix PBIR and go to 1     │
│  5. Screenshot/review  → issues? fix and go to 1         │
│  6. Clean              → report completion               │
└──────────────────────────────────────────────────────────┘

Rules:

• Step 2 — powerbi-report-author validate <path-to-.Report-dir>. Pass the report definition directory (e.g., Sales.Report), not the .pbip file or project root. Fix all errors before reload — invalid PBIR errors will surface in Desktop.
• Steps 3–5 — use powerbi-desktop CLI: status to choose the PID, then reload --pid <pid> for PBIP/PBIR current files and screenshots from the same PID. Then perform the screenshot review below. After status, if the selected instance has hasUnsavedChanges: true, do not reload yet; ask the user to save or discard their Desktop UI changes, rerun status, and continue only once it is false. reload covers report/PBIR changes only. For semantic-model/TMDL changes, use a semantic-model skill or Modeling MCP and reopen the PBIP if changes are not reflected. Exception: Theme JSON files are cache-keyed by name — Desktop may not pick up edits on reload. Either rename the theme file with a random suffix (and update report.json), or close and reopen Desktop.

Desktop CLI commands:

Use powerbi-desktop screenshot <page-id> --pid <pid> when only one PBIR page needs review. reload is supported only for PBIP-backed reports. No powerbi-desktop command accepts --report; use status to select the Desktop instance by PID because the same PBIP can be open in more than one process. Screenshots default to scale 2. Run reload and screenshot operations serially per PID — never in parallel against the same PID, even as a workaround for a slow or retryable error. Read references/powerbi-desktop.md for the complete command reference and troubleshooting workflow.

Common Desktop CLI outcomes:

Screenshot Review

After taking screenshots, perform an independent rendered-output review before reporting completion. Read screenshot-review.md, check layout, data rendering, formatting/theme, slicers, and common screenshot failure modes, then fix PBIR and repeat the loop until clean.

Validation

Run powerbi-report-author validate <path> after every logical batch of PBIR changes. Prefer the .Report directory; the CLI also accepts a .pbip file or a project root containing a single .Report directory. Errors block Desktop reload — fix them first. Review warnings and fix unless there's a clear reason not to.

The validator is an offline preflight covering PBIR structure, JSON/schema validity, cross-file references, IDs/names, visual types, role bindings, filters, formatting objects/properties/enums/selectors, visualContainerObjects, theme registration, layout bounds, and selected Desktop/rendering failure patterns. It does not replace Desktop reload and screenshot review.

Anti-Patterns and Pitfalls

Official Documentation

For Microsoft Learn setup guidance, support constraints, and feature availability, use Power BI report authoring docs.