BI Agent Superpowers

BI Agent Superpowers is an open-source toolkit that gives AI coding agents practical Power BI Desktop capabilities.

It installs reusable agent skills, configures Microsoft MCP servers, and provides a small CLI called super so Codex, Claude Code, GitHub Copilot, Gemini CLI, and Kilo Code can work with Power BI projects using the same operating contract.

This is not a loose prompt pack. It is a reproducible Power BI agent layer:

• 6 skills for Power BI/project work: session startup, project bootstrap, semantic-model design and audit, DAX authoring and optimization, performance profiling with Tabular Editor 2 / BPA integration, and Power BI Desktop MCP connection.
• 2 Microsoft MCP servers for Power BI Desktop modeling and Microsoft Learn documentation.
• 1 CLI (super) for install, updates, local plugin generation, checks, and regeneration.
• Codex-first skill and MCP installation, plus compatibility adapters for other agents.
• Claude Code plugin artifacts for users who explicitly want that local plugin format.

Status: v5.0.x is the current stable release line. The v5 line standardizes every public slash command under the /bi-* namespace.

Validation baseline: BI Agent Superpowers is developed and stress-tested first in Codex. Other agent adapters are shipped as compatibility targets and may work, but they are not currently tested end-to-end with the same depth unless a release note says otherwise.

Table of Contents

• What It Does
• Install From Terminal
• Ask Your Agent To Install It
• Skills Included
• Quick Demos
• Supported Agents
• MCP Servers
• CLI Reference
• Plugin File Tree
• Requirements
• Updates
• What Ships To npm
• Development
• Project Validation Harness
• Troubleshooting
• FAQ

What It Does

Power BI work with AI agents usually breaks down in predictable places:

1. The agent does not understand the BI project structure.
2. The agent does not know how to connect to Power BI Desktop.
3. The agent invents DAX, PBIR, or setup steps without validating them against real tools.
4. Each agent has different skill and MCP configuration paths.

BI Agent Superpowers fixes that by giving Codex the primary tested Power BI workflow and exposing the same operating contract to compatible agents:

• project context through reusable skills;
• Power BI Desktop access through the Microsoft Power BI Modeling MCP;
• current Microsoft documentation through the Microsoft Learn MCP;
• optional Claude Code plugin artifacts for local project work;
• update checks so old plugin bundles do not silently stay stale.

The goal is simple: open a Power BI project, ask your agent for help, and have the agent know what tools, files, prerequisites, and guardrails apply.

Install From Terminal

All Supported Agents

Use this when you want one command path for Codex and the compatibility adapters for Claude Code, GitHub Copilot, Gemini CLI, and Kilo Code.

npm install -g @luquimbo/bi-superpowers
super install --all --yes

Restart your agent after installation so it reloads skills and MCP configuration.

Interactive Install

Use this when you want the installer to detect agents and ask where to install.

npm install -g @luquimbo/bi-superpowers
super install

Install For One Agent Only

# Claude Code user-level skills + MCP config
super install --agent claude-code --yes

# GitHub Copilot
super install --agent github-copilot --yes

# Codex
super install --agent codex --yes

# Gemini CLI
super install --agent gemini-cli --yes

# Kilo Code
super install --agent kilo --yes

Claude Code Marketplace Install

If you use Claude Code, the marketplace path is the cleanest install experience for that agent. Claude Code is a compatibility target; Codex remains the primary end-to-end validation baseline.

/plugin marketplace add luquimbo/bi-superpowers
/plugin install bi-superpowers

After that, start a new session and run:

/bi-start

Advanced: Optional Local Claude Code Plugin

This is only for Claude Code users who deliberately want repo-local slash-command plugin files. Codex, GitHub Copilot, Gemini CLI, and Kilo Code should use super install above; do not run super kickoff for those agents.

Inside a Power BI project repo:

super kickoff

This generates project-local Claude Code plugin files:

• .claude-plugin/
• .plugin/
• .mcp.json
• commands/
• skills/
• config.json

Regenerate them later with:

super recharge

Ask Your Agent To Install It

If your agent has terminal access, paste one of these prompts.

Claude Code

Use the marketplace path first:

Install BI Agent Superpowers from the Claude Code marketplace.

Run these Claude Code plugin commands:

/plugin marketplace add luquimbo/bi-superpowers
/plugin install bi-superpowers

After installation, start the plugin with /bi-start and tell me if any restart or reload is needed.

If you also want project-local plugin files in the current repo for Claude Code only:

Set up BI Agent Superpowers for this project as a local Claude Code plugin.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super kickoff

