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

1. 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.
2. Set up/update CLIs → before first use, confirm powerbi-report-author and the global powerbi-desktop command are available; see CLI Setup.
3. Understand the model → use the Semantic Model MCP Server/skill if available, or read TMDL files directly for table/column/measure names
4. 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.
5. Route by intent → use Topic Files and Examples to pick the relevant guide.
6. 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.
7. Check common pitfalls → read Anti-Patterns and Pitfalls before editing or validating when the change touches visuals, bindings, filters, formatting, layout, or Desktop rendering.
8. Validate → run powerbi-report-author validate <path-to-.Report-dir> after every logical batch of PBIR changes; see Validation.
9. 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.
10. Report back → give the user a concise summary of what was done and any issues encountered (major and minor).