From pbi-squire
Analyze, create, and modify Power BI projects with intelligent assistance. Diagnose calculation issues, create new measures and visuals, and deploy changes with validation. Uses Microsoft's Power BI Modeling MCP for live semantic model editing when available, with automatic fallback to file-based TMDL manipulation. Supports PBIP projects and Power BI Desktop.
npx claudepluginhub cn-dataworks/pbi-squire-plugin --plugin pbi-squireThis skill uses the workspace's default tool permissions.
Complete Power BI development assistant that orchestrates specialized agents for DAX calculations, M code transformations, and report design. Handles semantic model changes (measures, tables, columns), data transformations (Power Query/M code), and report-side changes (PBIR visuals, layouts).
assets/analysis_report_template.mddeveloper-features.mdreferences/anonymization-patterns.mdreferences/best-practices.mdreferences/command-parameters.mdreferences/common_transformations.mdreferences/dax_common_patterns.mdreferences/interaction_patterns.mdreferences/m_best_practices.mdreferences/m_pattern_discovery.mdreferences/orchestration-pattern.mdreferences/pbir_visual_structure.mdreferences/powerbi-design-standards.mdreferences/project_comparison_guide.mdreferences/project_structure_validation.mdreferences/query_folding_guide.mdreferences/tmdl_partition_structure.mdreferences/tool-fallback-pattern.mdreferences/translation-guidelines.mdreferences/update-info.mdGenerates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Complete Power BI development assistant that orchestrates specialized agents for DAX calculations, M code transformations, and report design. Handles semantic model changes (measures, tables, columns), data transformations (Power Query/M code), and report-side changes (PBIR visuals, layouts).
Key Capabilities:
Architecture:
Tell me what you need help with. I'll route to the appropriate workflow:
| You say... | I'll do... |
|---|---|
| "Fix this measure" / "Something is broken" | EVALUATE - diagnose and plan fixes |
| "Create a YoY growth measure" | CREATE_ARTIFACT - design new DAX artifacts |
| "Filter this table in Power Query" | DATA_PREP - M code transformations |
| "Explain what this dashboard does" | SUMMARIZE - document in business language |
| "Apply the changes" | IMPLEMENT - execute the planned changes |
| "Compare these two projects" | MERGE - diff and merge projects |
| "Set up data anonymization" | SETUP_ANONYMIZATION - mask sensitive columns |
| "Help me with Power BI" | I'll ask clarifying questions first |
Not sure what you need? Just describe your situation - I'll ask clarifying questions to understand your goal before starting any workflow.
Common clarification questions I might ask:
Trigger Keywords:
Trigger Actions:
File Patterns:
*.pbip, *.pbix, *.tmdl, *.bim*/.SemanticModel/**, */.Report/**Before executing any workflow, perform these checks in order:
Purpose: Detect whether Power BI Modeling MCP is available for live validation.
How to check:
MCP Status affects workflow behavior:
| MCP Status | Reading/Analysis | Writing/Editing | Validation |
|---|---|---|---|
| Available | ✅ Full features | ✅ Full features | ✅ Live DAX validation |
| Not Available | ✅ Full features | ⚠️ Works (no validation) | ⚠️ Structural only |
If MCP is NOT available and workflow involves writing:
┌──────────────────────────────────────────────────────────────────────────┐
│ ⚠️ MCP NOT DETECTED - Limited Validation Mode │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ Power BI Modeling MCP is not configured for this session. │
│ │
│ What this means: │
│ • Reading and analyzing TMDL/PBIR files: ✅ Works normally │
│ • Creating/editing DAX code: ⚠️ Works but WITHOUT live validation │
│ • Syntax errors will only be caught when you open in Power BI Desktop │
│ │
│ To enable live validation: │
│ 1. Install Power BI Modeling MCP (VS Code extension) │
│ 2. Open Power BI Desktop with your model │
│ 3. Restart Claude Code │
│ │
│ Options: │
│ [P] Proceed without validation (I'll verify in Power BI Desktop) │
│ [C] Cancel and set up MCP first │
└──────────────────────────────────────────────────────────────────────────┘
For read-only workflows (SUMMARIZE, VERSION_CHECK): Proceed without warning since MCP is not needed.
For write workflows (EVALUATE, CREATE_ARTIFACT, IMPLEMENT): Show the warning above and let user decide.
After determining MCP status, always display the operating mode to the user:
Operating Mode: LIVE MODE (MCP connected)
→ DAX validation, data sampling, and live queries available
Operating Mode: FILE MODE (no MCP)
→ Reading/writing TMDL files directly, no live validation
This ensures the user knows what capabilities are available for the session. Display this BEFORE proceeding to any workflow.
Purpose: Auto-configure the project on first skill invocation. No manual bootstrap needed for Analyst Edition.
Check for setup indicators in the current project directory:
.claude/pbi-squire.jsonCLAUDE.md with plugin referenceIf BOTH exist → Continue to Step 0
If EITHER missing → Inline Setup Flow
When configuration is missing, automatically guide the user through setup inline:
Search the current working directory for Power BI projects:
# Find .pbip files within 2 levels
find . -maxdepth 2 -name "*.pbip" -type f 2>/dev/null
Based on the number of projects found:
| Projects Found | Mode | Action |
|---|---|---|
| 0 | N/A | Ask user for project path |
| 1 | single | Auto-configure for that project |
| 2+ | shared | Ask if shared repository |
For 0 projects found:
┌─────────────────────────────────────────────────────────────────────┐
│ FIRST-TIME SETUP │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ No Power BI projects (.pbip) found in the current directory. │
│ │
│ Please provide the path to your Power BI project folder: │
│ │
│ Example: C:\Projects\SalesReport │
│ │
└─────────────────────────────────────────────────────────────────────┘
For 1 project found (auto-configure as single):
┌─────────────────────────────────────────────────────────────────────┐
│ FIRST-TIME SETUP │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Found Power BI project: │
│ • SalesReport/SalesReport.pbip │
│ │
│ Configuring PBI Squire for this project... │
│ │
└─────────────────────────────────────────────────────────────────────┘
For 2+ projects found (ask about shared mode):
┌─────────────────────────────────────────────────────────────────────┐
│ FIRST-TIME SETUP │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Found 3 Power BI projects in this folder: │
│ • SalesReport/SalesReport.pbip │
│ • SalesOverview/SalesOverview.pbip │
│ • SalesKPIs/SalesKPIs.pbip │
│ │
│ Configure as a shared repository where all these projects use │
│ the same PBI Squire settings? │
│ │
│ [Y] Yes - shared settings for all (Recommended) │
│ [N] No - configure each project separately │
│ │
└─────────────────────────────────────────────────────────────────────┘
This step MUST complete before creating config files. Do NOT auto-select a default. Wait for the user's explicit answer.
┌─────────────────────────────────────────────────────────────────────┐
│ DATA SENSITIVITY │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Should PBI Squire require data anonymization before querying │
│ data via MCP? │
│ │
│ Select YES if: │
│ • Data contains PII, financial, or healthcare information │
│ • Your organization prohibits using real data with AI models │
│ • Compliance policies require data masking │
│ │
│ [Y] Yes - require anonymization setup before data queries │
│ [N] No - proceed without masking requirements │
│ │
│ ⚠️ You must choose one — there is no default. │
│ │
└─────────────────────────────────────────────────────────────────────┘
Create the following files inline (no bootstrap script needed):
.claude/pbi-squire.json - Skill configuration:
{
"projectPath": "<detected-or-provided-path>",
"dataSensitiveMode": <value-from-step-3>,
"mode": "single",
"projectOverrides": {}
}
CRITICAL: The
dataSensitiveModevalue MUST reflect the user's answer from Step 3. Never default tofalse. If Step 3 has not been completed, do NOT create this file.
For shared repositories:
{
"projectPath": "<current-directory>",
"dataSensitiveMode": <value-from-step-3>,
"mode": "shared",
"projectOverrides": {}
}
.claude/settings.json - Permissions (if doesn't exist):
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Edit",
"Write",
"Bash(python *)",
"Bash(git *)"
]
}
}
CLAUDE.md - Add plugin reference (append if exists, create if not):
## PBI Squire Plugin
This project uses the PBI Squire plugin for DAX/M code analysis.
Power BI projects are located at: `<project-path>`
.claude/tools/pbi-squire/version.txt - Version tracking:
tools/developer/version.txtAfter inline setup, check if this is Developer Edition:
Check if skills/pbi-squire/developer-features.md exists in the plugin directory
If Developer Edition, check for Python tools:
test -f ".claude/tools/pbi-squire/tmdl_format_validator.py" && echo "TOOLS_AVAILABLE" || echo "TOOLS_MISSING"
If Python tools missing, show informational message but DO NOT block:
┌─────────────────────────────────────────────────────────────────────┐
│ ⚠️ PYTHON TOOLS NOT INSTALLED │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Developer Edition detected, but Python analysis tools are not │
│ installed. Using Claude-native fallback (slightly slower). │
│ │
│ For faster performance, run bootstrap to install Python tools: │
│ │
│ Windows: │
│ & "$HOME\.claude\plugins\custom\pbi-squire\tools\bootstrap.ps1" │
│ │
│ macOS/Linux: │
│ bash "$HOME/.claude/plugins/custom/pbi-squire/tools/bootstrap.sh" │
│ │
│ Continuing with Claude-native validation... │
│ │
└─────────────────────────────────────────────────────────────────────┘
Continue with workflow - do not require user to re-run command
Key Principle: Setup happens inline on first invocation. The user never needs to run a separate bootstrap step for Analyst Edition. Developer Edition can use bootstrap for Python tools, but works without them via fallback.
Why Setup Matters: Without configuration:
Check for .claude/pbi-squire.json in the project directory:
{
"projectPath": "C:/Projects/SalesReport",
"dataSensitiveMode": true
}
projectPath:
dataSensitiveMode:
true → Enforce anonymization check before any MCP data queries (Step 2 is required)false → Proceed without anonymization checks (Step 2 can be skipped)Purpose: Immediately detect when user references a .pbix file and recommend conversion BEFORE any analysis begins.
Check the user's provided path:
.pbix (case-insensitive), this is a binary PBIX fileExtract project name: Remove .pbix extension from filename (e.g., SalesReport.pbix → SalesReport)
Display this message IMMEDIATELY as the first response:
╔═══════════════════════════════════════════════════════════════════════════╗
║ 📦 PBIX FILE DETECTED - CONVERSION REQUIRED ║
╠═══════════════════════════════════════════════════════════════════════════╣
║ ║
║ You've pointed to a .pbix file: ║
║ <user-provided-path> ║
║ ║
║ PBIX is a compressed binary format that significantly limits analysis. ║
║ To get full visibility into your DAX, M code, and visuals, you need ║
║ to convert to the Power BI Project (.pbip) format. ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
┌─────────────────────────────────────────────────────────────────────────┐
│ ⚠️ IMPORTANT: Each PBIP project needs its own folder! │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ When you save a PBIP project, Power BI creates MULTIPLE files: │
│ │
│ <project-name>/ ← Container folder (you create) │
│ ├── <project-name>.pbip ← Project file │
│ ├── <project-name>.SemanticModel/ ← Data model folder │
│ └── <project-name>.Report/ ← Report folder │
│ │
│ Without a container folder, these files mix with other projects! │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Would you like me to create the project folder for you?
[Y] Yes, create: <configured-projects-folder>/<project-name>/
Then I'll guide you through the Save As steps.
[N] No, I'll handle it myself
(Make sure to create a folder first, then Save As PBIP inside it)
[E] Explain extraction options (DAX-only, limited analysis)
Variable Substitutions:
<user-provided-path>: The exact path the user provided<configured-projects-folder>: Read from .claude/pbi-squire.json → projectPath
projectPath is null: Use "a short path like C:\PBI or D:\Projects"<project-name>: Extract from the .pbix filename (without extension)If user selects [Y] (Create folder for me):
Create the folder using Bash:
mkdir -p "<configured-projects-folder>/<project-name>"
Display success message with Save As instructions:
✅ Folder created: <configured-projects-folder>/<project-name>/
Now complete the conversion in Power BI Desktop:
─────────────────────────────────────────────────
1. Open Power BI Desktop
2. File → Open → Select: <user-provided-pbix-path>
3. File → Save As → Power BI Project (.pbip)
4. Navigate to: <configured-projects-folder>/<project-name>/
5. Click Save (use the default filename)
When you're done, let me know and I'll analyze the project at:
<configured-projects-folder>/<project-name>
Wait for user confirmation, then continue to Step 1 with the new path
If user selects [N] (I'll handle it myself):
If user selects [E] (Explain extraction options):
Why Each Project Needs Its Own Folder:
Why This Step is First:
Read config to determine mode:
.claude/pbi-squire.jsonmode field: "single" or "shared"When mode: "single":
projectPath directlyWhen mode: "shared":
projectPathprojectOverrides┌─────────────────────────────────────────────────────────────────────┐
│ 📁 Repository: C:/Projects/Analytics │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Found 4 Power BI projects: │
│ │
│ [1] HR-Dashboard ⚠️ data masking required │
│ [2] Sales-Report │
│ [3] Marketing-Overview │
│ [4] Finance-Summary │
│ │
│ Which project? (1-4 or project name): │
│ │
└─────────────────────────────────────────────────────────────────────┘
projectOverrides["<project-name>"] existsdataSensitiveMode may be overridden per-projectExample config with overrides:
{
"projectPath": "C:/Projects/Analytics",
"dataSensitiveMode": false,
"mode": "shared",
"projectOverrides": {
"HR-Dashboard": {
"dataSensitiveMode": true
}
}
}
When "HR-Dashboard" is selected, dataSensitiveMode becomes true for that session.
When the user provides a folder path directly (not from config):
*.pbip files in the target folderFound N Power BI projects:
1. ProjectA/ProjectA.pbip
2. ProjectB/ProjectB.pbip
Which project would you like to work with?
After selecting a specific project, check for anonymization configuration:
Look for .anonymization/config.json inside the project folder
ProjectA/.anonymization/config.jsonParentFolder/.anonymization/config.jsonIf config exists: Verify DataMode parameter is set appropriately before sampling data
If config does NOT exist and workflow will query data:
⚠️ This project doesn't have anonymization configured.
MCP queries may expose sensitive data.
Options:
1. Set up anonymization first (/setup-data-anonymization --project "<path>")
2. Proceed anyway (data is not sensitive)
3. Work in file-only mode (no data queries)
These operations don't expose data and can proceed without anonymization:
dax_query_operations.validate() — syntax check onlymeasure_operations.list() — metadata onlytable_operations.list() — metadata onlyUse when: User reports something is broken, incorrect, or not working as expected.
Process:
Output: findings.md with diagnosed issues and proposed fixes
Next step: "implement the changes" to apply fixes
Use when: User wants to add new code-based artifacts (DAX measures, calculated columns, tables).
Note: For visuals, use CREATE_PAGE workflow. Visuals require layout coordinates, field bindings, and PBIR file generation which this workflow doesn't handle.
Process:
Output: findings.md with new artifact specifications (DAX/M code)
Next step: "implement the changes" to create artifacts
Can also be called in embedded mode by CREATE_PAGE workflow to generate measures as part of page creation.
Use when: User wants a complete new report page with multiple visuals.
Pro Feature: This workflow requires the Developer Edition. Core users can create individual measures with CREATE_ARTIFACT, then manually add visuals in Power BI Desktop.
Process:
Output: findings.md with measures + visual specifications + PBIR files
Next step: "implement the changes" to create the page
Use when: User wants to modify data transformations, Power Query logic, table filtering, column operations, or any ETL changes.
Trigger phrases:
Process:
Key considerations:
references/query_folding_guide.md)Option 1 (Recommended): Filter in M code
✓ Simple and straightforward
✓ Maintains query folding
✗ Loads all data then filters
Option 2: Filter at source (SQL WHERE)
✓ Better performance for large datasets
✗ More complex to maintain
Query folding rules (quick reference):
Output: Updated TMDL partition files + validation results
References:
references/query_folding_guide.md - Complete folding rulesreferences/common_transformations.md - M code pattern libraryreferences/m_best_practices.md - Style guidereferences/tmdl_partition_structure.md - TMDL formattingUse when: User has reviewed findings and wants to apply proposed changes.
Prerequisites: Must have findings.md from previous workflow
Process:
Output: Updated project files + validation results
Use when: User wants to understand what an existing dashboard does, explain metrics to stakeholders, or create documentation.
Trigger phrases:
Process:
Translation principles:
Example translations:
| Technical | Business |
|---|---|
CALCULATE(SUM(...), ALL(...)) | Total ignoring current filters |
SAMEPERIODLASTYEAR | Same period last year |
| Line chart with Date on X-axis | Line chart tracking trends over time |
Output: dashboard_analysis.md with:
Output example structure:
# Dashboard Analysis: Sales Performance
## Executive Summary
This dashboard provides sales leadership with visibility into revenue
performance, regional comparisons, and year-over-year growth trends.
## Pages
### 1. Executive Summary
**Purpose:** High-level KPIs for executive stakeholders
**Visuals:**
- **Total Revenue Card** - Current total revenue ($2.4M)
- **YoY Growth Card** - Year-over-year change (+12.5%)
**Filters:** Year, Quarter
### 2. Regional Breakdown
[...]
## Metrics Glossary
### Total Sales
- **Definition:** Sum of all invoice amounts excluding returns
- **Dependencies:** Sales Amount column
- **Logic:** Filters out cancelled orders
### YoY Growth %
- **Definition:** Percentage change vs same period last year
- **Dependencies:** Total Sales, Prior Year Sales
References:
references/translation-guidelines.md - Technical to business languagereferences/visual_types.md - How to describe each visual typereferences/dax_common_patterns.md - Common DAX pattern translationsreferences/interaction_patterns.md - Interaction behavior descriptionsassets/analysis_report_template.md - Full report templateUse when: User wants to compare or combine two Power BI projects.
Process:
Output: Merged project + merge report
Use when: User asks about plugin version, updates, tier (Pro/Free), or installation status.
Trigger phrases:
Process:
Read Plugin Metadata
.claude-plugin/plugin.json from plugin installation directoryversion, repositoryskills/pbi-squire/developer-features.md exists (Developer) or not (Analyst)Read Project Version (if bootstrapped)
.claude/tools/pbi-squire/version.txt in current projectReport Status
┌──────────────────────────────────────────────────┐
│ PBI Squire Status │
├──────────────────────────────────────────────────┤
│ Plugin (global): │
│ Version: 1.3.0 (Developer Edition) │
│ Location: ~/.claude/plugins/custom/powerbi-* │
├──────────────────────────────────────────────────┤
│ Project (local): │
│ Version: 1.2.0 ← Update available │
│ Location: .claude/tools/pbi-squire/ │
├──────────────────────────────────────────────────┤
│ Update Instructions: │
│ Plugin: cd ~/.claude/plugins/custom/power* │
│ git pull │
│ Project: Run bootstrap.ps1 from project dir │
└──────────────────────────────────────────────────┘
If Update Requested
Output: Version status report with update instructions if needed
Plugin metadata location: $HOME/.claude/plugins/custom/pbi-squire/.claude-plugin/plugin.json
See also: references/update-info.md for detailed update procedures
Use when: User wants to set up data anonymization to protect sensitive information before using MCP queries.
Trigger phrases:
Process:
.anonymization/config.json and update skill configWhat gets created:
DataMode parameter (toggle between "Real" and "Anonymized")Masking strategies:
| Strategy | Example | Use For |
|---|---|---|
| Sequential numbering | "Customer 1, Customer 2" | Names |
| Fake domain | "user1@example.com" | Emails |
| Partial mask | "XXX-XX-1234" | SSN, Tax ID |
| Fake prefix | "(555) 555-1234" | Phone numbers |
| Scale factor | Original * 0.8-1.2 | Financial amounts |
| Date offset | Original +/- 30 days | Birth dates |
| Placeholder | "[Content redacted]" | Free text |
Output:
.anonymization/config.json with configuration.claude/pbi-squire.json with dataSensitiveMode: trueInvokes: powerbi-anonymization-setup agent
References:
references/anonymization-patterns.md - Detection patterns and M code templatesAfter setup: To test, open Power BI Desktop → Transform Data → Manage Parameters → Change DataMode to "Anonymized".
This skill uses Claude Code's leaf subagent pattern for context isolation and parallel execution. The main thread (skill layer) orchestrates workflows and spawns specialized subagents directly.
IMPORTANT: Claude Code subagents cannot spawn other subagents. Therefore:
Task()Execute workflows in the MAIN THREAD (do NOT delegate to an orchestrator subagent):
Load the appropriate workflow file based on trigger:
workflows/evaluate-pbi-project-file.mdworkflows/create-pbi-artifact-spec.mdworkflows/implement-deploy-test-pbi-project-file.mdworkflows/merge-powerbi-projects.mdExecute phases directly in main thread:
findings.mdTask(powerbi-code-locator), Task(powerbi-visual-locator)Task(powerbi-dashboard-update-planner)Task(powerbi-dax-specialist), Task(powerbi-mcode-specialist)Task(powerbi-dax-review-agent), Task(powerbi-pbir-validator)Subagents communicate via findings.md:
Reference: See references/orchestration-pattern.md for detailed routing logic and quality gates
The orchestrator delegates to specialized agents based on artifact type:
powerbi-dax-specialist)Handles: Measures, calculated columns, calculation groups, KPIs
Expertise:
powerbi-mcode-specialist)Handles: Partitions (table M queries), named expressions, ETL
Expertise:
| Agent | Purpose | Output Section |
|---|---|---|
powerbi-code-locator | Find DAX/M/TMDL code | Section 1.A |
powerbi-visual-locator | Find PBIR visuals | Section 1.B |
powerbi-data-context-agent | Query live data via XMLA | Section 1.C |
powerbi-pattern-discovery | Find similar artifacts | Section 1.D |
| Agent | Purpose | Output Section |
|---|---|---|
powerbi-dashboard-update-planner | Design calculation & visual changes | Section 2 |
powerbi-artifact-decomposer | Break complex requests into artifacts | Section 1.0 |
powerbi-data-understanding-agent | Build specifications via Q&A | Section 1.2 |
| Agent | Purpose | Output Section |
|---|---|---|
powerbi-dax-review-agent | Validate DAX syntax & best practices | Section 2.5 |
powerbi-pbir-validator | Validate PBIR visual.json structure | Section 2.6 |
power-bi-verification | Generate test cases & impact analysis | Section 3 |
| Agent | Purpose | Output Section |
|---|---|---|
powerbi-code-implementer-apply | Apply TMDL changes | Section 4.A |
powerbi-visual-implementer-apply | Apply PBIR changes | Section 4.B |
| Agent | Purpose | Output |
|---|---|---|
powerbi-anonymization-setup | Set up data masking for sensitive columns | .anonymization/config.json |
These agents are available only in the Developer Edition:
| Agent | Purpose |
|---|---|
powerbi-playwright-tester | Browser automation testing |
powerbi-ux-reviewer | Design critique from screenshots |
powerbi-qa-inspector | DOM inspection for deployment errors |
All agents are leaf subagents (they do not spawn other subagents):
agents/
├── core/ # Core agents (all editions)
│ ├── powerbi-code-locator.md # Investigation
│ ├── powerbi-visual-locator.md # Investigation
│ ├── powerbi-dashboard-update-planner.md # Planning (writes specs)
│ ├── powerbi-dax-specialist.md # Code generation
│ ├── powerbi-mcode-specialist.md # Code generation
│ ├── powerbi-dax-review-agent.md # Validation
│ ├── powerbi-pbir-validator.md # Validation
│ └── ... (additional leaf agents)
│
└── pro/ # Pro agents (Developer Edition only)
├── powerbi-playwright-tester.md
├── powerbi-ux-reviewer.md
└── powerbi-qa-inspector.md
Note: Orchestration logic is in references/orchestration-pattern.md and executed by the main thread, not a subagent.
The skill maintains session state in .claude/state.json:
Tasks use the Task Blackboard pattern where specialists read/write to designated sections of findings.md.
The skill auto-configures on first invocation. No separate bootstrap step required for Analyst Edition.
Analyst Edition: Auto-configures inline (no Python required) Developer Edition: Auto-configures inline + optional bootstrap for Python tools
When you first invoke the skill in a new project, it will:
See "Step -1: Project Setup Check" for the detailed flow.
Use bootstrap for:
# Windows
& "$HOME\.claude\plugins\custom\pbi-squire\tools\bootstrap.ps1"
# macOS/Linux
bash "$HOME/.claude/plugins/custom/pbi-squire/tools/bootstrap.sh"
What gets created (Analyst Edition):
YourProject/
├── CLAUDE.md ← Project instructions
├── .claude/
│ ├── pbi-squire.json ← Skill configuration
│ ├── settings.json ← Permissions
│ ├── tasks/ ← Task findings files
│ ├── tools/
│ │ └── pbi-squire/
│ │ └── version.txt ← Version tracking only
│ └── helpers/
│ └── pbi-squire/
│ └── pbi-url-filter-encoder.md
└── YourProject.pbip
Additional files for Developer Edition:
YourProject/
├── .claude/
│ ├── tools/
│ │ └── pbi-squire/ ← Python tools (Pro only)
│ │ ├── token_analyzer.py
│ │ ├── tmdl_format_validator.py
│ │ └── ... (13 Python scripts)
│ └── powerbi-design-standards.md ← Design template (Pro only)
└── ...
The bootstrap script tracks versions to manage updates:
| Command | Purpose |
|---|---|
bootstrap.ps1 | Install/update tools if needed |
bootstrap.ps1 -CheckOnly | Check if update available (exit code 1 = update needed) |
bootstrap.ps1 -Force | Force reinstall even if current |
To update this skill to the latest version:
Step 1: Pull latest plugin code
cd "$HOME\.claude\plugins\custom\pbi-squire"
git pull
Step 2: Update project tools (run from your project directory)
cd "C:\path\to\your\project"
& "$HOME\.claude\plugins\custom\pbi-squire\tools\bootstrap.ps1"
Quick check if update is available:
& "$HOME\.claude\plugins\custom\pbi-squire\tools\bootstrap.ps1" -CheckOnly
# Exit code 1 = update available, 0 = current
Plugin location: $HOME\.claude\plugins\custom\pbi-squire\
| File | Behavior | Safe to Customize? |
|---|---|---|
CLAUDE.md | Prompts before appending | ✅ Yes |
.claude/settings.json | Skips if exists | ✅ Yes |
.claude/pbi-squire.json | Skips if exists | ✅ Yes |
.claude/tasks/* | Not touched | ✅ Yes |
.claude/tools/pbi-squire/* | Overwritten | ❌ No (plugin-managed) |
.claude/helpers/pbi-squire/* | Overwritten | ❌ No (plugin-managed) |
.claude/tools/*.py (root) | Not touched | ✅ Yes (your scripts) |
.claude/helpers/* (root) | Not touched | ✅ Yes (your files) |
Important: Only the pbi-squire/ subfolders are plugin-managed. Your own scripts in .claude/tools/ or .claude/helpers/ are safe.
To customize behavior, edit:
.claude/settings.json - Permissions and Claude Code settings.claude/pbi-squire.json - Skill configurationCLAUDE.md - Project-specific instructionsAll changes pass through validation before completion:
| Validator | What it Checks | Blocking |
|---|---|---|
| DAX Review | Syntax, semantics, best practices | Yes (errors) |
| PBIR Validator | JSON structure, config integrity | Yes (errors) |
| MCP Validation | Live syntax check (MCP mode only) | Yes (errors) |
Warnings are reported but don't block implementation.
The plugin uses a tool-first fallback pattern to provide optimal performance for Pro users while ensuring Core users can still accomplish all tasks.
| Check | Developer Edition | Analyst Edition |
|---|---|---|
| Python tools available? | Yes (via bootstrap) | No |
| Execution speed | Fast (milliseconds) | Slower (uses LLM) |
| Token cost | Lower | Higher |
| Functionality | Same | Same |
Agents check for tool availability before executing:
# Example check
test -f ".claude/tools/tmdl_format_validator.py" && echo "TOOL_AVAILABLE" || echo "TOOL_NOT_AVAILABLE"
| Task | Pro Tool | Core Fallback |
|---|---|---|
| TMDL validation | tmdl_format_validator.py | Claude validates against tmdl_partition_structure.md |
| Visual editing | pbir_visual_editor.py | Claude uses Edit tool on visual.json |
| M code editing | m_partition_editor.py | Claude uses Edit tool with tab handling |
| Pattern analysis | m_pattern_analyzer.py | Claude reads and analyzes TMDL |
| Anonymization | sensitive_column_detector.py | Claude uses anonymization-patterns.md |
See references/tool-fallback-pattern.md for complete documentation.
The skill provides structured trace output to show workflow progress, agent invocations, and MCP tool usage.
Workflow Start:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 WORKFLOW: [workflow-name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase Markers:
📋 PHASE [N]: [Phase Name]
└─ [Description of what's happening]
Agent Invocations:
└─ 🤖 [AGENT] [agent-name]
└─ Starting: [brief description]
└─ 🤖 [AGENT] [agent-name] complete
└─ Result: [summary]
MCP Tool Calls:
└─ 🔌 [MCP] [tool-name]
└─ [parameters or context]
└─ ✅ Success: [result summary]
└─ ❌ Error: [error message]
Workflow Complete:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ WORKFLOW COMPLETE: [workflow-name]
└─ Output: [file path or summary]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Icon | Meaning |
|---|---|
| 🚀 | Workflow start |
| 📋 | Phase/step |
| 🤖 | Agent invocation |
| 🔌 | MCP tool call |
| 📂 | File operation |
| 🔍 | Search/discovery/validation |
| ✏️ | Edit/write |
| ✅ | Success |
| ❌ | Error/failure |
| ⚠️ | Warning |
See resources/tracing-conventions.md for complete tracing documentation.
This skill includes reference documentation:
assets/findings_template.mdTemplate for Task Blackboard used by all workflows.
PBIR visual templates with {{PLACEHOLDER}} syntax are maintained in a public repository:
GitHub: https://github.com/cn-dataworks/pbir-visuals/visual-templates/
Template types include:
Templates are fetched via WebFetch from raw.githubusercontent.com.
See assets/visual-templates/README.md for usage and contribution instructions.
references/getting-started.md - Onboarding guide with data masking workflowglossary.md - Technical terms explainedtroubleshooting-faq.md - Common issues and solutionsupdate-info.md - Version management, update procedures, edition detection| Goal | Example Prompt | Workflow |
|---|---|---|
| Fix a problem | "Help me fix the YoY calculation in my Sales dashboard" | EVALUATE |
| Create DAX measure | "Create a margin percentage measure" | CREATE_ARTIFACT |
| Create calculated column | "Add a full name column combining first and last" | CREATE_ARTIFACT |
| Create a visual | "Add a sales KPI card with YoY comparison" | CREATE_PAGE (Developer) |
| Create a page | "Build a regional performance dashboard page" | CREATE_PAGE (Developer) |
| Transform data | "Filter the Customers table to active only" | DATA_PREP |
| Edit M code | "Add a calculated column in Power Query" | DATA_PREP |
| Apply changes | "Implement the changes from findings.md" | IMPLEMENT |
| Understand dashboard | "Summarize this dashboard and explain what it does" | SUMMARIZE |
| Document metrics | "Explain how the Total Sales metric works" | SUMMARIZE |
| Compare projects | "Merge my dev and prod projects" | MERGE |
| Check version | "What version of PBI Squire am I running?" | VERSION_CHECK |
| Anonymize data | "Set up data anonymization for this project" | SETUP_ANONYMIZATION |
| Mask PII | "Hide sensitive columns like names and emails" | SETUP_ANONYMIZATION |
| Design standards | "Set up design guidelines for my dashboard" | SETUP_DESIGN_STANDARDS (Developer) |
| Design review | "Review my dashboard against design guidelines" | QA_LOOP (Developer) |
Note: The following features require the Pro version of this plugin. If
developer-features.mdexists in this skill folder, those additional capabilities are available.
Pro capabilities include:
QA Loop prerequisites:
The QA Loop (/qa-loop-pbi-dashboard) focuses on runtime and deployment errors (grey boxes, crashes, broken visuals), not syntax validation. Code must already be validated before running the QA loop, either:
/implement-deploy-test-pbi-project-file workflow (which validates TMDL/PBIR syntax)Design Standards workflow:
.claude/powerbi-design-standards.md in your project/qa-loop-pbi-dashboard --design-critique to validate against standardsSee developer-features.md for full Pro documentation (Pro version only).