1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 正式名称 | kql（合集仓库子目录名） | 目录名 |
| 所属合集仓库 | microsoft/skills（微软官方维护，面向 Azure SDK 与 Microsoft Foundry 的 Agent Skills 仓库，收录 175 个技能） | GitHub API + 仓库 README |
| 作者/维护者 | Microsoft 官方 | GitHub 组织账号 |
| 来源链接 | https://github.com/microsoft/skills/tree/main/.github/skills/kql | — |
| 许可证 | MIT（仓库根 LICENSE 文件） | GitHub API |
| 所属合集仓库整体 Stars/Forks | 2,785 / 315（注：该数字属整个 175 技能合集仓库，不代表本技能自身热度，仅供了解所属仓库规模） | GitHub API |
| 该技能自身活跃度 | 该目录下共 9 次实质性提交，来自具名微软工程师；所属仓库近日（2026-07-21）仍有提交，非弃置 | GitHub Commits API（路径限定查询） |
| 最新版本 | 无独立版本号，随仓库整体迭代 | 仓库结构实测 |
| 安装方式 | 见第十章 | 仓库根 README |
2. 功能介绍与亮点
kql 是微软官方编写的 Kusto Query Language（KQL）避坑与进阶指南，教 Agent 写出正确、高效的 KQL 查询——这门语言是 Azure Data Explorer、Microsoft Fabric 实时智能（EventHouse）、Azure Monitor Log Analytics、Microsoft Sentinel 等微软数据服务的原生查询语言。
核心内容：
- 语法陷阱清单：管道式语法基础、查询计划与管理计划（
.show/.create等）的区分、常见报错场景 - 内存安全查询模式：针对超百万行大表给出“先 count、先 where 再 summarize、避免对高基数列 dcount”等规则，并逐条列出
E_LOW_MEMORY_CONDITION、E_RUNAWAY_QUERY两类报错的排查路径 - 窗口函数序列化陷阱：
row_cumsum()、row_number()等函数在乱序数据上产生错误结果的具体案例与修复写法 - 结果规模纪律：专门提示“向量陷阱”——含 1536 维向量列的表哪怕
take 20也可能拖出 600KB 结果，需主动project掉向量列 - 附带 4 份参考文档（进阶模式、探索式查询模板、错误恢复手册、发现型查询），共约 46KB 内容
- 文档提供可直接试跑的公共集群
https://help.kusto.windows.net（Samples 库），读者无需自建 Azure 资源即可验证每条示例
亮点：纯 Markdown 知识型技能，无需任何 SDK 或订阅即可生效；内容明显来自真实生产报错的沉淀（错误码、内存陷阱、序列化坑点都是实战细节），而非泛泛的语法转述。
3. 适用场景
所属分类：数据分析与可视化
适合日常需要写 KQL 查询做日志排查、遥测分析、安全事件调查的用户：使用 Azure Monitor / Log Analytics 做应用监控的开发者，使用 Microsoft Sentinel 做安全事件调查的分析师，以及在 Azure Data Explorer 或 Microsoft Fabric 实时智能上做时序数据探索的数据工程师。不需要预先掌握 KQL 语法，技能本身覆盖了从入门到大表调优的完整台阶。
4. 跨 Agent 兼容性
| Agent | 结论 | 判断依据 |
|---|---|---|
| Claude Code | ⚠️ 需手动放置，但官方给出明确方法 | 仓库主安装向导 npx skills add 面向 GitHub Copilot；但根 README 额外给出 ln -s ../.github/skills .claude/skills 的官方符号链接示例，专门说明如何在 Claude Code 中共用同一份技能目录 |
| Codex | ❓ 未验证 | 已抓取材料未提及针对 Codex 的官方说明，未为此单独搜索 |
| OpenClaw | ❓ 未验证 | 同上 |
| Hermes Agent | ❓ 未验证 | 同上 |
技能本体是不含任何厂商专属运行时依赖的纯 Markdown 文档，理论上手动复制到任意支持 SKILL.md 格式的 Agent 均可读取生效，但以上结论仅基于已抓取材料，未逐一验证。
5. 推荐理由
微软官方出品，把 KQL 常见报错、内存陷阱与序列化坑点整理成可直接复用的避坑指南，减少 Agent 反复试错的成本。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 微软官方出品且所属仓库近日（2026-07-21）仍有提交、持续活跃；但作为 175 技能合集仓库中的一个子目录，其自身独立讨论热度未见于公开渠道，故不套用合集整体星数 |
| 可用性 | 9 | 单文件 SKILL.md 加 4 份参考文档共约 46KB，覆盖入门到大表调优；零 SDK、零订阅、零付费依赖，复制即可生效；所属仓库近日（2026-07-21）仍有提交 |
| 安全性 | 10 | 纯知识型 Markdown 技能，不含任何可执行脚本，不发起网络请求，不涉及凭据 |
| 综合评分 | 9.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行及权限范围 | 无——技能全文为查询语法说明与示例，不含可执行脚本或安装脚本 |
| ② 运行时联网外发数据 | 无——不发起任何网络请求，读者需自行连接自己的 Kusto 集群执行查询 |
| ③ API Key/凭据要求 | 无需任何凭据；文档提供的公共试跑集群 help.kusto.windows.net 面向匿名访问的示例数据集 |
| ④ 可疑指令/Prompt Injection 迹象 | 未发现——全文为 KQL 语法、报错代码与修复示例，未见诱导执行额外操作或外发数据的文字 |
| ⑤ 作者/组织信誉 | Microsoft 官方 GitHub 组织账号，仓库为公司级维护，具名工程师提交 |
| ⑥ License 是否明确 | MIT，仓库根目录明确声明 |
| ⑦ 最近维护时间 | 所属仓库最近一次提交为 2026-07-21；该技能目录自身最近一次提交由具名微软工程师完成 |
7. 跟同类 Skills 相比的优势
| 方案 | 核心定位 | 覆盖范围 | 与 kql 的差异 |
|---|---|---|---|
| kql（本次推荐） | 微软官方出品，Kusto Query Language 避坑与调优指南 | Azure Data Explorer / Fabric 实时智能 / Log Analytics / Sentinel | — |
| elasticsearch-esql（elastic/agent-skills） | Elastic 官方出品，教 Agent 写正确的 ES|QL 查询 | Elasticsearch 生态 | 同为“厂商官方查询语言避坑指南”的定位，但服务的数据平台完全不同，二者互不替代 |
| bigquery-basics（google/skills） | Google 官方出品，面向 Agent 设计的 BigQuery 技能 | Google Cloud BigQuery | 覆盖的是 BigQuery 的查询与权限实践，语法体系（标准 SQL）与 KQL 的管道式语法不同 |
| databricks-core（databricks/databricks-agent-skills） | Databricks 官方出品，打通 CLI 认证与数据平台操作 | Databricks 平台 | 定位偏“平台操作入口”，kql 定位偏“单一查询语言的语法与调优知识”，颗粒度不同 |
差异化核心：这四个技能同属“云厂商官方出品的数据平台专属技能”这一谱系，但各自绑定不同厂商的数据平台与查询语言，彼此不存在替代关系——选择哪一个完全取决于用户实际使用的数据服务。kql 在这组同类项目里的独特价值在于内容颗粒度更细：不只是语法入门，而是把内存溢出、序列化坑点、结果规模控制这类只有大量实战才能沉淀出的细节写成了可直接复用的排错手册。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。其所属的 microsoft/skills 仓库有独立的 Evals & Tests 自动化测试流水线（GitHub Actions 徽章可见），技能改动需通过测试才能合入，属于工程化质量把关，但这属于生产流程信息，不构成对本技能的第三方评价。
9. 其他补充
所属仓库提供在线技能浏览器（Skill Explorer，microsoft.github.io/skills）可一键浏览全部 175 个技能并选择安装；官方博客《Context-Driven Development: Agent Skills for Microsoft Foundry and Azure》介绍了该仓库的设计理念。
10. 安装使用方式
方式一：官方 CLI 向导
npx skills add microsoft/skills运行后从交互列表中勾选 kql 即可安装。
方式二：手动复制或符号链接（推荐用于 Claude Code 等非 Copilot 场景）
git clone https://github.com/microsoft/skills.git
cp -r skills/.github/skills/kql your-project/.claude/skills/
# 或使用符号链接以便随仓库更新同步：
ln -s /path/to/skills/.github/skills/kql your-project/.claude/skills/kql安装后注意事项：
- 技能本身是纯文档，无需安装任何包或 SDK，复制完成即可生效，无需重启宿主 Agent
- 所属仓库体量较大（175 个技能），官方建议按需选用而非整仓库导入，避免上下文稀释
references/目录下的 4 份补充文档不会被自动加载，Agent 会按需读取，无需手动预加载
11. 注意事项
- 仓库官方安装向导与主文档面向 GitHub Copilot CLI / VS Code，对 Codex、OpenClaw、Hermes Agent 未见官方兼容性说明，跨 Agent 使用需自行验证
- 技能内容聚焦 KQL 语言本身的语法与调优，不包含 Azure 资源部署、权限配置等运维内容，需要打通认证与操作入口的用户仍需另配相应工具
- 该技能作为 175 个技能合集仓库中的一个子目录，其自身独立讨论热度未见于公开渠道，热度评估以“官方出品 + 仓库整体活跃”为依据，而非该子目录本身的病毒式传播证据