# Semantic Model Authoring > > - **Type:** Skill - **Install:** `agentstack add skill-microsoft-skills-for-fabric-semantic-model-authoring` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [microsoft](https://github.com/microsoft) - **Source:** https://github.com/microsoft/skills-for-fabric/tree/main/plugins/fabric-skills/skills/semantic-model-authoring ## Install ```sh agentstack add skill-microsoft-skills-for-fabric-semantic-model-authoring ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About > **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. 2. **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. 4. **Load applicable guidelines** - [modeling-guidelines.md](./references/modeling-guidelines.md) always; [direct-lake-guidelines.md](./references/direct-lake-guidelines.md) if Direct Lake. 5. **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. 6. **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). 7. **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; 5. **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](https://github.com/microsoft) - **Source:** [microsoft/skills-for-fabric](https://github.com/microsoft/skills-for-fabric) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-microsoft-skills-for-fabric-semantic-model-authoring - Seller: https://agentstack.voostack.com/s/microsoft - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.