mcp-skill-server

大多数编码助手现在都原生支持技能，因此不再需要专门用于技能发现的 MCP 服务。这个软件包的价值在于让技能的执行具有确定性且可部署——通过固定入口点和受控执行，在编辑器中开发的技能可以在非沙箱化的生产环境中运行。它还支持增量加载，因此 Agent 可以按需发现技能，而不是一开始就加载所有技能。

---

MCP 技能服务

在你工作的地方构建 Agent 技能。编写 Python 脚本，添加 SKILL.md，你的 Agent 就能立即使用它。在日常工作流中实时迭代。准备就绪后，将同一个技能部署到生产环境——无需重写。

为什么？

大多数技能开发流程是这样的：编写代码 → 部署 → 在预发布 Agent 中测试 → 发现问题 → 重新部署 → 重复。这很慢，而且在构建技能时，你始终无法真正使用它。

MCP Skill Server 改变了这一点。它在你的机器上、编辑器中运行——支持 Claude Code、Cursor 或 Claude Desktop。你可以在开发技能的同时，在实际工作中使用它。这种紧密的反馈循环（编辑 → 保存 → 使用）能让你自然地发现缺少什么，而不是依赖人为设计的测试场景。 其前提是：如果技能无法在 Claude Code 中良好运行，那么它很可能也无法在能力较弱的 Agent 中良好运行。

让技能不断完善，以便在外部环境中稳定运行

Claude 技能已经可以包含配套脚本，但没有正式定义的入口点——由 Agent 决定如何调用这些脚本。这适用于本地使用，但无法部署：如果执行路径不固定，生产环境中的 MCP 服务就无法可靠地调用技能。

MCP Skill Server 会强制要求在 SKILL.md 的 frontmatter 中声明 entry 字段（例如 entry: uv run python my_script.py）。这为服务提供了一个固定且唯一的入口点，由服务控制。命令和参数通过脚本的 --help 输出发现——这是事实依据，而不是大模型对代码的解读。

1. Claude/coding agent skill                → SKILL.md + scripts, but no fixed entry — agent decides how to run them
2. Local MCP skill (+ entry)   → Fixed entry point, schema from --help, usable daily via this server
3. Production                  → Same skill, same entry — deployed to your enterprise MCP server

在本地打磨，再为生产环境做好准备

连接到 MCP 服务的每个 Agent 都会获得相同的接口——list_skills、get_skill、run_skill——因此，无论由哪个 Agent 调用，技能描述、参数名称和帮助文本都完全相同。不过，不同 Agent 各有优势——即使技能在本地可用，仍需使用你的生产 Agent 进行测试。

1. 亲自使用——构建技能，并通过 Claude Code 或 Cursor 每天使用它。当 Agent 误用技能时，改进描述和参数名称。
2. 使用较弱的模型进行测试——尝试较小的模型，以发现接口中的歧义。
3. 添加确定性入口点——在 SKILL.md 中声明 entry，以便可靠、安全地执行。使用 skill init 搭建初始结构，使用 skill validate 检查是否已准备就绪。
4. 使用生产 Agent 进行测试——在目标环境中验证端到端流程，然后部署。

安装

Claude Desktop（一键安装）

安装后，编辑 Claude Desktop 配置中的技能路径，使其指向你的技能目录。

Claude Code

claude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills

Cursor

在项目中的 .cursor/mcp.json 中添加（或前往“设置”→“MCP”→“添加服务”）：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

手动安装

# From PyPI (recommended)
uv pip install mcp-skill-server

# Or from source
git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server && uv sync

# Run the server
uvx mcp-skill-server serve /path/to/my/skills

然后添加到编辑器的 MCP 配置中：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

创建技能

选项 A：使用 skill init（推荐）

# Create a new skill
uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"

# Or use the standalone command
uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"

# Promote an existing prompt-only Claude skill to a runnable MCP skill
uv run mcp-skill-init ./existing_claude_skill

选项 B：手动设置

1. 创建包含脚本的文件夹

my_skills/
└── hello/
    ├── SKILL.md
    └── hello.py

2. 添加包含 frontmatter 的 SKILL.md

---
name: hello
description: A friendly greeting skill
entry: uv run python hello.py
---

# Hello Skill

Greets the user by name.

3. 使用 argparse 编写脚本

# hello.py
import argparse

parser = argparse.ArgumentParser(description="Greeting skill")
parser.add_argument("--name", default="World", help="Name to greet")
args = parser.parse_args()

print(f"Hello, {args.name}!")

就这样。服务会根据 --help 输出自动发现命令和参数，无需配置。

部署验证

技能准备好投入生产时：

uv run mcp-skill-server validate ./my_skills/hello
# or
uv run mcp-skill-validate ./my_skills/hello

检查项：

• 必需的 frontmatter 字段（name、description、entry）
• 入口命令使用允许的运行时
• 脚本文件存在
• 可通过 --help 发现命令

工作原理

MCP 工具

服务会向 Agent 暴露四个工具：

工具	描述
list_skills	列出所有可用技能
get_skill	获取技能详情（命令、参数）
run_skill	使用参数执行技能
refresh_skills	修改后重新加载技能

架构发现

服务会自动解析 --help 输出，以发现技能的接口：

# Subcommands become separate commands
subparsers = parser.add_subparsers(dest='command')
analyze = subparsers.add_parser('analyze', help='Run analysis')

# Arguments become parameters with inferred types
analyze.add_argument('--year', type=int, required=True)  # int, required
analyze.add_argument('--file', type=str)                  # string, optional

输出文件

自动检测保存到 output/ 的文件。或者，将 OUTPUT_FILE:/path/to/file 打印到标准输出。

插件

输出处理器

处理技能生成的文件（上传、复制、转换等）：

from mcp_skill_server.plugins import OutputHandler, LocalOutputHandler

# Default: tracks local file paths
handler = LocalOutputHandler()

# Optional GCS handler (requires `uv sync --extra gcs`)
from mcp_skill_server.plugins import GCSOutputHandler
handler = GCSOutputHandler(
    bucket_name="my-bucket",
    folder_prefix="skills/outputs/",
)

响应格式化器

自定义 MCP 工具响应中执行结果的格式：

from mcp_skill_server.plugins import ResponseFormatter

class CustomFormatter(ResponseFormatter):
    def format_execution_result(self, result, skill, command):
        return f"Result: {result.stdout}"

# Use with create_server()
from mcp_skill_server import create_server
server = create_server(
    "/path/to/skills",
    response_formatter=CustomFormatter()
)

开发

git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server
uv sync --dev
uv run pytest
uv run mcp-skill-server serve examples/

延伸阅读

• 面向大模型的工具设计 — 说明技能为何采用 list/get/run 模式，而不是暴露原始工具，以及这对大模型准确性的影响

许可证

MIT