skill2mcp

skill2mcp

将 Claude Code Skills 转换为 MCP (Model Context Protocol) 服务，让任何支持 MCP 的 AI 客户端都能发现和使用本地 Skill。

特性

• 自动扫描 — 自动发现 .claude/skills 和 .claude/commands 目录下的 Skill 文件
• Skill → MCP Tool — 每个 Skill 自动注册为独立的 MCP Tool，支持参数传递和变量替换
• 命令执行 — 提取并执行 Skill 中的 shell 命令（代码块 ```!bash 和内联 !`cmd`）
• 安全防护 — 内置危险命令黑名单、命令超时机制
• 通用 run_command — 可选的通用命令执行 Tool，支持开关控制
• 零配置 — 默认配置即可工作，通过环境变量灵活定制

快速开始

安装

# 使用 npx 直接运行（无需安装）
npx skill2mcp

# 或全局安装
pnpm add -g skill2mcp
skill2mcp

在 MCP 客户端中配置

以 Claude Code 为例，在 .claude/settings.json 中添加：

{
  "mcpServers": {
    "skill2mcp": {
      "command": "npx",
      "args": ["skill2mcp"],
      "env": {
        "SKILL2MCP_WORKDIR": "/path/to/your/project"
      }
    }
  }
}

配置完成后，MCP 客户端将自动发现指定目录下的所有 Skill 并将其暴露为可调用的 Tool。

配置

通过环境变量进行配置：

环境变量	说明	默认值
SKILL2MCP_SKILL_DIRS	Skill 搜索目录，多个目录用 : 分隔	.claude/skills:.claude/commands
SKILL2MCP_TIMEOUT	命令执行超时时间（毫秒）	30000（30 秒）
SKILL2MCP_WORKDIR	工作目录，相对路径的基准目录	当前工作目录
SKILL2MCP_ENABLE_RUN_COMMAND	是否启用通用 run_command Tool	true（启用）

工作原理

flowchart LR
    A[Skill 文件] -->|扫描 & 解析| B[Skill Registry]
    B -->|注册为 Tool| C[MCP Server]
    C -->|stdio 传输| D[MCP 客户端]
    D -->|调用 Tool| C
    C -->|变量替换 & 命令提取| E[命令执行器]
    E -->|安全检查 + 超时控制| F[shell 执行]

• 扫描 — 递归扫描配置的 Skill 目录，解析 Markdown 文件的 frontmatter 和正文
• 注册 — 将每个 Skill 注册为独立的 MCP Tool，名称由目录/文件名派生
• 执行 — 当 Tool 被调用时，替换变量（$ARGUMENTS、${CLAUDE_SKILL_DIR}），提取 shell 命令并执行，将结果替换回正文返回

Skill 格式

目录结构

支持两种目录布局：

.claude/
├── skills/                    # Skill 目录格式
│   └── my-skill/              # 每个 Skill 一个子目录
│       └── SKILL.md           # Skill 定义文件
└── commands/                  # Command 目录格式（兼容）
    └── my-command.md          # 每个 Command 一个 Markdown 文件

Frontmatter 字段

Skill 文件使用 YAML frontmatter 定义元数据：

---
description: "执行项目构建"
argument-hint: "<target>"
when_to_use: "需要构建项目时使用"
allowed-tools: ["Bash", "Read"]
shell: bash
---

## 构建说明

执行以下命令构建项目：

\`\`\`!bash
pnpm run build
\`\`\`

字段	类型	说明
description	string	Skill 描述，用作 MCP Tool 的描述
argument-hint	string	参数提示，如 <file-path>
when_to_use	string	使用场景说明
allowed-tools	string[]	允许使用的工具列表
shell	string	Shell 类型

变量替换

Skill 正文中支持以下变量：

变量	说明
$ARGUMENTS	用户传入的完整参数字符串
$0, $1, $2 ...	参数按空格分割后的各部分
${CLAUDE_SKILL_DIR}	Skill 所在目录的绝对路径

命令格式

在正文中使用以下格式定义要执行的 shell 命令：

代码块格式：

```!bash
pnpm run build
```

内联格式：

当前版本: !`cat package.json | grep version`

安全措施

• 危险命令黑名单 — 自动拦截 rm -rf /、mkfs、dd、shutdown、reboot 等破坏性命令
• 命令超时 — 默认 30 秒超时，超时后自动终止子进程
• spawn 安全 — 使用 child_process.spawn 传入数组参数，避免 shell 注入
• run_command 开关 — 通用命令执行 Tool 可通过 SKILL2MCP_ENABLE_RUN_COMMAND=false 禁用

项目结构

src/
├── bin.ts          # CLI 入口
├── index.ts        # 公共 API 导出
├── config.ts       # 配置解析（环境变量 + 默认值）
├── scanner.ts      # Skill 文件扫描与 frontmatter 解析
├── registry.ts     # MCP Tool 注册（Skill → Tool 映射）
├── executor.ts     # 命令提取、变量替换、安全执行
├── server.ts       # MCP Server 创建与启动
├── types.ts        # 类型定义
└── __tests__/      # 测试文件

开发

# 安装依赖
pnpm install

# 开发模式（watch）
pnpm run dev

# 构建
pnpm run build

# 测试
pnpm run test

# 测试覆盖率
pnpm run test:coverage

# 代码检查
pnpm run lint

# 类型检查
pnpm run typecheck

# 完整检查（typecheck + lint）
pnpm run check

许可证

MIT © 2026 shenjingnan