尧图网站建设 
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.mdexamples/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] ---这三个字段分别承担不同职责字段值示例作用descriptionReview code for quality, maintainability, and correctness技能的简短描述用于资源列表中向客户端展示实现渐进式披露version1.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 its 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, dont 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.pySkillProvider处理单个技能文件夹将其中文件暴露为资源SkillsDirectoryProvider扫描目录为每个含主文件的子文件夹创建一个SkillProvider继承自AggregateProvider见 directory_provider.pyClaudeSkillsProvider等厂商专用子类默认指向~/.claude/skills/等平台目录。对于每个技能provider 会暴露三类资源见 skill_provider.py资源URI 示例说明主文件资源skill://code-review/SKILL.md技能正文MIME 类型text/markdown合成清单资源skill://code-review/_manifestJSON 格式的文件清单含每个文件的路径、大小、SHA256 哈希辅助文件模板skill://code-review/{path*}或独立资源按supporting_files参数决定暴露方式其中_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_filesresources。5.2 多根目录与重载SkillsDirectoryProvider支持传入多个根目录并按优先级去重——如果技能名出现在多个根目录第一个找到的生效directory_provider.py设置reloadTrue则每次请求都重新扫描便于开发期热更新。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(rootsskills_dir, reloadTrue)) 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 正常解析、消费的技能文件应满足以---起始至少提供description推荐同时提供version与tags描述应控制在单行、简洁准确正文用 Markdown 编写用##分节组织操作步骤与检查清单每个条目保持可执行清单项应像code-review/SKILL.md那样具体到是否校验用户输入、是否有注入漏洞这种可判定的粒度而不是抽象口号辅助文件如 API 参考文档放在同一目录下通过相对链接引用默认由ResourceTemplate按需读取反馈类技能应包含输出格式约定如本文的 Giving Feedback 一节保证 Agent 生成的结果结构一致、可直接被开发者使用。将上述技能目录通过SkillsDirectoryProvider挂载后任何符合 MCP 协议的客户端即可发现、读取并下载这些技能实现技能即资源的分发能力。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 fastmcp 技能实战：用 SKILL.md 编写可复用的 Code Review 审查清单并通过 MCP 资源对外暴露
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.mdexamples/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] ---这三个字段分别承担不同职责字段值示例作用descriptionReview code for quality, maintainability, and correctness技能的简短描述用于资源列表中向客户端展示实现渐进式披露version1.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 its 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, dont 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.pySkillProvider处理单个技能文件夹将其中文件暴露为资源SkillsDirectoryProvider扫描目录为每个含主文件的子文件夹创建一个SkillProvider继承自AggregateProvider见 directory_provider.pyClaudeSkillsProvider等厂商专用子类默认指向~/.claude/skills/等平台目录。对于每个技能provider 会暴露三类资源见 skill_provider.py资源URI 示例说明主文件资源skill://code-review/SKILL.md技能正文MIME 类型text/markdown合成清单资源skill://code-review/_manifestJSON 格式的文件清单含每个文件的路径、大小、SHA256 哈希辅助文件模板skill://code-review/{path*}或独立资源按supporting_files参数决定暴露方式其中_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_filesresources。5.2 多根目录与重载SkillsDirectoryProvider支持传入多个根目录并按优先级去重——如果技能名出现在多个根目录第一个找到的生效directory_provider.py设置reloadTrue则每次请求都重新扫描便于开发期热更新。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(rootsskills_dir, reloadTrue)) 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 正常解析、消费的技能文件应满足以---起始至少提供description推荐同时提供version与tags描述应控制在单行、简洁准确正文用 Markdown 编写用##分节组织操作步骤与检查清单每个条目保持可执行清单项应像code-review/SKILL.md那样具体到是否校验用户输入、是否有注入漏洞这种可判定的粒度而不是抽象口号辅助文件如 API 参考文档放在同一目录下通过相对链接引用默认由ResourceTemplate按需读取反馈类技能应包含输出格式约定如本文的 Giving Feedback 一节保证 Agent 生成的结果结构一致、可直接被开发者使用。将上述技能目录通过SkillsDirectoryProvider挂载后任何符合 MCP 协议的客户端即可发现、读取并下载这些技能实现技能即资源的分发能力。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考