Agent Skills + MCP：构建智能Azure文档助手（附源码）

引言

由 Anthropic 开放的 Claude Agent Skills 无疑是当下最火的 Agentic 技术。各大 AI 开发助理厂商纷纷跟进，你可以用 Claude Code Agent SDK 或其他厂商的 SDK 实现这一能力，也可以直接在 AI 开发助理软件里使用。它本质上是一个开放标准——本文正是基于这个思想，参考 Skills 文档自主实现该能力。此外，本文还将用实际例子阐明 Agent Skills 与 MCP 的区别，以及它们如何配合发挥合力。

一句话总结：这个 Agent 用实例证明了 Agent Skills 可以动态、可重复地作为 LLM 的操作指导。它像一份“说明书”，向大模型注入项目背景、使用注意、规范、方式等特定场景上下文。本 Agent 通过 Skills 教会大模型在遇到文档查询问题时，直接使用 Microsoft Learn MCP 获取答案，甚至省去了 RAG 的繁重工作。

• Agent Skills 文档：https://agentskills.io
• 代码库：https://github.com/tianputao/AzureDoc_Agent_with_Skills_MCP

此 Agent 主要结合了三项技术来构建智能 Azure 文档助手，无需复杂的 RAG 处理：

• Microsoft Agent Framework (MAF) – 企业级 Agent 编排框架
• Agent Skills – 模块化、可发现的能力系统
• Model Context Protocol (MCP) – 标准化工具集成协议

最终实现了一个可扩展的智能 Agent，能够理解用户意图、动态激活相关技能，并利用合适的工具提供准确的文档帮助。

架构概览

系统架构

完整的系统架构整合了前端、后端、Skills 系统和 MCP 服务器，提供智能文档帮助。

渐进式披露设计

Skills 的核心架构原则是渐进式披露（Progressive Disclosure），在三个层次上实现：

关键洞察：SKILL.md 作为工具使用指南

关键设计决策：我们不是有条件地将工具传递给 Agent，而是在初始化时注册所有 MCP 工具，让 SKILL.md 内容指导使用哪些工具。

这样带来的好处：

• 多个 MCP 服务器可以在一个系统中共存
• 不同的技能指导不同的工具使用
• 轻松添加新技能和 MCP 集成
• 完全分离工具可用性与工具选择

实机演示

组件深入解析

1. Microsoft Agent Framework 集成

MAF 提供企业级 Agent 编排能力。

使用的关键特性：

• 通过 run_stream() 流式响应
• 多轮对话的线程管理
• 通过 MCPStreamableHTTPTool 集成工具

2. Agent Skills 系统

Agent Skills 遵循 agentskills.io 标准，并加入了一个自定义增强：基于 LLM 的技能匹配。

通过 LLM 语义识别问题

# ✅ 解决方案：语言无关、理解意图
matched_skill = await llm_matcher.match_skills(
    user_query="我想了解Cosmos DB的分区机制",
    available_skills=skills
)
# → 匹配：microsoft-docs

优势：

• 支持任何语言或表达方式
• 理解意图，而不仅仅是关键词
• 无需手动维护关键词
• 关键词匹配作为回退，增强鲁棒性

查询处理流程

整个查询处理过程如下序列图所示：

用户查询：“给我Azure Functions的Python代码示例”

步骤 1：LLM 技能匹配

可用技能：
  - microsoft-docs: "查询官方文档..."
  - microsoft-code-reference: "查找代码示例和 API 参考..."

LLM 分析：
  用户想要：代码示例
  最佳匹配：microsoft-code-reference ✓

步骤 2：渐进式披露

加载完整的 SKILL.md：

  ## 工具
  | 工具 | 用途 |
  |------|------|
  | microsoft_code_sample_search | 查找可工作的代码示例 |

  ## 何时使用
  - 用户请求代码示例
  - 需要 API 参考示例
  - 需要 SDK 使用模式

步骤 3：SKILL.md 注入

context_message = f"""
{SKILL.md 内容}

用户问题：给我Azure Functions的Python代码示例
"""
stream = agent.run_stream(context_message)

步骤 4：Agent 工具选择

Agent 读取 SKILL.md，理解：

• “用户想要代码示例”
• “我应该使用 microsoft_code_sample_search”
• 执行工具 → 返回结果

结论

本项目展示了如何通过结合以下技术构建生产级智能 Agent：

• Microsoft Agent Framework 提供强大的编排能力
• Agent Skills 提供模块化能力管理
• MCP 提供标准化工具集成
• 基于 LLM 的智能 匹配技能

资源

• Microsoft Agent Framework：https://learn.microsoft.com/en-us/agent-framework/
• Agent Skills Standard：https://agentskills.io
• Microsoft Learn MCP Server：https://github.com/MicrosoftDocs/mcp/tree/main
• Model Context Protocol：https://modelcontextprotocol.io/
• microsoft-docs-Skills：https://github.com/MicrosoftDocs/mcp/blob/main/skills/microsoft-docs/SKILL.md
• microsoft-code-reference-Skills：https://github.com/MicrosoftDocs/mcp/blob/main/skills/microsoft-code-reference/SKILL.md

更多关于 Agent 开发与 MCP 的实战讨论，欢迎访问云栈社区。