Then verify that .claude-plugin/, .plugin/, .mcp.json, commands/, skills/, and config.json were created in this repo. Do not modify unrelated files.

GitHub Copilot

Set up BI Agent Superpowers for GitHub Copilot on this machine.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super install --agent github-copilot --yes

After it finishes, verify that the GitHub Copilot skills directory and MCP config were updated. Then remind me to restart VS Code or reload Copilot so it picks up the new skills and MCP servers.

Codex

Set up BI Agent Superpowers for Codex on this machine.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super install --agent codex --yes

After it finishes, verify that the shared skills were installed under ~/.agents/skills and that the Codex MCP config was updated. Then summarize the installed skills and MCP servers.

Do not run super kickoff or super mcp-setup for Codex; those commands are only for optional repo-local Claude Code plugin files.

Gemini CLI

Set up BI Agent Superpowers for Gemini CLI on this machine.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super install --agent gemini-cli --yes

After it finishes, verify that ~/.gemini/skills and the Gemini MCP settings were updated. Then tell me to restart Gemini CLI before using the skills.

Kilo Code

Set up BI Agent Superpowers for Kilo Code on this machine.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super install --agent kilo --yes

After it finishes, verify that ~/.kilo/skills and the Kilo MCP settings were updated. Then tell me to restart Kilo Code before using the skills.

Multi-Agent Setup

Set up BI Agent Superpowers for every supported agent installed on this machine.

In the terminal, run:

npm install -g @luquimbo/bi-superpowers
super install --all --yes

After it finishes, summarize which agents were configured, which MCP files were written, and whether any Windows symlink fallback copied files instead of creating symlinks.

Skills Included

bi-start

Session opener. It gives the user a clean starting point, checks whether a newer BI Agent Superpowers version exists, shows the skill menu, and routes the conversation to the right specialist skill.

Use it when:

• you are starting a new session;
• you do not know which skill to invoke;
• you want the agent to check update status before work begins.

bi-kickoff

Project analysis and planning skill. It inspects a BI project, explains what exists, identifies gaps, and creates a sensible plan for the next work cycle.

Use it when:

• opening a Power BI repo for the first time;
• starting a new PBIP project;
• asking an agent to understand project structure before editing.

bi-connect

Power BI Desktop connection skill. It helps the agent connect to the open Power BI Desktop model through the Microsoft Power BI Modeling MCP. Model writes go through MCP; PBIP files are treated as saved/exported version-control snapshots.

Use it when:

• you need to list tables, columns, measures, or relationships;
• you want to execute DAX queries;
• you want the agent to inspect or modify the semantic model through Desktop.
• you want to write or review DAX user-defined functions using current Microsoft Learn syntax and DAXLIB patterns.

Quick Demos

Start A Session

/bi-start

Expected result:

• update check;
• menu of 6 skills;
• environment hints;
• next-step recommendation.

Analyze A Power BI Project

/bi-kickoff
Analyze this Power BI repo. Tell me what exists, what is missing, and what plan we should follow.

Expected result:

• project map;
• risks and missing context;
• recommended implementation path;
• handoff to bi-connect when appropriate.

Connect To Power BI Desktop

/bi-connect
Connect to the model currently open in Power BI Desktop and list tables, measures, columns, and relationships.

Expected result:

• MCP connection check;
• semantic model snapshot;
• actionable diagnostics if Desktop or MCP wiring is not ready.

Write A DAX UDF With DAXLIB As Reference

/bi-connect
Write a reusable DAX UDF for gross margin percentage. Use Microsoft Learn for the current UDF syntax and consult DAXLIB patterns before proposing the function.

Expected result:

• current UDF syntax/preview check;
• existing function inspection when a model is connected;
• DAXLIB-aware pattern selection without vendoring external code by default;
• tested function draft and validation steps.

Supported Agents

| Agent | Skill install path | MCP config path | Primary usage | Validation status | |---|---|---|---|---| | Codex | ~/.agents/skills/ | ~/.codex/config.toml | Natural language with skills and MCPs | Primary end-to-end test baseline | | Claude Code | ~/.claude/skills/ or marketplace plugin | ~/.claude.json | Slash commands and natural language | Compatibility target; not the primary end-to-end QA baseline | | GitHub Copilot | ~/.copilot/skills/ | ~/.copilot/mcp-config.json | Natural language with skills and MCPs | Compatibility target; not the primary end-to-end QA baseline | | Gemini CLI | ~/.gemini/skills/ | ~/.gemini/settings.json | Natural language | Compatibility target; not the primary end-to-end QA baseline | | Kilo Code | ~/.kilo/skills/ | ~/.kilo/mcp_settings.json | Natural language | Compatibility target; not the primary end-to-end QA baseline |

