Skillz：将 Claude Style Skills 普惠到任意 AI Agent 的开源工具

想象这样一个场景：你是一名 AI 开发者，花了一周时间精心编写了一组 Claude Code Skills——包含特定领域的提示词、工作流脚本和参考文档——但它们只能在 Claude Code 中使用。你想要在 Cursor、Warp Terminal 或者自己搭建的 Agent 中复用这些 Skills，却发现只能手动复制粘贴，版本同步更是一团乱麻。

Skillz 正是为解决这个痛点而生。它是一个基于 FastMCP 协议实现的 MCP Server，能够把任意符合 Claude Style 的 Skills（SKILL.md + 资源文件）转换成标准化的 MCP 工具，让任何支持 MCP 协议的 AI 客户端都能直接调用。

背景：Claude Skills 的生态困境

Anthropic 在 2025 年推出的 Claude Code 中引入了 Skills 概念——一种结构化的 AI 指令集，通过 SKILL.md 文件声明元数据（名称、描述、许可），再附上辅助脚本、数据文件等资源。Skills 让 AI Agent 能够像安装插件一样扩展能力，引发了社区的广泛模仿。

然而，Claude Skills 的设计初衷是与 Claude Code 深度绑定的。它们存放在 Claude Code 特定的 ~/.claude/skills/ 目录下，采用扁平的目录结构，且 Claude Code 对 Skills 的解析逻辑是内部实现的。Skills 社区（Skills Supermarket）因此面临一个根本矛盾：开发者写了一套 Skills，却只能在 Claude Code 中使用，无法惠及其他 Agent 生态。

Skillz 由独立开发者 Eleanor Berger（GitHub @eleanor-berger）发起，项目托管于 intellectronica 组织，旨在打破这一壁垒。其官方定位为「实验性概念验证（Proof-of-Concept）」，代码从 2025 年 10 月开源至今已获得 397 Stars。

核心功能：让 Skills 真正可移植

Skillz 的设计哲学可以用一句话概括：Skills 的内容不变，只是接入方式变了。

技能发现与注册机制

Skillz 通过 SkillRegistry 类实现 Skills 的自动发现。默认从 ~/.skillz 目录扫描，支持两种 Skills 包格式：

• 目录形式：每个 Skill 对应一个子目录，目录内必须有 SKILL.md（含 YAML front matter 元数据）
• 压缩包形式：.zip 或 .skill 后缀的文件，解压后同样要求根目录或单一顶层目录下有 SKILL.md

这种设计比 Claude Code 原生只支持扁平目录要灵活得多。开发者可以将相关 Skills 组织在子目录下，也可以将 Skills 作为压缩包分发，便于版本管理和分享。

注册过程中，parse_skill_md() 函数负责解析 SKILL.md 的 YAML front matter，提取 name、description、license、allowed-tools 等字段。解析失败（如缺少 front matter、字段不完整）的 Skills 会被跳过并记录 warning 日志，不会阻塞整个服务。

MCP 协议接入

Skillz 基于 FastMCP 框架构建，而非 Anthropic 官方的 MCP SDK。FastMCP 是一个社区实现的轻量级 MCP Server 框架，提供了更简洁的 API 来注册 tools、resources 和 prompts。

通过 build_server() 函数，Skillz 将已注册的每个 Skill 暴露为 MCP 协议层级的资源（Resource）。MCP 客户端（如 Codex、Copilot）连接后，可以：

1. 列出 Skills：枚举所有可用 Skills 的元数据
2. 读取 Skills 内容：获取 SKILL.md 的 Markdown 正文（去除 front matter 后）
3. 下载资源文件：获取 Skill 目录中的辅助脚本、数据文件等

Skillz 支持三种传输协议，通过 --transport 参数指定：

• stdio（默认）：适用于命令行 Agent，通过标准输入输出通信
• http：提供 HTTP REST 接口
• sse：基于 Server-Sent Events 的推送模式

服务默认端口 8000（HTTP/SSE 模式），可通过 --port 参数自定义。

工具链设计

Skillz 本身是一个纯 Python 包，依赖仅有两个：fastmcp>=2.2.5 和 pyyaml>=6.0。项目使用 uv 作为包管理器和构建工具（pyproject.toml + uv.lock），Python 版本要求 >= 3.12，CI 测试环境甚至使用了最新的 Python 3.14 预览版，确保与前沿生态同步。

技术架构分析

Skillz 的代码库非常精简，核心逻辑集中在一个 ~1200 行的 _server.py 文件中。架构设计值得关注的几个关键点：

核心数据模型

项目定义了四个核心数据结构：

# 元数据：从 SKILL.md front matter 解析
@dataclass(slots=True)
class SkillMetadata:
    name: str
    description: str
    license: Optional[str]
    allowed_tools: tuple[str, ...]  # 允许调用的外部工具
    extra: Dict[str, Any]           # 任意扩展字段

# Skill运行时对象：路径 + 元数据 + 资源
@dataclass(slots=True)
class Skill:
    slug: str                        # URL-safe slug标识
    directory: Path
    instructions_path: Path         # SKILL.md 路径
    metadata: SkillMetadata
    resources: tuple[Path, ...]     # 附带资源文件
    zip_path: Optional[Path]        # 压缩包路径（非目录形式时）
    _zip_members: Optional[set[str]] # zip内文件索引缓存

