当前位置：首页 > news >正文

Skillz：基于MCP协议实现AI技能跨平台复用的开源服务器

news 2026/4/26 16:54:52

1. 项目概述：Skillz，一个为AI智能体注入“技能”的MCP服务器

在AI智能体（Agent）的开发和使用中，我们常常面临一个困境：每个智能体平台（如Claude Code、Cursor、GitHub Copilot等）都有自己的一套“技能”（Skills）或“工具”（Tools）生态。一个在Claude Code上编写精良、能自动分析代码依赖的技能，到了其他环境可能就完全无法使用。这种生态割裂不仅增加了开发者的重复劳动，也限制了技能的复用和传播。今天要介绍的Skillz项目，正是为了解决这个问题而生。它是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器，其核心使命是作为一个“适配器”或“桥梁”，让遵循Claude技能格式（SKILL.md）编写的技能，能够被任何支持MCP协议的AI客户端所调用。

简单来说，Skillz让你辛苦编写的AI技能不再被某个平台“锁死”。无论你习惯使用Codex、Copilot、Cursor，还是其他任何集成了MCP客户端的开发环境，你都可以通过Skillz服务器，加载并调用同一套技能库。这极大地提升了开发效率，也让技能生态的构建变得更加开放和可持续。对于经常在不同AI编程工具间切换的开发者，或是希望为自己团队构建一套统一、可移植AI工具链的技术负责人而言，Skillz提供了一个非常优雅的解决方案。

注意：Skillz目前仍被作者标记为“实验性的概念验证”。这意味着其API和功能可能在未来发生变动，且其运行机制涉及执行外部脚本，存在潜在安全风险。务必将其视为不受信任的代码，建议在沙箱或容器环境中运行，使用时需自行承担风险。

2. 核心原理与架构设计解析

要理解Skillz的价值，我们需要先拆解其依赖的两个关键技术：Claude技能格式和模型上下文协议（MCP）。

2.1 Claude技能格式：技能的定义与封装

Claude技能并非一个复杂的二进制程序，而是一种基于Markdown和文件的轻量级封装。一个标准的技能包通常包含以下核心部分：

SKILL.md文件：这是技能的灵魂。它采用YAML Front Matter（一种在Markdown文件头部用---分隔的YAML区块）来定义技能的元数据，例如技能名称、描述、输入参数、输出格式等。在YAML区块之后，则是用自然语言编写的、给AI模型看的详细使用说明和示例。
资源文件：这是技能的“身体”。可以是Python/JavaScript脚本、Shell脚本、配置文件、示例数据、提示词模板等任何辅助文件。这些资源在技能被调用时，可以作为上下文提供给AI模型，或者被技能内嵌的脚本直接执行。

这种设计的精妙之处在于“人机共读”。SKILL.md既是给开发者看的文档，也是给AI模型看的“说明书”。AI通过阅读这份说明书来理解何时以及如何调用该技能，而附带的资源文件则为技能的真正执行提供了可能。

2.2 模型上下文协议（MCP）：统一的通信桥梁

MCP是一个开放协议，旨在标准化AI应用程序（客户端）与外部数据源、工具（服务器）之间的通信。你可以把它想象成AI世界的“USB协议”或“HTTP协议”。一个MCP服务器可以暴露一系列“工具”（Tools）和“资源”（Resources），而MCP客户端（如AI智能体）则可以发现这些工具并调用它们。

Skillz的核心工作，就是扮演一个MCP服务器。它扫描指定的技能目录，解析每个技能文件夹或压缩包中的SKILL.md文件，然后将每个技能“转换”成一个或多个标准的MCP工具。同时，技能包内的其他资源文件，则被暴露为MCP资源，可供客户端按需读取。这样，任何兼容MCP的AI客户端，无需理解Claude技能的具体格式，只需要通过标准的MCP协议与Skillz服务器通信，就能获得所有已加载技能的能力。

2.3 Skillz的工作流程

发现阶段：Skillz启动时，根据配置的路径（默认为~/.skillz）扫描技能。它支持多种组织形式：单层文件夹、嵌套子目录、以及.zip或.skill格式的压缩包。
解析阶段：对于每个发现的技能单元，Skillz读取其SKILL.md，解析YAML Front Matter，提取出工具名称、描述、参数列表等关键信息。
注册阶段：Skillz将这些信息封装成标准的MCP工具，并向连接的客户端进行通告。
调用阶段：当AI客户端（用户通过自然语言或指令）决定调用某个技能时，它会通过MCP协议向Skillz发送一个包含参数的请求。
执行阶段：Skillz接收到请求后，会根据技能配置，执行技能包内指定的辅助脚本（如果有），或者仅仅是将技能资源和说明提供给AI模型，由模型在上下文中进行“计算”。
返回阶段：Skillz将脚本执行的结果或处理后的信息，通过MCP协议返回给客户端，最终呈现给用户。

