Agent Skills¶

fabric-dw ships two Claude Code Agent Skills that orchestrate multi-step administration workflows on top of the MCP server.

Skill	Trigger phrases	What it does
`query-optimizer`	"optimize this query", "why is my query slow", "analyze execution plan", "missing statistics", "fix clustering"	Captures the estimated execution plan, inspects query insights history, audits statistics, examines clustering, and proposes or applies optimizations
`dbt-setup`	"set up dbt", "scaffold a dbt project", "create dbt profile", "generate dbt sources"	Generates a complete dbt-fabric scaffold (profiles, project, column-rich sources, requirements) and writes it to disk

Both skills require the fabric-dw MCP server to be configured in your AI client.

Install via Claude Code Plugin¶

The recommended installation path for Claude Code users is the fabric-dw plugin. Skills are installed from GitHub without cloning the repo and are namespaced as /fabric-dw:query-optimizer and /fabric-dw:dbt-setup.

Add the following to your .claude/settings.json (project-scoped) or ~/.claude/settings.json (personal):

{
  "extraKnownMarketplaces": {
    "fabric-dw": {
      "source": { "source": "github", "repo": "sdebruyn/fabric-dw-mcp-cli" }
    }
  },
  "enabledPlugins": {
    "fabric-dw@fabric-dw": true
  }
}

After saving, the skills are available as slash commands:

/fabric-dw:query-optimizer
/fabric-dw:dbt-setup

Version caching

The plugin version is pinned in .claude-plugin/plugin.json. If a new release changes skill content, bump the plugin version to force cached copies to update.

Install as raw SKILL.md files¶

If you are using a different AI assistant, the Claude API directly, or any tool that supports the SKILL.md format but not the Claude Code plugin mechanism, download or reference the raw skill files:

query-optimizer: https://raw.githubusercontent.com/sdebruyn/fabric-dw-mcp-cli/main/skills/query-optimizer/SKILL.md
dbt-setup: https://raw.githubusercontent.com/sdebruyn/fabric-dw-mcp-cli/main/skills/dbt-setup/SKILL.md

Place each file at one of the Claude Code personal or project skill paths:

Path	Scope
`~/.claude/skills/<name>/SKILL.md`	Personal — applies to all projects
`.claude/skills/<name>/SKILL.md`	Project-scoped — committed to repo

For example, to install query-optimizer at project scope:

mkdir -p .claude/skills/query-optimizer
curl -fsSL https://raw.githubusercontent.com/sdebruyn/fabric-dw-mcp-cli/main/skills/query-optimizer/SKILL.md \
  -o .claude/skills/query-optimizer/SKILL.md

Skill reference¶

query-optimizer¶

Performs a structured query performance analysis on a Fabric Data Warehouse:

Captures the estimated execution plan via get_query_plan (no query execution)
Parses the SHOWPLAN_XML for costly operators, residual predicates, and implicit type conversions
Inspects query insights history via list_request_history and list_long_running_queries
Audits statistics per referenced table with list_statistics and show_statistics
Fetches column metadata (types, nullability, identity, computed) via get_table_columns
Reads current data-clustering columns via get_cluster_columns (DW-only; skipped for SQL Analytics Endpoints)
Reports findings and recommendations; optionally applies statistics changes (create_statistics / update_statistics) and re-clustering (set_cluster_columns) after explicit user confirmation

To visualize the execution plan, use the CLI (pass the warehouse name as the first positional argument and the query via -q):

fdw sql plan <warehouse> -q "<query>" --format html -o plan.html   # writes self-contained HTML file; open plan.html in any browser
fdw sql plan <workspace>/<warehouse> -q "<query>" --format svg -o plan.svg   # renders SVG via system dot binary (requires Graphviz)

--format html requires -o/--output and writes a file — it does not open the browser automatically.

dbt-setup¶

Bootstraps a dbt-fabric project for a Fabric Data Warehouse:

Resolves the warehouse connection string via get_warehouse
Lists schemas and tables with list_schemas and list_tables to confirm connectivity
Generates all scaffold files with generate_dbt_profile using with_sources=true — the tool performs a bulk column fetch and emits a models/staging/_sources.yml with columns: blocks (name and formatted data_type) for every table, ready for dbt contract enforcement
Writes profiles.yml, dbt_project.yml, models/staging/_sources.yml, requirements.txt, and .gitignore to disk; confirms before overwriting existing files
Provides next steps: pip install -r requirements.txt, dbt debug, dbt run