powerbi-custom-visuals
Skill3 starsChanged 7 months agoMITView on GitHub
Build, package, and embed Power BI custom visuals (.pbiviz) into PBIR reports via the powerbi-visuals SDK. Automatically invoke when the user asks to "create a custom visual", "vibe-code a visual", "build a pbiviz", "scaffold a custom visual project", "import a custom visual into the report", "iterate on visual.ts", or mentions powerbi-visuals-tools, pbiviz, capabilities.json, IVisual, or D3-based custom Power BI visuals.
- Installs packages
In this repository58 other files it gives its agents.
- powerbi-audit-tenant-settingsSkill
- powerbi-bpa-rulesSkill
- powerbi-connect-pbidSkill
- powerbi-connectSkill
- powerbi-create-pbi-reportSkill
- powerbi-c-sharp-scriptingSkill
- powerbi-cyber-securitySkill
- powerbi-data-catalog-lineageSkill
- powerbi-data-governance-traceabilitySkill
- powerbi-data-transformationSkill
- powerbi-dax-masterySkill
- powerbi-dax-performanceSkill
- powerbi-daxSkill
- powerbi-deneb-visualsSkill
- powerbi-doctorSkill
- powerbi-duckdb-lakehouseSkill
- powerbi-fabric-appsSkill
- powerbi-fabric-app-templatesSkill
- powerbi-fabric-capacitySkill
- powerbi-fabric-cliSkill
- powerbi-fabric-pipelinesSkill
- powerbi-fabricSkill
- powerbi-lineage-analysisSkill
- powerbi-measure-glossarySkill
- powerbi-medallion-architectureSkill
- powerbi-modelSkill
- powerbi-modifying-theme-jsonSkill
- powerbi-paginated-reportsSkill
- powerbi-pbi-cliSkill
- powerbi-pbip-formatSkill
- powerbi-pbir-cliSkill
- powerbi-pbir-format-enhancedSkill
- powerbi-performance-scaleSkill
- powerbi-power-querySkill
- powerbi-project-managementSkill
- powerbi-python-visualsSkill
- powerbi-refresh-semantic-modelSkill
- powerbi-report-authoringSkill
- powerbi-report-conversionSkill
- powerbi-report-designSkill
- powerbi-reportSkill
- powerbi-report-structureSkill
- powerbi-report-themingSkill
- powerbi-review-reportSkill
- powerbi-review-semantic-modelSkill
- powerbi-r-visualsSkill
- powerbi-security-rlsSkill
- powerbi-source-integrationSkill
- powerbi-spark-livySkill
- powerbi-standardize-naming-conventionsSkill
- powerbi-star-schema-modelingSkill
- powerbi-svg-visualsSkill
- powerbi-te2-cliSkill
- powerbi-te-cliSkill
- powerbi-te-docsSkill
- powerbi-testing-validationSkill
- powerbi-time-series-dataSkill
- powerbi-tmdlSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Always create the visual project as a sibling of the .pbip, never inside the .Report or .SemanticModel folders — Power BI Desktop will …
- Very specific: line 65
Before editing src/visual.ts, lock in two things:
- Very specific: line 84
Caps: if 5 turns pass with no progress on tsc --noEmit errors, stop and ask the user.
- Distinctive: line 90
Only install packages from this short list without explicit user approval:
≈ “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.
Files
Authoring Power BI custom visuals end-to-end
Author a TypeScript Power BI custom visual, package it as .pbiviz, and embed it in a PBIR report so Power BI Desktop loads it on open. Three CLI commands plus the powerbi-visuals-tools SDK do the work; this skill drives Claude through the iteration loop.
Toolchain
| Tool | Role |
pbiviz (powerbi-visuals-tools) | Scaffolds, type-checks, packages |
pbi-agent visual import-custom | Copies .pbiviz into RegisteredResources/, registers in report.json |
pbi-agent visual list-custom | Shows what's currently registered (embedded + public) |
pbi-agent visual remove-custom | Removes registration + on-disk .pbiviz |
First-run setup (with user consent)
Confirm the user is on a machine that can run Node before installing anything.
node --version # need 18+ ; if missing, ask before installing
npm --version
npm install -g powerbi-visuals-tools
pbiviz --versionPin SDK packages to known-good versions inside the visual project:
powerbi-visuals-toolsmatching the global pbivizpowerbi-visuals-apimatching theapiVersioninpbiviz.json
Scaffold
Always create the visual project as a sibling of the .pbip, never inside the .Report or .SemanticModel folders — Power BI Desktop will reject contaminated PBIR folders.
MyProject.pbip
MyProject.Report/
MyProject.SemanticModel/
mygaugevisual/ ← scaffolded herepbiviz new mygaugevisual
cd mygaugevisual
npm installNaming constraint: pbiviz new rejects names with anything other than letters and digits. Strip hyphens and underscores from any user-provided name before running it (my-gauge-v1 → mygaugev1).
Fill required pbiviz.json metadata
pbiviz package strict-validates author.name, author.email, visual.description, and visual.supportUrl. The fresh scaffold leaves them blank, so the first package call will fail on metadata before any code runs. Populate them up-front:
author.name/author.email— derive fromgit config user.name/user.email(no extra prompt to the user)visual.description— derived from the spec from the plan-then-code stepvisual.supportUrl— placeholder URL is fine; real value required only at AppSource publish
Plan-then-code (fresh scaffold only)
Before editing src/visual.ts, lock in two things:
- Data roles + capabilities — what fields does the user drop into the visual? Edit
capabilities.json. - Render approach — D3, Canvas, plain DOM, or SVG? Pick one and don't switch mid-iteration.
Skip the planning step on subsequent edits — go straight to the inner loop.
Inner loop (iterate)
Every change cycle:
npx tsc --noEmit # fast type check; fix errors before packaging
pbiviz package # produces dist/<name>.pbiviz
pbi-agent visual import-custom dist/<name>.pbiviz --replaceThen reload the .pbip in Power BI Desktop to see the result.
Caps: if 5 turns pass with no progress on tsc --noEmit errors, stop and ask the user. Detect oscillation (same error reappearing after a "fix") and break out.
Cache invalidation: Power BI Desktop caches custom visuals by GUID + version. The --replace flag rewrites the registration, but Desktop sometimes still serves the cached bundle. Bump the patch version in pbiviz.json between iterations to force a reload — pbiviz_bump_patch() in powerbi_agent.visual does this if you need to script it. Skip the bump if the user has set a non-semver version (treat as user-managed).
npm allowlist
Only install packages from this short list without explicit user approval:
d3,d3-*(visualization primitives)lodash(utility)date-fns(date formatting)powerbi-visuals-utils-*(official Microsoft visual utilities)
For anything else: surface package name + version + reason + bundle-size estimate and wait for explicit approval. Custom visuals ship every dependency to the browser; bundle bloat is a real cost.
Embedding into the report
pbi-agent visual import-custom dist/mygaugevisual.pbiviz
pbi-agent visual list-customEmbedded entries land in:
<.Report>/StaticResources/RegisteredResources/<name>.<guid>.pbiviz<.Report>/definition/report.json→customVisuals+resourcePackages
To swap an iteration in place, pass --replace. To uninstall, pbi-agent visual remove-custom <guid-or-name>.
Publishing to AppSource
Out of scope for this skill. The pbiviz package output is what you submit to the AppSource publish flow, but the registration step lives outside this CLI.
Troubleshooting
| Symptom | Likely cause |
tsc --noEmit clean but pbiviz package fails | metadata missing in pbiviz.json (see above) |
| Visual loads but renders nothing | check the browser console in Desktop's report view; usually a capabilities.json data-role mismatch |
| Visual won't update after re-import | Desktop cache — bump patch version, close + reopen .pbip |
import-custom errors not a valid zip archive | pbiviz package step didn't succeed; rebuild |
import-custom errors already registered | pass --replace, or remove-custom first |
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
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.