这种架构将技能的具体实现（脚本）与技能的调用接口（MCP工具）解耦，是Skillz能够实现跨平台兼容性的关键。

3. 从零开始：Skillz的安装与基础配置

3.1 环境准备与安装

Skillz是一个Python包，推荐使用uv这个快速的Python包安装器和解析器来运行，它能很好地处理依赖隔离。

首先，确保你的系统已安装Python 3.8+。然后，你可以使用pip或uv来安装或运行Skillz。

方法一：使用uvx直接运行（推荐，无需永久安装）uvx是uv的工具，可以像全局命令一样运行Python包。这是最快捷的方式，尤其适合体验和测试。

# 直接运行最新版的skillz，它会启动MCP服务器（默认使用stdio传输） uvx skillz@latest

方法二：使用pip安装如果你希望将其安装到特定环境，可以使用pip。

pip install skillz # 安装后，可以通过 `skillz` 命令启动 skillz

3.2 配置你的AI客户端以连接Skillz

安装Skillz本身只是第一步，更重要的是让你的AI工具知道它的存在。这需要通过配置你所用工具的MCP服务器设置来实现。

以Cursor IDE为例：Cursor内置了MCP客户端支持。你需要编辑Cursor的MCP配置文件。此文件通常位于：

macOS/Linux:~/.cursor/mcp.json
Windows:%USERPROFILE%\.cursor\mcp.json

如果文件不存在，请创建它。然后添加Skillz的配置：

{ "mcpServers": { "skillz": { "command": "uvx", "args": ["skillz@latest"] } } }

这个配置告诉Cursor：“启动一个名为‘skillz’的MCP服务器，执行命令uvx，并传递参数skillz@latest”。配置完成后，重启Cursor，它就会自动启动Skillz服务器并建立连接。

以Claude Code为例：Claude Code的配置方式类似，配置文件路径可能为~/.config/claude-code/mcp.json或通过其设置界面配置。内容与上述Cursor配置基本相同。

实操心得：在配置时，最常遇到的问题是指令路径错误。如果你不是用uvx而是用pip安装到了虚拟环境，那么command应该指向该虚拟环境Python解释器下的skillz可执行文件绝对路径。使用uvx是最省心的方式，因为它会自动处理环境问题。

3.3 技能目录的初始化与管理

默认情况下，Skillz会从~/.skillz目录加载技能。你需要创建这个目录并开始存放你的技能。

mkdir -p ~/.skillz

现在，你的~/.skillz目录就是你的“技能库”。你可以通过两种方式向其中添加技能：

手动创建：在~/.skillz下为每个技能创建子文件夹，并按照格式放置SKILL.md和资源文件。
从市场安装：访问Skills Supermarket，这是一个Skillz的技能目录站。你可以找到他人分享的技能，通常以.skill或.zip格式提供，下载后直接放入~/.skillz目录即可。

4. 技能开发详解：编写你的第一个SKILL.md

要让Skillz识别并暴露一个技能，核心是正确编写SKILL.md文件。让我们通过一个具体的例子——“文件行数统计”技能来学习。

4.1 技能元数据定义（YAML Front Matter）

在SKILL.md文件的最顶部，用---包裹YAML内容，用于定义技能的“接口”。

--- name: count-lines description: 统计指定文本文件或代码文件的行数。 input_schema: type: object properties: file_path: type: string description: 需要统计行数的文件的绝对路径或相对于技能目录的路径。 required: - file_path ---

参数解析：

name: 技能的唯一标识符，在MCP工具列表中显示的名称。建议使用短横线分隔的小写单词。
description: 技能的简短描述，帮助AI模型理解技能的用途。
input_schema: 定义了调用此技能时需要输入的参数。它遵循JSON Schema格式。
- type: object: 表示输入是一个对象。
- properties: 定义对象中的各个属性（参数）。这里我们定义了一个file_path参数。
- required: 列出哪些参数是调用时必须提供的。

这个YAML块告诉Skillz和AI客户端：“这里有一个叫count-lines的工具，它需要一个file_path字符串参数。”

4.2 技能指令与上下文编写

在YAML块下方，就是给AI模型看的详细指令了。这部分用自然语言写成，质量直接影响到AI是否能正确使用该技能。

