从 Copilot CLI 到 Claude Code、Cursor:skills-for-fabric 多AI编码工具使用全解析(终极指南)
从 Copilot CLI 到 Claude Code、Cursor:skills-for-fabric 多AI编码工具使用全解析(终极指南)
skills-for-fabric 是微软官方的 AI 编码助手技能集合,它让 GitHub Copilot CLI、Claude Code、Cursor 等 AI 编码工具真正"懂" Microsoft Fabric:内置 24 个技能(Skill)与 5 个智能体(Agent),覆盖数据仓库、Lakehouse、Power BI、实时智能等场景的 REST API、查询模式与运维最佳实践。本文用一套"傻瓜式"步骤,带你在不同 AI 工具中完成安装、配置与首次实战。
📦 skills-for-fabric 是什么?为什么值得装?
简单来说:它是 AI 编码工具操作 Microsoft Fabric 的"作业手册 + 工具箱"。
- 技能(Skills):可复用的 AI 指令,告诉 AI 该用什么 API、什么查询模式、什么运维规范。技能文件集中在 skills/ 目录。
- 智能体(Agents):跨工作流编排的"专家角色",如 FabricDataEngineer.agent.md 负责调度涉及 Spark + SQL + KQL 的端到端任务。
- 共享参考(Common):common/ 目录存放各技能共用的 API 参考与笔记开发规范,避免内容重复漂移。
- MCP 服务器:让 AI 直接调用 Fabric 的实时数据接口,详见下文 MCP 配置章节。
整体采用 Agents → Skills → Common 三层混合架构,这个设计决定了你在任何工具里都能获得一致的行为。两个安装捆绑包按需选择:
| 捆绑包 | 适用场景 |
|---|---|
fabric-skills |
完整 Fabric 技能包:作者(Authoring)、消费(Consumption)、运维(Operations)、迁移与端到端架构 |
powerbi-authoring |
Power BI 语义模型、报表与 PBIP 工作流的专业创作包 |
🎯 技能清单一览:这些任务都能交给 AI
| 工作负载 | 对应技能文件 | 典型任务 |
|---|---|---|
| Fabric 数据仓库 | skills/sqldw-cli/SKILL.md | T-SQL 建表、查询、慢查询诊断 |
| Spark / Lakehouse | skills/spark-cli/SKILL.md | Notebook 编写与运行、Spark 作业诊断 |
| 语义模型 | skills/semantic-model-authoring/SKILL.md | DAX 度量值、TMDL 部署 |
| Eventhouse / KQL | skills/eventhouse-cli/SKILL.md | KQL 表管理与实时查询 |
| 报表创作 | skills/powerbi-report-cli/SKILL.md | 报表规划、设计、发布 |
| 目录治理 | skills/onelake-catalog-govern-cli/SKILL.md | OneLake 目录审计与整改 |
| Synapse 迁移 | skills/synapse-migration/SKILL.md | 专用 SQL 池迁移到 Fabric |
更多完整技能说明见 CLAUDE.md 中的工作负载清单。
1️⃣ Copilot CLI 安装:3 条命令 1 分钟上手(官方推荐)
Copilot CLI 插件安装是最省心的路径,只需三步:
# 第一步:添加官方插件市场
/plugin marketplace add microsoft/skills-for-fabric
# 第二步:安装完整 Fabric 技能包
/plugin install fabric-skills@fabric-collection
# 第二步(备选):只装 Power BI 创作包
/plugin install powerbi-authoring@fabric-collection
安装完成后即可更新:
/plugin update fabric-skills@fabric-collection
# 或者一次性更新所有已装插件(在终端执行)
copilot plugin update --all
💡 自动更新技巧:在你的用户设置(~/.copilot/settings.json)中为 fabric-collection 条目加上 "autoUpdate": true,Copilot CLI 就会在每个会话开始时自动刷新技能包,版本信息以 apm.yml 中的 version 字段为准。
2️⃣ Claude Code 安装:插件市场一条命令搞定
Claude Code 同样走插件市场,且自动复用 Azure CLI 登录态认证远程 MCP:
# 添加市场 + 安装技能包
claude plugin marketplace add microsoft/skills-for-fabric
claude plugin install fabric-skills@fabric-collection
# 已有安装则更新
claude plugin update fabric-skills@fabric-collection
# 检查 MCP 服务器连接状态
claude mcp list
两个关键提醒(详见 mcp-setup/README.md):
fabric-collection是第三方市场,需在/plugin→ Marketplaces 中选中它并勾选 Enable auto-update 一次;- 旧的手动 MCP 注册可能覆盖插件配置,若
/mcp里看到失效的旧条目,可在用户确认后移除。
3️⃣ Cursor、Windsurf 与其他工具:克隆仓库即自动生效
如果你不用插件市场,直接把仓库克隆到项目目录,各工具会自动发现对应的根级配置文件:
| AI 工具 | 自动识别的配置文件 |
|---|---|
| Cursor | .cursorrules |
| Windsurf | .windsurfrules |
| Claude Code | CLAUDE.md |
| Codex / Jules / OpenCode | AGENTS.md |
| Gemini CLI | GEMINI.md(通过 @./AGENTS.md 导入,单一维护源) |
git clone https://gitcode.com/gh_mirrors/sk/skills-for-fabric
# 将仓库中的规则文件放入你的 Fabric 项目目录即可被自动识别
这些规则文件内容保持一致:都要求 AI 遵循 Agents → Skills → Common 分层、通过 az login 获取令牌、按意图路由到具体技能——保证跨工具行为一致。
4️⃣ APM 单技能安装:只装你需要的那一个
插件包是整体安装的,但如果你只想启用某一个技能(比如只要 sqldw-cli),用微软官方的 APM(Agent Package Manager)即可精准投放到指定工具:
# 安装 APM CLI(任选其一)
pip install apm-cli
# 只安装 sqldw-cli 技能,并同时投放到 claude 和 cursor
apm install microsoft/skills-for-fabric --skill sqldw-cli --target claude,cursor
几个实用参数:
| 参数 | 作用 |
|---|---|
--skill NAME |
只启用指定技能,可重复传多次 |
--target, -t |
投放目标工具,如 copilot、claude、cursor、codex |
--global, -g |
安装到用户级(~/.agents/skills/)而非当前项目 |
--only apm |
只装技能、不注册 MCP 服务器 |
--dry-run |
只打印安装计划,不实际写入 |
技能会落盘到 .agents/skills/<name>/,并把指向 common/ 共享参考的链接自动重写到 apm_modules/ 的实体副本中,因此单技能安装也保留全部共享参考——这是 apm.yml 将包根目录设为仓库根目录的设计目的。
MCP 服务器配置:把 AI 接到真实的 Fabric 数据
技能提供"怎么做"的指导,MCP 服务器提供"连得上"的实时工具。本仓库声明了 3 个 Fabric MCP 服务器(见 .mcp.json):
| MCP 服务器 | 用途 |
|---|---|
FabricIQ |
自然语言分析 Power BI 报表与语义模型 |
fabric-sqlendpoint |
直接执行 SQL 端点查询(execute_query) |
powerbi-modeling-mcp |
Power BI 建模辅助(stdio 方式经 npx 启动) |
各工具的配置差异:
- Claude Code:插件自带原生 Azure CLI
headersHelper,自动从az login会话取令牌,无需额外 OAuth 应用; - Codex(0.153.4+):在
~/.codex/config.toml中合并 3 个[mcp_servers.*]条目,用http_headers_helper调az account get-access-token; - VS Code:在
.vscode/mcp.json中配置 HTTP 服务器 +promptString令牌输入(VS Code 无 header-helper 机制,需手动粘贴令牌)。
完整配置样例与故障排查见 mcp-setup/README.md。
🔐 认证准备:一次 az login 覆盖所有负载
几乎所有 Fabric 操作都需要 Azure AD 认证,两条命令即可:
az login
az account get-access-token --resource https://api.fabric.microsoft.com
如果还涉及 SQL 连接(Warehouse、Lakehouse SQL 端点),再为 https://database.windows.net 资源取一个令牌。完整示例见 CLAUDE.md。注意:不要将令牌粘贴到聊天或配置文件中,MCP 的 header-helper 会私密消费它。
✨ 首次实战:试试这些现成提示词
仓库内置了可直接使用的提示词示例,安装后在项目目录里对 AI 说同样的话即可:
例如:
"Use Microsoft Fabric skills to design a medallion architecture for NYC taxi data."
AI 会自动按 FabricDataEngineer 智能体的规则把任务拆解到 spark-cli、sqldw-cli 等技能,并遵循 Bronze → Silver → Gold 分层与 Delta Lake 最佳实践。
🩺 更新策略与常见问题速查
| 工具 | 更新方式 |
|---|---|
| Copilot CLI | /plugin update fabric-skills@fabric-collection 或 copilot plugin update --all |
| Claude Code | claude plugin update fabric-skills@fabric-collection,或启用市场的 auto-update |
| Cursor / Windsurf / 手动克隆 | 重新执行宿主工具的插件更新命令,或 git pull |
常见坑:
- MCP 显示连接但调用失败:
claude mcp list退出码 0 不代表工具全部可用,进 Claude 后用/mcp看真实状态; - 旧注册覆盖新插件:失效的旧
FabricIQ条目会在用户确认后删除(claude mcp remove --scope local FabricIQ)再复查; - WSL/容器中令牌失效:Windows 上的登录不会自动带入 WSL,需在客户端实际运行的环境里重新
az login。
总结:选对工具,一句话上手
- 用 Copilot CLI → 直接装
fabric-skills插件,体验最完整; - 用 Claude Code → 装插件并启用 auto-update,MCP 自动复用 Azure 登录;
- 用 Cursor 等其他工具 → 克隆仓库让规则文件自动生效,或用 APM 精准投放单技能;
- 只做 Power BI 创作 → 选
powerbi-authoring包。
项目遵循 MIT 协议,版本迭代记录见 CHANGELOG.md,从入门到迁移,skills-for-fabric 帮你把 Fabric 的复杂操作压缩成一句自然语言。