Semantic Model Authoring

> Update Check — ONCE PER SESSION (mandatory) > The first time this skill is used in a session, run the check-updates skill before proceeding. > - GitHub Copilot CLI / VS Code: invoke the check-updates skill. > - Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version. > - Skip if the check was already performed earlier in this session.

> 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 > 3. Always consider the [Tool selection priority](#tool-selection-priority) when choosing which tool to use for each operation. Do not default to TMDL edits or az rest if MCP is available and connected to the target model.

Power BI Semantic Model Authoring — CLI Skill

Workflow Selector

Use this decision tree to route to the correct workflow based on user intent:

| User wants to... | Workflow | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Create a semantic model from scratch | [Create new semantic model](#workflow-create-new-semantic-model) | | Add/edit semantic model objects (e.g. measures, tables, columns, relationships) | [Modify an Existing Model](#workflow-modify-an-existing-model) | | Write or refactor DAX code | [Modify an Existing Model](#workflow-modify-an-existing-model) | | Improve DAX query or measure performance | [Optimize DAX Performance](#workflow-optimize-dax-performance) | | Analyze semantic model against best practices | [Analyze Best Practices](#workflow-analyze-best-practices) | | Prepare a semantic model for AI consumption (Copilot / Data Agents) | [Semantic Model AI Readiness](#workflow-semantic-model-ai-readiness) | | Deploy a model to a Fabric workspace | [Deploy to Fabric](#workflow-deploy-to-fabric) | | Refresh a semantic model | [Refresh Semantic Model](#workflow-refresh-semantic-model) | | Configure data sources, parameters, or permissions | [Manage Semantic Model in Fabric](#workflow-manage-semantic-model-in-fabric) | | Bind a semantic model to a Fabric connection (or unbind) | [Bind Semantic Model to a Connection](#workflow-bind-semantic-model-to-a-connection) | | Export / Get semantic model definition as PBIP | [Export to PBIP](#workflow-export-to-pbip) |

Table of Contents

Load these references on demand when a workflow step requires them. Do not load all at once.

| Topic | Reference | When to load | | -------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Modeling Best Practices | [modeling-guidelines.md](./references/modeling-guidelines.md) | Before creating or editing any model | | Naming Conventions | [naming-conventions.md](./references/naming-conventions.md) | When naming or renaming tables, columns, measures | | Direct Lake Modeling | [direct-lake-guidelines.md](./references/direct-lake-guidelines.md) | When model connects to OneLake | | TMDL Editing | [tmdl-guidelines.md](./references/tmdl-guidelines.md) | Before generating or editing any TMDL file | | PBIP Projects | [pbip.md](./references/pbip.md) | When working with PBIP folders | | DAX Language | [dax-guidelines.md](./references/dax-guidelines.md) | When writing or reviewing any DAX code | | DAX Queries & Metadata Discovery | [semantic-model-consumption](../semantic-model-consumption/SKILL.md) | Read-only DAX queries; use for post-creation validation | | DAX Performance Decision Guide | [dax-perf-decision-guide.md](./references/dax-perf-decision-guide.md) | Start here when optimizing DAX | | DAX Performance Pattern Catalog | [dax-perf-patterns.md](./references/dax-perf-patterns.md) | Load on demand after the decision guide identifies candidate patterns | | Semantic Model AI Readiness | [semantic-model-ai-readiness.md](./references/semantic-model-ai-readiness.md) | When preparing a model for Copilot or Data Agents | | Semantic Model REST API | [semantic-model-rest-api.md](./references/semantic-model-rest-api.md) | When using az rest for TMDL CRUD, refresh, parameters, permissions, or property retrieval | | Connection Binding | [connection-binding.md](./references/connection-binding.md) | When binding/unbinding a semantic model to a Fabric data connection (gateway, cloud, VNet, automatic, none) | | Finding Workspaces/Items | [COMMON-CLI.md](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) | When resolving workspace/item IDs | | Fabric Control-Plane API | [COMMON-CLI.md](../../common/COMMON-CLI.md#fabric-control-plane-api-via-az-rest) | When using az rest patterns, LRO, pagination | | Authentication | [COMMON-CLI.md](../../common/COMMON-CLI.md#authentication-recipes) | When authenticating with az login | | Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) | Wrong audience = 401; read before any auth issue | | Core Control-Plane REST APIs | [COMMON-CORE.md § Core Control-Plane REST APIs](../../common/COMMON-CORE.md#core-control-plane-rest-apis) | Includes pagination, LRO polling, and rate-limiting patterns | | Definition Envelope | [ITEM-DEFINITIONS-CORE.md](../../common/ITEM-DEFINITIONS-CORE.md#semanticmodel) | When building TMDL definition payloads | | Examples | [Examples](#examples) | Reference end-to-end walkthroughs. |

---

Tool Selection Priority

Priority order (highest first):

1. Tier 1 — powerbi-modeling-mcp MCP is registered -> Use MCP for authoring (new or edit) operations against the model from any source: Power BI Desktop, Fabric workspace, or local PBIP folder. MCP is the most reliable and full-featured way to edit semantic models, with immediate effect on the live model and no risk of TMDL desync.

Important: In case of dynamic search tools is available (e.g. tool_search_tool_regex) search for an available MCP server matching the pattern powerbi-modeling-mcp.

This includes BOTH writes AND reads/inspection.

• To inspect or verify changes -> use the corresponding MCP operations (List / Get).
• Anti-pattern: opening, view-ing, glob-ing or otherwise reading TMDL files (*.tmdl) while MCP is connected. The MCP-loaded model is the source of truth - the on-disk TMDL is stale. The only exceptions is when the user explicitly asks to work with the TMDL files.

1. Tier 2 — MCP not registered + PBIP folder or Fabric workspace -> Edit TMDL files directly. Load [tmdl-guidelines.md](./references/tmdl-guidelines.md) and [pbip.md](./references/pbip.md). When the source is a Fabric workspace, use az rest to round-trip the TMDL (load [semantic-model-rest-api.md](./references/semantic-model-rest-api.md)): getDefinition -> edit TMDL locally -> updateDefinition.

Fallback — none of the above available (e.g., Power BI Desktop with no PBIP and no MCP) -> STOP. The agent cannot author the model in this configuration. Instruct the user to either (a) install and register the powerbi-modeling-mcp MCP server, or (b) save the PBIX as a PBIP project, then restart the workflow.

> All workflows below are tool-agnostic. Workflow steps describe the intent (connect, create, edit, save, deploy, refresh). The tool used to perform each step is determined here. Always select the highest-priority tool available for the current environment; do not mix tools when a higher-priority option works. Some workflows OVERRIDE this default priority, always check the workflow's own tool-selection rules before defaulting to Tier 1.

Connecting to a Semantic Model

A semantic model can live in three locations. Resolve the connection per [Tool Selection Priority](#tool-selection-priority):

• Power BI Desktop: Locate the running Power BI Desktop instance and connect to its local model.
• Fabric workspace: First, find the workspace and semantic model using the [Finding Workspaces and Items](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) pattern: list workspaces to resolve the workspace ID by name, then list items of type SemanticModel in that workspace to resolve the model ID by name. Then connect to the model (live) or export its TMDL definition for local editing.
• PBIP project: Connect to the [Name].SemanticModel/definition folder. Load [pbip.md](./references/pbip.md) to understand the PBIP folder structure - only load the [Name].SemanticModel/definition folder that includes the TMDL code.

Saving Changes to a Semantic Model

How changes are persisted depends on where the model lives and which tool tier (per [Tool Selection Priority](#tool-selection-priority)) is in use:

Live connection (Tier 1 - MCP against Desktop or Fabric workspace):

• Changes are applied immediately as each operation executes against the live model. No explicit save step is needed.
• PBIP project (live via MCP): Serialize the model back to the [Name].SemanticModel/definition folder at the end of the session. If the PBIP folder does not exist yet, follow [Export to PBIP](#workflow-export-to-pbip) to create the full structure first.

Local TMDL editing (Tier 2 - direct file edits or az rest round-trip):

• PBIP project: Changes are already written to the TMDL files during editing. No additional save step is needed.
• Fabric workspace: Changes were made to local TMDL files exported from the service. Re-deploy the model (load [semantic-model-rest-api.md](./references/semantic-model-rest-api.md) for the updateDefinition flow) to push changes back to the workspace.

---

Workflow: Create new Semantic Model

When this applies: User asks to create a new semantic model from scratch.

Steps:

1. Gather requirements - interview the user until both reach a shared understanding of: purpose of the model, data source connection details and schemas, and key business entities/facts. If data source information is not available, STOP and use ask_user. Do not guess or fabricate.
2. Determine storage mode - data source is Fabric OneLake -> Direct Lake; otherwise default to Import. Only use DirectQuery when the user explicitly asks for it.
3. Design star schema - identify fact and dimension tables and relationship keys.

• If fact table includes date field(s), create a separate date dimension table and link it to the fact with a relationship. If not explicitly requested, use PowerQuery/M partition instead of DAX calculated table.

1. Load applicable guidelines - [modeling-guidelines.md](./references/modeling-guidelines.md) always; [direct-lake-guidelines.md](./references/direct-lake-guidelines.md) if Direct Lake.
2. Build - create an empty database (compatibility level 1702+), then for each table follow the execution order from [Modify an Existing Model](#workflow-modify-an-existing-model) (partitions -> columns -> relationships -> measures). Storage-mode specifics:

• Import / DirectQuery - create M parameters for the data source (Server, Database, ...) and reference them in partition M code; ensure proper dataType and sourceColumn mapping on columns.
• Direct Lake - create a shared named expression for the Direct Lake connection using the AzureStorage.DataLake connector; use EntityPartitionSource with directLake mode mapped to the lakehouse table columns.

1. Deploy or save - Fabric workspace available -> [Deploy to Fabric](#workflow-deploy-to-fabric); otherwise -> [Export to PBIP](#workflow-export-to-pbip). See [Saving Changes to a Semantic Model](#saving-changes-to-a-semantic-model).
2. Validate - run [Validation Checklist](#validation-checklist).

---

Workflow: Modify an Existing Model

When this applies: User asks to add/edit/remove measures, tables, columns, relationships, write DAX code, refactor with UDFs, or edit TMDL directly.

Steps:

1. Connect & discover - per [Connecting to a Semantic Model](#connecting-to-a-semantic-model). List tables, relationships, existing measures, and identify storage mode (it dictates which guidelines apply).
2. Load applicable guidelines - [modeling-guidelines.md](./references/modeling-guidelines.md) always; [direct-lake-guidelines.md](./references/direct-lake-guidelines.md) if Direct Lake; [tmdl-guidelines.md](./references/tmdl-guidelines.md) when editing TMDL directly; [dax-guidelines.md](./references/dax-guidelines.md) for any DAX changes (includes UDF refactoring).
3. Plan changes - identify exactly what to add, modify, or remove. Check for naming conflicts and duplicates.
4. Execute in correct order:

• Adding tables - partitions -> columns -> relationships -> measures.
• Adding relationships - ensure key columns exist on both sides with matching data types;
• Adding measures - verify referenced columns/tables exist;

1. Save & validate - per [Saving Changes to a Semantic Model](#saving-changes-to-a-semantic-model) and [Validation Checklist](#validation-checklist).

---

Workflow: Optimize DAX Performance

When this applies: User asks to improve DAX query performance, diagnose slow measures, or optimize calculations.

> Hard requirement: Requires a trace-capable client (MCP preferred))

Load [dax-perf-decision-guide.md](./references/dax-perf-decision-guide.md) first and follow the framework defined there. Load [dax-perf-patterns.md](./references/dax-perf-patterns.md) only when applying candidate optimization patterns.

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills-for-fabric
• License: MIT

Install and usage instructions live in the source repository linked above.