## 技能指令 你是一个文件行数统计工具。当用户想要知道一个文件有多少行时，我会为你提供文件路径。 你的任务是： 1. 读取 `file_path` 参数所指向的文件。 2. 计算文件的总行数。 3. 返回一个清晰的结果信息，格式为：“文件 [文件名] 共有 [行数] 行。” ## 示例 **用户请求**：“帮我数一下 `project/src/main.py` 有多少行。” **调用参数**：`{ "file_path": "project/src/main.py" }` **期望输出**：“文件 main.py 共有 150 行。” ## 资源 本技能附带一个辅助脚本 `count_lines.py`，你可以选择使用它来精确计算行数，或者直接使用你内部的文本处理能力。 ```python # count_lines.py import sys def count_lines(filepath): try: with open(filepath, 'r', encoding='utf-8') as f: return sum(1 for _ in f) except FileNotFoundError: return f"错误：找不到文件 {filepath}" except Exception as e: return f"读取文件时出错：{e}" if __name__ == "__main__": if len(sys.argv) != 2: print("用法: python count_lines.py <文件路径>") sys.exit(1) result = count_lines(sys.argv[1]) print(result) ```

编写要点：

指令明确：清晰告诉AI“你是什么”、“你的任务是什么”。避免模糊不清。
示例具体：提供至少一个完整的输入输出示例，这是AI学习如何调用技能的最佳方式。
资源引用：如果技能包含可执行脚本，在这里说明其用途和调用方法。AI模型可能会决定是直接运行脚本，还是根据脚本逻辑自行处理。

4.3 组织技能文件结构

将上面的SKILL.md和count_lines.py脚本放在同一个文件夹中，然后将整个文件夹放入Skillz的搜索路径。

最终的技能目录结构如下：

~/.skillz/ └── count-lines/ # 技能文件夹，名字最好与技能名一致 ├── SKILL.md # 核心技能定义文件 └── count_lines.py # 辅助脚本（资源文件）

完成以上步骤后，重启你的Skillz服务器（或确保其正在运行），然后在你的AI客户端（如Cursor）中，你就可以尝试询问：“请使用count-lines技能统计一下/home/user/test.py的行数。” AI应该能识别并调用这个技能。

5. 高级配置与部署方案

5.1 使用Docker运行以实现环境隔离

考虑到Skillz会执行技能包中的任意脚本，为了安全，强烈建议在生产环境或运行不受信任的技能时使用Docker容器进行隔离。

Skillz提供了官方Docker镜像intellectronica/skillz。使用Docker部署的配置如下：