值得注意的是 Skill 使用 @dataclass(slots=True) 优化内存占用，_zip_members 缓存设计避免了对大 zip 文件的重复扫描。

双注册表设计

SkillRegistry 维护了两张映射表：_skills_by_slug（按 slug 索引）和 _skills_by_name（按 name 索引）。slug 由 slugify() 函数通过正则将名称转为小写字母数字串（如「My Skill → my-skill」），保证了 MCP URI 的合法性。双表设计允许客户端按 slug 或原名查询，但重复注册时会优先保留先出现的版本。

传输层灵活性

FastMCP 框架的抽象层让 Skillz 能够同时支持 stdio/HTTP/SSE 三种传输方式。对于本地 CLI 工具（Codex、Copilot），stdio 模式零配置启动；对于需要远程调用的场景，HTTP/SSE 模式提供了标准的网络接口。

上手体验

安装与启动

Skillz 提供了三种启动方式，按门槛从低到高排列：

方式一：uvx 一行命令（最简）

# MCP客户端配置示例（如Claude Code的mcp.json）
{
  "skillz": {
    "command": "uvx",
    "args": ["skillz@latest"]
  }
}

uvx 是 uv 提供的即开即用运行器，无需预先安装，类似于 Node.js 的 npx。指定 skillz@latest 即可拉取最新版本并运行。Skills 目录默认使用 ~/.skillz。

方式二：Docker 隔离运行（推荐生产使用）

docker run -i --rm \
  -v /path/to/skills:/skillz \
  intellectronica/skillz \
  /skillz

Docker 方式将 Skills 目录通过 volume 挂载进容器，实现宿主机文件与容器内服务的隔离。README 中特别提到应「Treat skills like untrusted code and run in sandboxes/containers」，说明项目方也意识到远程 Skills 的安全风险。

方式三：pip 安装本地开发

pip install skillz
skillz --list-skills  # 预览发现结果
skillz --verbose     # 调试模式

目录结构规范

一个完整的 Skill 目录结构如下：

~/.skillz/
├── summarize-docs/           # 目录型 Skill
│   ├── SKILL.md              # 必须：front matter + 使用说明
│   ├── summarize.py         # 辅助脚本（Agent可下载执行）
│   └── prompts/example.txt  # 参考数据
├── translate.zip            # 压缩包型 Skill
└── data-cleaner.skill       # .skill后缀（同.zip）

其中 SKILL.md 必须包含 YAML front matter：

---
name: summarize-docs
description: Summarize technical documentation
allowed-tools: bash, python3
license: MIT
---

## Instructions
Use summarize.py to process documentation...

Gemini CLI 扩展

Skillz 还提供了官方的 gemini-cli-skillz 扩展，安装后可在 Google Gemini CLI 中直接使用 Skills，真正实现了「一次编写，各端通用」。

安全考量

这是目前 Skillz 最需要关注的问题。 项目 README 开篇即声明「Experimental proof-of-concept. Potentially unsafe. Treat skills like untrusted code and run in sandboxes/containers.」

Skillz 的核心功能是让 Agent 执行 Skills 中打包的脚本和工具。这意味着：

• 从第三方来源安装的 Skills 可能包含恶意代码
• Skills 中的 allowed-tools 字段目前仅起声明作用，并无强制执行机制
• 压缩包形式的 Skills 存在 zip slip 等路径遍历风险（虽然代码中有 __MACOSX/ 过滤）

因此，Skillz 官方强烈建议通过容器运行，并在 MCP 客户端侧配置沙箱环境。生产环境中，应仅使用来源可信的 Skills，并通过签名验证等机制确保完整性。

行业意义

从更宏观的视角看，Skillz 代表了 AI Agent 生态的一个关键趋势：可插拔的技能系统。

当前主流 Agent 产品（Claude Code、Cursor Agent、Copilot Agent）各自维护独立的工具集和能力扩展体系，彼此不兼容。Skills 的标准化如果能够普及，将催生出一个类似 npm 的 Skills 市场——开发者上架一个 Skill，所有 Agent 客户端都能用。Skillz 作为这一愿景的开源先行者，399 Stars 和 35 Forks 的社区关注度说明需求真实存在。

不过，要真正实现这一愿景，还需要解决几个关键问题：跨 Agent 的安全沙箱标准统一、Skills 的版本管理和依赖声明、以及来自 Anthropic 等平台方的官方支持。Skillz 目前作为 MCP Server 的实现，走的是协议层面标准化的路线，可能比厂商私有方案更具长期价值。

总结

维度	评估
定位	MCP Server（协议桥接层）
核心价值	将 Claude Style Skills 普惠到任意 MCP 客户端
技术栈	Python 3.12+, FastMCP, PyYAML
代码规模	~1200 行单文件核心逻辑，精简高效
部署难度	简单（uvx 一行 / Docker 单命令）
容器化	多阶段 Dockerfile，生产可用
传输协议	stdio / HTTP / SSE 三模式
活跃度	持续更新，依赖使用前沿 Python 3.14
安全风险	高（官方承认 PoC 性质，建议沙箱运行）

对于正在构建 AI Agent 工具链的开发者，Skillz 是一个值得关注的实验性工具。它的核心贡献不在于自身代码量，而在于证明了 Skills 可移植性的可行性。如果你的 Agent 支持 MCP 协议，Skillz 可以快速扩展其技能库，尤其适合需要共享和复用专业领域知识的场景。