The installer always writes the universal skill copy to ~/.agents/skills/, then links or copies agent-specific skill directories as needed.

MCP Servers

| MCP | Transport | Purpose | |---|---|---| | powerbi-modeling-mcp | local stdio | Connects to Power BI Desktop through XMLA for model inspection, DAX queries, and model operations. | | microsoft-learn | HTTP | Gives the agent access to Microsoft Learn documentation in context. |

You can install these MCPs manually, but super install writes the expected MCP config for each selected agent automatically.

For DAX user-defined functions, bi-connect also points agents at DAXLIB as an upstream reference:

• https://github.com/daxlib/daxlib
• https://docs.daxlib.org/
• https://github.com/daxlib

BI Agent Superpowers does not vendor DAXLIB source code. Agents should consult it as a reference and only import/adapt specific MIT-licensed functions when the user explicitly requests that.

CLI Reference

The package exposes both super and bi-superpowers:

super help
bi-superpowers help

Common commands:

super install          # Install 6 skills + 2 MCPs for selected agents
super kickoff          # Advanced: generate optional local Claude Code plugin files
super recharge         # Regenerate optional local Claude Code plugin artifacts
super powers           # List available skills
super scan             # Compare source skills with generated artifacts
super checkup          # Validate skill content
super validate-projects # Validate repo fixtures + local private project refs
super build-desktop    # Build the Claude Desktop .mcpb extension in the current dir
super build-desktop --output dist
super upgrade          # Update the global CLI and print refresh steps
super help             # Show full CLI help

super mcp-setup is intentionally not part of normal setup. It only refreshes MCP config inside an existing local Claude Code plugin created by super kickoff; it refuses to write repo-local config in arbitrary projects. For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and normal Claude Code user-level installs, use super install --all --yes.

Plugin File Tree

Local Claude Code Plugin

Generated by super kickoff or super recharge:

This tree is optional and Claude Code specific. It is not required for Codex, GitHub Copilot, Gemini CLI, or Kilo Code because those agents use the user-level install created by super install.

project/
├─ .claude-plugin/
│  ├─ plugin.json
│  ├─ marketplace.json
│  └─ skill-manifest.json
├─ .plugin/
│  └─ plugin.json
├─ .mcp.json
├─ commands/
│  ├─ bi-start.md
│  ├─ bi-kickoff.md
│  └─ bi-connect.md
├─ skills/
│  ├─ bi-start/
│  │  ├─ SKILL.md
│  │  └─ scripts/update-check.js
│  ├─ bi-kickoff/
│  │  ├─ SKILL.md
│  │  └─ scripts/update-check.js
│  ├─ bi-connect/
│  │  ├─ SKILL.md
│  │  └─ scripts/update-check.js
└─ config.json

Build Pipeline

flowchart TD
    A["src/content/"] --> B["npm run build:plugin"]
    B --> C["commands/*.md"]
    B --> D["skills/*/SKILL.md"]
    B --> E[".claude-plugin/"]
    B --> F[".plugin/"]
    B --> G[".mcp.json"]
    C --> H["Claude Code slash commands"]
    D --> I["Agent skills"]
    G --> J["Power BI Modeling MCP + Microsoft Learn MCP"]

Requirements

Base Requirements

• Node.js 18 or newer.
• At least one supported AI agent.

For bi-connect

• Windows.
• Power BI Desktop open.
• Power BI Modeling MCP available to the agent.

Updates

Claude Code Marketplace

/plugin update bi-superpowers

npm / CLI Installs

super upgrade
super install --all --yes

If you created a project-local plugin:

cd your-power-bi-project
super recharge

super upgrade intentionally does not run super install or super recharge automatically. User-profile installs and project-local plugins are separate refresh targets.

On Windows, if symlink creation is not available and the installer falls back to copying skills, each re-run mirrors the managed skill directories. Removed or renamed bundled scripts are deleted from the copied install during refresh.

What Ships To npm

The npm package includes:

bin/
.claude-plugin/
.plugin/
.mcp.json
commands/
skills/
src/content/
templates/
desktop-extension/
config.json
config.example.json
README.md
CHANGELOG.md
AGENTS.md
LICENSE
package.json

The npm package does not include:

docs/superpowers/
validation/
validation.local.example.json
validation.local.json
node_modules/
*.test.js
**/.pbi/localSettings.json