{ "skillz": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/absolute/path/to/your/skills:/skillz:ro", "intellectronica/skillz", "/skillz" ] } }

配置参数拆解：

-i: 保持标准输入打开，允许MCP客户端与容器内进程交互。
--rm: 容器退出后自动删除，避免积累停止的容器。
-v /host/path:/skillz:ro: 这是关键。将主机上的技能目录挂载到容器内的/skillz路径。:ro表示以只读方式挂载，防止技能脚本意外修改主机文件，这是一个重要的安全实践。
intellectronica/skillz: 使用的Docker镜像。
/skillz: 传递给容器内Skillz进程的参数，指定容器内的技能根目录。

重要安全提醒：即使使用Docker，也只挂载必要的技能目录，并尽可能使用只读(:ro)选项。切勿将整个用户目录或敏感系统目录挂载到容器中。

5.2 探索不同的MCP传输方式

Skillz基于FastMCP构建，支持三种传输方式，适用于不同场景：

stdio(默认)：标准输入输出。适用于与本地客户端（如Cursor、Claude Code）集成，配置简单，性能好。
http: HTTP协议。将Skillz作为HTTP服务运行，允许网络上的远程客户端调用。适合团队内共享一个技能服务器。
sse: 服务器发送事件。一种单向通信协议，适用于特定推送场景。

例如，如果你想将Skillz运行为一个本地HTTP服务，供多个本地工具连接，可以这样启动：

uvx skillz@latest --transport http --host 127.0.0.1 --port 8000

然后在客户端的MCP配置中，就需要使用http传输的配置格式（具体格式取决于客户端支持，可能需要指定URL）。

5.3 技能目录的灵活组织与兼容性考量

Skillz在技能发现上比Claude Code更灵活，但这带来了兼容性问题。

Claude Code兼容模式（扁平结构）：如果你希望技能目录同时能被原生的Claude Code识别，必须使用严格的扁平结构。Claude Code只扫描技能根目录下的一级子文件夹，每个子文件夹是一个技能，不支持压缩包和嵌套。

~/.skillz/ # 技能根目录 ├── skill-a/ # 技能A │ ├── SKILL.md │ └── helper.py ├── skill-b/ # 技能B │ └── SKILL.md └── skill-c/ # 技能C ├── SKILL.md ├── data.csv └── process.py

Skillz增强模式（嵌套与压缩包）：如果你只使用Skillz，可以充分利用其高级特性来管理大量技能。

~/.skillz/ ├── text-utils/ # 分类目录 │ ├── summarizer/ # 技能：总结工具 │ │ ├── SKILL.md │ │ └── sum.py │ └── translator.skill # 技能：翻译工具（压缩包格式） ├── code-analysis.zip # 技能：代码分析（压缩包格式，根目录有SKILL.md） └── devops/ └── deploy/ # 技能：部署工具 ├── SKILL.md └── scripts/ ├── deploy.sh └── config.yaml

你可以使用skillz --list-skills命令来验证Skillz是否能正确发现所有技能。

# 扫描默认目录 skillz --list-skills # 扫描指定目录 skillz /path/to/my/skills --list-skills

6. 实战：集成外部技能与故障排查

6.1 集成Gemini CLI扩展

Skillz的生态不仅限于代码编辑器。intellectronica/gemini-cli-skillz项目是一个Gemini CLI的扩展，它允许你在命令行中使用Gemini AI模型，并通过Skillz调用Claude格式的技能。

安装与使用：

确保已安装gemini-cli工具。

安装Skillz扩展：

gemini extensions install https://github.com/intellectronica/gemini-cli-skillz

配置Gemini CLI使用Skillz。这通常需要在Gemini CLI的配置文件中指定MCP服务器，配置方式与Cursor类似，指向Skillz服务器进程。
之后，在命令行中，你就可以像这样使用：gemini -p “使用summarize技能总结一下这篇长文章”，Gemini CLI会通过Skillz调用对应的总结技能。

这个案例展示了Skillz作为标准化MCP服务器的威力：一次编写技能，可以在桌面IDE和命令行工具等多种客户端中复用。

6.2 常见问题与排查技巧实录

在实际部署和使用Skillz的过程中，你可能会遇到以下问题：

问题1：AI客户端无法发现或调用技能。

排查步骤：
1. 检查Skillz进程：首先确认Skillz服务器是否正在运行。在配置为stdio传输时，客户端会负责启动它，但有时启动会失败。查看客户端的日志或控制台输出。
2. 使用--verbose和--log参数：在Skillz的启动命令中添加--verbose参数，可以将调试日志输出到控制台。添加--log参数会同时将日志写入/tmp/skillz.log文件。这是最直接的排查手段。
```
uvx skillz@latest --verbose --log
```
3. 检查技能发现日志：在verbose日志中，寻找“Discovered skill”相关的条目。如果没有，说明Skillz没有在你的目录中找到有效的SKILL.md文件。
4. 验证SKILL.md格式：确保SKILL.md的YAML Front Matter格式正确，没有语法错误。可以使用在线YAML校验器检查---之间的内容。
5. 检查MCP配置：确认客户端（如Cursor）的mcp.json配置文件路径正确，内容无JSON语法错误，且命令uvx在系统PATH中可用。

问题2：技能被调用，但AI模型不理解或错误使用。

排查步骤：
1. 精炼技能描述：问题往往出在SKILL.md的“技能指令”部分。确保指令足够清晰、无歧义。多从AI模型的视角思考：“看到这段文字，我能明白要做什么吗？”
2. 丰富示例：增加更多、更贴近真实使用场景的调用示例。示例是最好的老师。
3. 简化输入模式：如果技能输入模式太复杂，AI可能难以正确构造参数。尝试将复杂参数拆解或提供默认值。

问题3：技能包中的脚本执行失败。

排查步骤：
1. 权限问题：在Linux/macOS下，确保脚本具有可执行权限(chmod +x script.sh)。
2. 环境依赖：脚本可能依赖特定的Python包或系统工具。考虑在技能文档中明确声明依赖，或者将技能打包进Docker容器，确保环境一致性。
3. 路径问题：脚本中使用的相对路径，是基于Skillz服务器进程的当前工作目录，还是基于技能包所在的目录？这是一个常见的坑。建议在脚本中处理路径时，优先使用从参数传入的绝对路径，或明确标注路径是相对于技能目录的。

问题4：技能加载缓慢或客户端响应慢。

排查步骤：
1. 技能目录规模：如果技能目录中有成千上万个文件，Skillz的初始扫描可能会变慢。考虑优化目录结构，或将不常用的技能移出。
2. 压缩包的影响：Skillz在启动时需要解压.zip或.skill文件以读取SKILL.md。如果压缩包很大，会影响启动速度。对于稳定的技能，可以考虑解压后使用文件夹形式存放。
3. 网络问题（仅HTTP/SSE模式）：如果使用远程HTTP模式，检查网络延迟。

一个实用的调试技巧：在开发技能时，我习惯先不使用AI客户端，而是用--verbose模式启动Skillz，并配合一个简单的MCP客户端测试工具（例如，一些MCP SDK自带的客户端示例）来手动调用技能，观察输入输出。这样可以排除AI模型理解带来的不确定性，聚焦于技能本身的逻辑和Skillz的配置是否正确。

查看全文

http://www.jsqmd.com/news/704212/