企业官网建设流程全解析

fastmcp 技能实战：用 SKILL.md 编写可复用的 Code Review 审查清单并通过 MCP 资源对外暴露

【免费下载链接】fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp

导读

本文以仓库 examples/skills/sample_skills/code-review/SKILL.md 为核心，讲解如何编写一份结构清晰、可被 Agent 直接消费的 Code Review 技能定义：包括 YAML frontmatter 元数据、四个维度的审查清单（正确性、可维护性、性能、安全）与反馈沟通原则。同时结合 fastmcp 的 skills provider 源码，说明这类SKILL.md是如何被扫描、解析，并通过skill://资源 URI 暴露给任何 MCP 客户端发现、读取与下载的。读完本文，你将掌握 SKILL.md 的编写规范，并能在自己的 MCP Server 中一键挂载整套技能目录。

一、关联文档定位：一份可被 Agent 消费的技能定义

code-review/SKILL.md位于 examples/skills/sample_skills/ 目录下，是 fastmcp 仓库中「skills 示例」的一部分。它本身不是项目文档，而是一份真实的技能定义文件——正如 examples/skills/README.md 所描述的那样，该示例目录展示了"如何将 Agent 技能（如 Claude Code skills）作为 MCP 资源暴露"。

从目录结构看，每个技能是一个独立文件夹，文件夹名即技能名，内部必须包含一个主文件（默认SKILL.md）：

examples/skills/sample_skills/ ├── pdf-processing/ │ ├── SKILL.md # 主技能文件 │ └── reference.md # 辅助文档 └── code-review/ └── SKILL.md # 主技能文件

code-review/SKILL.md的主题是"指导 Agent 进行彻底的代码审查"，它由两部分组成：frontmatter 元数据（被解析器读取，用于资源描述与清单生成）和审查清单正文（被 Agent 作为操作指南消费）。

二、frontmatter：技能元数据如何被解析

code-review/SKILL.md的开头是一个标准的 YAML frontmatter 块：

--- description: Review code for quality, maintainability, and correctness version: "1.0.0" tags: [code, review, quality] ---

这三个字段分别承担不同职责：

在 fastmcp 源码中，frontmatter 由 fastmcp_slim/fastmcp/server/providers/skills/_common.py 的parse_frontmatter()函数解析。该函数采用"简单 key: value 解析"，支持：

• 去除 BOM 前缀（\ufeff）；
• 通过---界定 frontmatter 起止；
• 解析字符串值（自动剥离单双引号）；
• 解析[a, b, c]形式的列表值（如上面的tags）。

解析后，description会写入SkillInfo数据类（见 skill_provider.py 的_load_skill()），并作为该技能对应skill://资源资源的description字段返回给客户端。

注意：若 frontmatter 中没有description，解析器会退而求其次，从正文第一行非空非#开头的内容（或第一个#标题）中截取前 200 个字符作为描述。因此，为技能编写准确、简洁的description是提升可发现性的关键。

三、审查清单正文：四个维度的完整继承

SKILL.md正文给出了一个可直接照做的审查框架——"When reviewing code, consider:"，从四个维度展开。这一部分是技能被 Agent 执行时的核心操作指南，原文内容如下，需要完整继承：

3.1 Correctness（正确性）

• Does the code do what it's supposed to do?（代码是否做了它该做的事？）
• Are edge cases handled?（边界情况是否被处理？）
• Are there any obvious bugs?（是否存在明显 bug？）

正确性审查是代码审查的第一道关卡，核心是验证"实现是否符合预期行为"。

3.2 Maintainability（可维护性）

• Is the code easy to understand?（代码是否易于理解？）
• Are variable and function names descriptive?（变量与函数命名是否具有描述性？）
• Is there appropriate documentation?（是否有适当的文档？）

可维护性决定了代码的长期成本，命名与文档是最直观的体检指标。

3.3 Performance（性能）

• Are there any obvious performance issues?（是否存在明显的性能问题？）
• Are expensive operations cached when appropriate?（昂贵的操作是否在合适的地方做了缓存？）
• Are database queries efficient?（数据库查询是否高效？）

性能维度强调"显而易见的"问题优先——先关注复杂度明显的热点，而不是过早优化。

3.4 Security（安全）

• Is user input validated?（用户输入是否被验证？）
• Are there any injection vulnerabilities?（是否存在注入漏洞？）
• Are secrets properly managed?（机密信息是否得到妥善管理？）

安全是任何代码审查不可妥协的底线，输入校验、注入防护与密钥管理是三大高频风险点。

四、反馈沟通原则：Giving Feedback

除了审查清单，原文档还专门定义了给出反馈的方式，这决定了技能输出是否真正可执行、可被开发者接受：

• Be specific and actionable（具体且可操作）
• Explainwhysomething should change（解释为什么应该改）
• Suggest alternatives, don't just criticize（提出替代方案，而不只是批评）
• Acknowledge good work too（也要肯定做得好的部分）