templates/ ships canonical reference templates (today: templates/sales/). Each template is a complete PBIP package with AGENTS.md, semantic model, and report definition — used as the canonical "template-as-reference" by all specialist skills, and as the source for the upcoming bi-kickoff "create from template" branch (which will copy templates/<domain>/ into <user-repo>/pbip-files/<projectName>.* with renaming). validation/ is repo-only. It stores sanitized validation descriptors and playbooks for project QA; private project paths live in validation.local.json, which must never be committed.

Development

Install dependencies:

npm install

Regenerate plugin artifacts:

npm run build:plugin

Validate locally:

npm test
npm run lint
npm run format:check
npm pack --dry-run --ignore-scripts

Source of truth:

src/content/

Generated artifacts:

commands/
skills/
.claude-plugin/
.plugin/
.mcp.json

Edit source files first, then regenerate generated outputs.

Project Validation Harness

In a source checkout, the repo can validate BI Agent Superpowers against real Power BI work without committing customer repositories.

Public fixtures live in:

templates/sales/

Sanitized validation metadata lives in:

validation/projects/
validation/cases/

Private local project paths live only in:

validation.local.json

That file is gitignored. Copy validation.local.example.json when you want to map client projects on your own machine.

Run the structural validation:

super validate-projects --project sales-template

Run every descriptor, treating skipped private projects as failures:

super validate-projects --strict

This command is non-destructive. It checks project paths and required files; it does not open Power BI Desktop, edit PBIP files, or copy private repos.

Publishing

Publishing is handled by GitHub Actions. Do not run npm publish locally.

Expected release flow:

npm version patch --no-git-tag-version
npm run build:plugin
npm test
npm run lint
npm run format:check
git add package.json package-lock.json commands/ skills/ .claude-plugin/ .plugin/ .mcp.json
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main --follow-tags

The publish workflow runs on v* tag pushes. Manual dispatch is constrained to an already-tagged release commit on main.

Troubleshooting

super is not found after npm install

Check the global package:

npm list -g @luquimbo/bi-superpowers

Try the long binary name:

bi-superpowers help

If npm's global bin directory is not in PATH, fix PATH or use your package manager's global binary setup instructions.

The Agent Does Not See The Skills

1. Restart the agent.
2. Run super install --all --yes again.
3. Check the relevant skill directory.
4. If using a local Claude Code plugin, run super recharge inside that repo.

Power BI Desktop Does Not Connect

1. Open Power BI Desktop.
2. Open the target .pbix or PBIP project.
3. Confirm the Power BI Modeling MCP is installed.
4. Restart the agent after MCP installation.

pbi-cli-tool Is Missing

Install Python, pipx, and pbi-cli-tool:

python --version
pipx --version
pipx install pbi-cli-tool
pbi --version

FAQ

Does This Replace Power BI Desktop?

No. Power BI Desktop remains the visual and report authoring tool. The plugin helps agents inspect project files and use MCPs for semantic-model work, but PBIP files are treated as version-control snapshots. Agents must not patch .Report/** PBIR JSON, visual.json, bookmarks, slicer/card settings, themes, or report resources directly.

The only report-side exception is template adaptation through the dedicated plugin field-swap/rebind command. Agents must not patch PBIR JSON by hand, even for a "simple measure replacement." The command may write PBIR only for data bindings (projections, prototypeQuery, query refs, field parameters, and sort/filter field references when required), with dry-run, backup, validation, and an explicit source-to-target mapping. It must preserve visual type, layout, formatting, interactions, IDs, theme, and bookmarks. Until that tool exists, report field swaps remain manual Desktop work.

Does It Work Outside Windows?

The CLI and several skills can run outside Windows. Workflows that depend on Power BI Desktop, especially bi-connect, are Windows-first.

Do I Need Claude Code?

No. Codex is the primary development and end-to-end validation baseline for this plugin. Claude Code has a useful compatibility path through marketplace/local plugin artifacts, but it is not the canonical test base unless a release note explicitly says that release was tested there.

Can I Use Only The MCP Servers?

Yes. You can install Microsoft Learn MCP and Power BI Modeling MCP manually. This repo packages them with skills and operational workflows so agents know when and how to use them.

Does This Send Data To A SaaS Backend?

No. The package installs local files, writes local agent config, and uses MCP servers configured on your machine. There is no BI Agent Superpowers SaaS backend.

Contributing

Issues and pull requests are welcome:

• GitHub: https://github.com/luquimbo/bi-superpowers
• Issues: https://github.com/luquimbo/bi-superpowers/issues
• npm: https://www.npmjs.com/package/@luquimbo/bi-superpowers

Before large changes, read:

• AGENTS.md
• ARCHITECTURE.md
• src/content/
• bin/

License

MIT © Lucas Sanchez (@luquimbo)