Powerbi Custom Visuals
Developmentpowerbi-custom-visualsPowerbi Custom Visuals is an Agent Skill for development published in the data-goblin/power-bi-agentic-development repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Power BI custom visual (.pbiviz) development with the pbiviz toolchain and its MCP server. Automatically invoke when the user mentions "custom visual", "pbiviz", "develop a Power BI visual", "powerbi-visuals-tools", "IVisual", "capabilities.json", "visual formatting model", "visual certification", "publish a visual to AppSource", or asks to scaffold, build, debug, package, certify, or publish a .pbiviz developer visual.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/data-goblin/power-bi-agentic-development/blob/HEAD/plugins/custom-visuals/skills/powerbi-custom-visuals/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/powerbi-custom-visuals, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Power BI Custom Visuals (pbiviz)
Build distributable Power BI developer visuals: TypeScript/D3 visuals packaged
as a .pbiviz file, written against the powerbi-visuals-api and built with the
pbiviz CLI (powerbi-visuals-tools). This skill covers the full loop: scaffold,
develop, live-preview, package, certify, and publish.
Pick the right tool first
This plugin holds five visual approaches. Choose before building:
deneb-visuals: no-code Vega / Vega-Lite specs inside a report; no packaging, no TypeScript
python-visuals: matplotlib / seaborn script visuals (static image, computes at render)
r-visuals: ggplot2 script visuals (static image); R's stats ecosystem
svg-visuals: SVG drawn by a DAX measure (ImageUrl); inline in tables/cards, no visual sandbox
powerbi-custom-visuals (this skill): a real .pbiviz developer visual, reusable across
reports and shareable on AppSource; full interactivity, formatting pane, certification
Reach for this skill when the need is a reusable, interactive, distributable visual with its own formatting pane. For a one-off chart in a single report, a sibling skill is usually faster and lighter.
Prerequisites
- Node.js 20.19 or later (the
powerbi-visuals-toolsengine minimum) pbivizCLI: run vianpx -y powerbi-visuals-tools <command>, or install it globally- Developer mode for live preview: enable the developer visual in Power BI Desktop, or turn on developer mode in the Power BI service
Core workflow
- Scaffold:
pbiviz new <VisualName>creates the project (src/visual.ts,capabilities.json,pbiviz.json,tsconfig.json,package.json,style/,assets/) - Implement the visual class in
src/visual.ts. Implement theIVisualinterface; the class name must equalvisualClassNameinpbiviz.json. Core methods:constructor(set up DOM and services),update(render on data/size/settings change),getFormattingModel(populate the format pane),destroy(cleanup) - Declare data and formatting in
capabilities.json:dataRoles(the field wells),dataViewMappings(how roles map to the dataView), andobjects(format-pane properties) - Build the formatting model with
powerbi-visuals-utils-formattingmodel(FormattingSettingsService, cards, slices). A card name matches acapabilities.jsonobject; a slice name matches a property - Live-preview:
pbiviz start, then add the developer visual to a report and iterate against real data - Package:
pbiviz packageproduces the.pbivizunderdist/; import it into a report
Full command flags, the project layout, the IVisual lifecycle, and formatting-model
patterns are in references/pbiviz-toolchain.md.
Use the bundled pbiviz MCP server
This plugin ships a .mcp.json that starts the pbiviz MCP server
(npx -y powerbi-visuals-tools mcp). It grounds development in current, correct API
usage instead of guessed code. Prefer its tools while building:
get_available_apis: look up data, formatting, interaction, and utility APIs with examples
get_best_practices: API-version management, performance, security, accessibility, testing
add_feature: list features available to add (bookmarks, tooltips, drill-down, selection, localization)
implement_feature: step-by-step instructions, code templates, and config changes for a feature
list_visual_info: extract a project's GUID, version, author, data roles, dependencies
check_vulnerabilities: scan dependencies and source for risky patterns (eval, innerHTML)
prepare_certification: verify required files, configuration, capabilities, and assets pre-submission
Setup, client config, and per-tool detail are in references/mcp-server.md.
Certify and publish
Certification unlocks export to PowerPoint and email subscriptions, and signals a
reviewed visual. Key gates: a lowercase certification branch matching the package,
eslint-plugin-powerbi-visuals passing, no eval/fetch/XMLHttpRequest, a clean
npm audit, and the latest API. Audit with pbiviz package --certification-audit.
Publishing goes through Partner Center to AppSource. R-based visuals cannot be certified.
Requirements and the submission flow are in references/certification-publishing.md.
Learn from shipped visuals
Microsoft publishes the full source of official and certified visuals. Start from the
tutorials (circlecard, sampleBarChart) and read a production visual close to the
target (gantt, sankey, sunburst, timeline, ChicletSlicer) for real patterns.
A curated list with what each one teaches is in references/community-examples.md.
Additional resources
Reference files
references/pbiviz-toolchain.md... CLI commands, project structure, IVisual lifecycle, capabilities.json, formatting model, key npm packagesreferences/mcp-server.md... the bundled pbiviz MCP: setup and its toolsreferences/certification-publishing.md... certification requirements and AppSource publishingreferences/community-examples.md... official and certified example visuals worth reading
Examples
examples/vscode-mcp.json... standalone.vscode/mcp.jsonfor a visual project outside this pluginexamples/capabilities-objects.json... acapabilities.jsonobjectsblock wired to a formatting card