这四个原则组合起来，实质上定义了"高质量代码评审反馈"的模板：定位具体问题 → 说明原因 → 给出替代方案 → 认可优点。当 Agent 基于该技能执行审查时，输出应符合此格式，而不是笼统地给出"代码不好"之类的空泛结论。

五、从文件到 MCP 资源：SKILL.md 如何被挂载与消费

编写好code-review/SKILL.md之后，关键问题是如何让它被 MCP 客户端发现。fastmcp 的 skills provider 系统提供了一个两层架构（见 fastmcp_slim/fastmcp/server/providers/skills/init.py）：

• SkillProvider：处理单个技能文件夹，将其中文件暴露为资源；
• SkillsDirectoryProvider：扫描目录，为每个含主文件的子文件夹创建一个SkillProvider（继承自AggregateProvider，见 directory_provider.py）；
• ClaudeSkillsProvider等厂商专用子类：默认指向~/.claude/skills/等平台目录。

对于每个技能，provider 会暴露三类资源（见 skill_provider.py）：

其中_manifest的结构（由 SkillResource._generate_manifest() 生成）类似：

{ "skill": "code-review", "files": [ {"path": "SKILL.md", "size": 1234, "hash": "sha256:abc..."} ] }

这使客户端可以"整体下载"某个技能用于本地使用。

5.1 渐进式披露（Progressive Disclosure）

客户端执行list_resources()时，只会看到技能名称与description（来自 frontmatter），不会看到完整正文——这保证了资源列表的轻量（见 examples/skills/README.md 的 Progressive Disclosure 小节）。默认情况下辅助文件通过ResourceTemplate暴露，不出现在list_resources()结果中；若希望全量枚举，可设置supporting_files="resources"。

5.2 多根目录与重载

SkillsDirectoryProvider支持传入多个根目录并按优先级去重——"如果技能名出现在多个根目录，第一个找到的生效"（directory_provider.py）；设置reload=True则每次请求都重新扫描，便于开发期热更新。

5.3 路径安全防护

辅助文件读取统一走safe_join()校验（skill_provider.py），可拒绝路径穿越、绝对路径注入、空字节与符号链接逃逸，防止通过skill://URI 越权读取目录外文件。

六、端到端运行：把 skills 目录挂到 MCP Server

仓库提供了可直接运行的服务端与客户端示例。服务端 examples/skills/server.py 的核心逻辑只有几行：

from pathlib import Path from fastmcp import FastMCP from fastmcp.server.providers.skills import SkillsDirectoryProvider mcp = FastMCP("Skills Server") skills_dir = Path(__file__).parent / "sample_skills" mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir, reload=True)) mcp.run()

启动与消费：

# 终端 1：启动服务端 uv run python examples/skills/server.py # 终端 2：运行客户端示例 uv run python examples/skills/client.py

客户端示例 examples/skills/client.py 展示了完整的消费流程：列出资源 → 列出资源模板 → 读取skill://pdf-processing/SKILL.md→ 读取_manifest→ 通过模板读取辅助文件。把其中的 URI 换成skill://code-review/SKILL.md，即可读取本文所述的 Code Review 技能正文。

挂载方式非常灵活（examples/skills/server.py 中列出了四种选项）：单个技能用SkillProvider，整个目录用SkillsDirectoryProvider，平台默认位置可用ClaudeSkillsProvider（~/.claude/skills/），还支持项目级与用户级目录的优先级叠加：

mcp.add_provider(SkillsDirectoryProvider(roots=[ Path.cwd() / ".claude/skills", # 项目级优先 Path.home() / ".claude/skills", # 用户级兜底 ]))

此外，__init__.py中还导出了CursorSkillsProvider、VSCodeSkillsProvider、CodexSkillsProvider、GeminiSkillsProvider、GooseSkillsProvider、CopilotSkillsProvider、OpenCodeSkillsProvider等厂商提供者，分别指向~/.cursor/skills/、~/.codex/skills/等平台目录，可直接复用。

七、编写规范总结：如何复刻一份高质量的 SKILL.md

综合原文档与解析器实现，一份可被 fastmcp 正常解析、消费的技能文件应满足：

1. 以---起始，至少提供description（推荐同时提供version与tags），描述应控制在单行、简洁准确；
2. 正文用 Markdown 编写，用##分节组织操作步骤与检查清单；
3. 每个条目保持"可执行"：清单项应像code-review/SKILL.md那样具体到"是否校验用户输入、是否有注入漏洞"这种可判定的粒度，而不是抽象口号；
4. 辅助文件（如 API 参考文档）放在同一目录下，通过相对链接引用，默认由ResourceTemplate按需读取；
5. 反馈类技能应包含输出格式约定（如本文的 Giving Feedback 一节），保证 Agent 生成的结果结构一致、可直接被开发者使用。

将上述技能目录通过SkillsDirectoryProvider挂载后，任何符合 MCP 协议的客户端即可发现、读取并下载这些技能，实现"技能即资源"的分发能力。

【免费下载链接】fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp