项目介绍
技能管理 MCP 服务器
这是一个基于模型上下文协议（MCP）的服务器，使 Claude 能够管理存储在 ~/.skill-mcp/skills 中的技能。该系统允许 Claude 编程地创建、编辑、运行和管理技能，包括带有环境变量的技能脚本执行。
快速状态
状态: ✅ 生产就绪 测试覆盖率: 86% (145/145 测试通过) 部署日期: 2025年10月18日 架构: 统一的CRUD架构，由22个模块组成的Python包
概览
TL;DR: 编写Python代码，统一多个技能在一个执行中 - 遵循Anthropic的MCP模式，使代理效率提高98.7%。
该项目主要由两个部分组成：
- MCP服务器 (
src/skill_mcp/server.py) - 提供5个统一的CRUD工具用于技能管理的Python包 - 技能目录 (
~/.skill-mcp/skills/) - 存储和管理你的技能的地方
关键优势
🚀 统一多技能执行（使用MCP的代码执行）
构建一次，随处组合 - 执行Python代码，无缝结合多个技能在一个运行中：
# 一个执行，多个技能统一！
# 从计算器、数据处理器和天气技能导入
from math_utils import calculate_average # 计算器技能
from json_fetcher import fetch_json # 数据处理器技能
from weather_api import get_forecast # 天气技能
# 获取天气数据
weather = fetch_json('https://api.weather.com/cities')
# 使用计算器工具计算平均值
temps = [city['temp'] for city in weather['cities']]
avg_temp = calculate_average(temps)
# 获取详细预报
forecast = get_forecast('London')
print(f"平均温度: {avg_temp}°F")
print(f"伦敦预报: {forecast}")
为什么这很强大：
- ✅ 上下文高效 - 自动聚合所有引用技能的依赖项和环境变量
- ✅ 可组合 - 像积木一样混合和匹配来自任何技能的工具
- ✅ 无冗余 - 在库技能中声明一次PEP 723依赖项，到处重用
- ✅ 逐步披露 - 只加载你需要的技能，当你需要它们时
- ✅ 遵循Anthropic的MCP模式 - 使用MCP的代码执行以实现高效的代理
效率提升：
- 📉 发现工具时减少98.7%的令牌 - 相比一次性加载所有工具
- 🔄 中间结果留在代码中 - 处理大数据集而不膨胀上下文
- ⚡ 单次执行 - 复杂的多步骤工作流在一个代码块中，而不是链式工具调用
这与Anthropic的研究一致，显示编写代码调用工具比对每个操作进行直接工具调用，代理扩展得更好。
🔓 不锁定到Claude界面
与Claude界面不同，这个系统使用的是模型上下文协议（MCP），它具有以下特点：
- ✅ 通用性 - 适用于Claude桌面版、claude.ai、Cursor以及任何兼容MCP的客户端
- ✅ 不依赖于Claude - 同样的技能可以在任何支持MCP的地方使用
- ✅ 面向未来 - 不依赖于Claude生态系统或政策变化
- ✅ 本地优先 - 对你的技能和数据有完全控制权
🎯 在任何地方使用技能
你的技能可以运行在：
- Cursor - 支持MCP的IDE集成
- Claude桌面版 - 具有MCP访问权限的原生应用
- claude.ai - 支持MCP的Web界面
- 任何MCP客户端 - 正在增长的兼容应用程序生态系统
📦 独立且模块化
- ✅ 每个技能都有自己的文件、脚本和环境，自成一体
- ✅ 不依赖于专有的Claude特性
- ✅ 可以跨项目版本化、共享和重用
- ✅ 标准的MCP协议确保了兼容性
🔄 在所有MCP客户端之间共享技能
- ✅ 一个技能目录，多个客户端 - 创建一次，随处使用
- ✅ Cursor和Claude中的相同技能 - 不需要重复
- ✅ 无缝切换 - 在工具之间切换无需重新配置
- ✅ 一致体验 - 技能在所有MCP客户端上表现一致
- ✅ 集中管理 - 更新一处的技能，所有地方都可用
🤖 LLM管理的技能（无需手动复制粘贴）
不再需要手动复制、压缩和上传文件：
❌ 旧方法：手动过程
1. 在本地创建技能文件
2. 压缩技能文件夹
3. 上传到Claude界面
4. 等待处理
5. 无法轻松修改或版本化
✅ 新方法：LLM程序化管理
1. 告诉Claude：“创建一个新的名为'data-processor'的技能”
2. Claude创建技能目录和SKILL.md
3. 告诉Claude：“添加一个处理CSV的Python脚本”
4. Claude创建并测试脚本
5. 告诉Claude：“为此技能设置API密钥”
6. Claude更新.env文件
7. 告诉Claude：“使用这些数据运行脚本”
8. Claude执行并展示结果 - 全部即时完成！
关键好处：
- ✅ 无需手动文件操作 - LLM处理创建、编辑和删除
- ✅ 即时更改 - 无需上传/下载/重新加载循环
- ✅ 完整的版本控制 - 技能是常规文件，可以使用git
- ✅ 易于修改 - LLM可以实时编辑脚本
- ✅ 可测试 - LLM可以立即创建和运行脚本
- ✅ 协作 - 团队可以通过MCP共同开发技能
功能
技能管理
- ✅ 列出所有可用技能
- ✅ 浏览技能文件和目录结构
- ✅ 读取技能文件（SKILL.md、脚本、参考、资产）
- ✅ 创建新的技能文件和目录
- ✅ 更新现有的技能文件
- ✅ 删除技能文件
脚本执行
- ✅ 运行Python、Bash和其他可执行脚本
- ✅ 自动依赖管理 - 使用uv内联元数据（PEP 723）的Python脚本
- ✅ 从密钥注入自动环境变量
- ✅ 命令行参数支持
- ✅ 自定义工作目录支持
- ✅ 捕获stdout和stderr
- ✅ 安全的30秒超时
直接Python执行 - 多技能统一 🚀
- ✅ 在一个执行中统一多个技能 - 无缝结合来自不同技能的工具
- ✅ 直接执行Python代码 - 无需创建脚本文件
- ✅ 跨技能导入 - 将来自任何技能的模块作为可重用库导入
- ✅ 自动依赖聚合 - 导入的所有技能的依赖项自动合并
- ✅ 环境变量加载 - 自动加载所有引用技能的.env文件
- ✅ 支持PEP 723 - 代码中的内联依赖项声明
- ✅ 98.7%更高效 - 遵循Anthropic推荐的MCP模式，以构建可扩展的代理
- ✅ 适合多技能工作流程、快速实验、数据分析和复杂管道
环境变量
- ✅ 列出环境变量键（安全 - 不显示值）
- ✅ 按技能设置或更新环境变量
- ✅ 持久存储在每个技能的.env文件中
- ✅ 自动注入到脚本执行中
目录结构
~/.skill-mcp/
└── skills/ # 你的技能目录
├── example-skill/
│ ├── SKILL.md # 必需：技能定义
│ ├── .env # 可选：特定技能的环境变量
│ ├── scripts/ # 可选：可执行脚本
│ ├── references/ # 可选：文档
│ └── assets/ # 可选：模板、文件
└── another-skill/
├── SKILL.md
└── .env
注意: MCP服务器通过PyPI上的uvx安装，并自动运行。不需要本地服务器文件！
快速开始
1. 安装uv
此项目使用uv进行快速可靠的Python包管理。
# 安装uv（包括uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh
2. 配置你的MCP客户端
将MCP服务器添加到你的配置中。服务器将通过uvx从PyPI自动下载和运行。
Claude桌面版 - 编辑配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Cursor - 编辑配置文件：
- macOS:
~/.cursor/mcp.json - Windows:
%USERPROFILE%\.cursor\mcp.json - Linux:
~/.cursor/mcp.json
{
"mcpServers": {
"skill-mcp": {
"command": "uvx",
"args": [
"--from",
"skill-mcp",
"skill-mcp-server"
]
}
}
}
就这样！无需安装 - uvx将自动下载并运行PyPI上的最新版本。
3. 重启你的MCP客户端
重启Claude桌面版或Cursor以加载MCP服务器。
4. 测试一下
在新对话中：
列出所有可用技能
Claude应该使用skill-mcp工具来显示~/.skill-mcp/skills/中的技能。
常用uv命令
在此仓库中开发：
uv sync # 安装/更新依赖项
uv run python script.py # 使用项目环境运行Python
uv add package-name # 添加新的依赖项
uv pip list # 显示已安装的包
uv run pytest tests/ -v # 运行测试
注意: uv会自动创建和管理.venv/ - 不需要手动创建虚拟环境！
脚本依赖项（PEP 723）
✅ run_skill_script 和 execute_python_code 都支持PEP 723！
Python脚本和代码可以使用uv的内联元数据声明其依赖项。服务器会自动检测这一点，并使用uv run来处理依赖项：
#!/usr/bin/env python3
# /// script
# dependencies = [
# "requests>=2.31.0",
# "pandas>=2.0.0",
# ]
# ///
import requests
import pandas as pd
# 你的脚本代码 - 依赖项会自动安装！
response = requests.get("https://api.example.com/data")
df = pd.DataFrame(response.json())
print(df.head())
优点：
- ✅ 无需手动安装依赖项
- ✅ 每次脚本/代码执行都有隔离的依赖项
- ✅ 与
run_skill_script和execute_python_code都自动工作 - ✅ 版本固定确保可重现性
- ✅
execute_python_code也会从技能导入中聚合依赖项！
如何与 run_skill_script 一起工作：
- 在你的Python脚本文件中添加内联元数据
- 当脚本通过
run_skill_script运行时，服务器会检测元数据 - uv会自动创建隔离环境并安装依赖项
- 脚本会在访问这些依赖项的情况下运行
- 无需手动
pip install或虚拟环境管理！
如何与 execute_python_code 一起工作：
- 在你的代码字符串中直接包含PEP 723元数据
- 服务器会自动检测元数据
- uv会创建隔离环境并安装依赖项
- 你的代码会在访问这些依赖项的情况下运行
- 额外奖励: 如果你从技能文件导入，它们的PEP 723依赖项也会自动聚合！
示例: 查看 example-skill/scripts/fetch_data.py 的实际示例。
本地测试：
# 带有依赖项的脚本只需工作！
uv run example-skill/scripts/fetch_data.py
直接Python代码执行 - 在一次运行中统一多个技能
execute_python_code 工具允许你运行Python代码，在一个执行中结合多个技能。这非常适合：
- 🔄 多技能工作流程 - 导入并组合来自不同技能的工具
- 🧪 快速实验 - 测试代码而无需创建文件
- 📊 数据分析 - 使用来自多个技能的库处理数据
- 🏗️ 建立可重用技能库 - 创建一次专用工具，到处使用
Anthropic研究的关键见解: 通过编写代码调用工具，代理扩展得更好，而不是对每个操作进行直接工具调用。这种方法最多可以减少98.7%的上下文使用，并启用更有效的流程。
基本用法
# 带有依赖项的简单内联执行
# /// script
# dependencies = [
# "requests>=2.31.0",
# ]
# ///
import requests
response = requests.get("https://api.example.com/data")
print(response.json())
跨技能导入 - 统一多个技能
组合的力量 - 创建一次实用技能，并以无数种方式组合它们：
现实世界示例: 通过统一计算器、数据处理器和CRM技能来处理销售数据：
步骤1: 创建一个具有可重用模块的计算器技能
# calculator:math_utils.py
def add(a, b):
return a + b
def multiply(a, b):
return a * b
步骤2: 创建数据处理器技能工具
# data-processor:csv_parser.py
# /// script
# dependencies = ["pandas>=2.0.0"]
# ///
import pandas as pd
def parse_csv_url(url):
return pd.read_csv(url)
def filter_by_status(df, status):
return df[df['status'] == status]
步骤3: 在一次执行中统一两个技能！
# 使用skill_references: ["calculator:math_utils.py", "data-processor:csv_parser.py"]执行
from math_utils import calculate_average
from csv_parser import parse_csv_url, filter_by_status
# 获取销售数据
sales_df = parse_csv_url('https://example.com/sales.csv')
# 过滤活跃交易
active_deals = filter_by_status(sales_df, 'active')
# 使用计算器技能计算平均交易规模
deal_values = active_deals['amount'].tolist()
avg_deal = calculate_average(deal_values)
print(f"活跃交易: {len(active_deals)}")
print(f"平均交易规模: ${avg_deal:,.2f}")
发生了什么：
- ✅ 两个技能统一 - 计算器 + 数据处理器在一个执行中
- ✅ 零冗余 - pandas依赖项在csv_parser.py中声明一次，自动包含
- ✅ 可组合 - 像乐高积木一样混合和匹配任何技能
- ✅ 上下文高效 - 只加载了所需的特定模块
自动依赖聚合
当你从具有PEP 723依赖项的技能模块导入时，它们会被自动包含：
具有依赖项的库技能：
# data-processor:json_fetcher.py
# /// script
# dependencies = ["requests>=2.31.0"]
# ///
import requests
def fetch_json(url):
return requests.get(url).json()
你的代码 - 无需重新声明requests！
# 使用skill_references: ["data-processor:json_fetcher.py"]执行
from json_fetcher import fetch_json
data = fetch_json('https://api.example.com')
print(data)
# 来自json_fetcher.py的依赖项自动聚合！
引用技能的环境变量
当你从技能导入时，它的环境变量会自动加载：
具有API凭证的技能：
# weather-skill/.env
API_KEY=your-secret-api-key
API_URL=https://api.weatherapi.com
你的代码 - 环境变量自动可用：
# 使用skill_references: ["weather-skill:api_client.py"]执行
from api_client import fetch_weather
# api_client.py可以从其.env文件访问API_KEY和API_URL
data = fetch_weather('London')
print(data)
优点：
- ✅ 无需手动加载.env文件
- ✅ 每个技能的秘密保持隔离
- ✅ 多个技能的环境变量自动合并
- ✅ 后续技能如果存在冲突会覆盖早期技能
使用场景
- 🔄 多技能工作流程 - 杀手级功能 - 在一个执行中统一来自多个技能的工具
- 示例：在单次运行中组合API客户端 + 数据解析器 + 分析计算器
- 示例：串联抓取器 + NLP处理器 + 通知发送者
- 示例：合并CRM数据 + 支付处理器 + 报告工具
- ✅ 快速数据分析