开放-克劳德技能服务器

Name: 开放-克劳德技能服务器
Author: QianjieTech

作者：QianjieTech19 星标更新：2025-11-13

安装使用来源：spider==github.com

项目介绍

AgentSkill MCP

将Claude Agent Skills带入任何兼容MCP的代理

这是一个通用的MCP服务器，使任何支持MCP的代理应用程序能够使用Anthropic官方的Claude Agent Skills，并采用渐进式披露——减少上下文开销同时最大化能力。

包名：agentskill-mcp | PyPI：agentskill-mcp

English | 简体中文

为什么选择AgentSkill MCP？

Claude Agent Skills设计精妙但仅限于Claude生态系统。此项目打破了这一限制：

✅ 通用兼容性：适用于任何MCP兼容的代理（Kilo Code、Cursor、Roo Code、Codex等）
✅ 100% Claude技能兼容：使用官方Anthropic技能格式——无需修改
✅ 渐进式披露：实现与Claude Code相同的智能上下文加载
✅ 零锁定：标准MCP协议意味着您永远不会被绑定到一个平台

技能解决的问题

传统的MCP工具在开始之前会一次性加载所有文档，消耗大量令牌。对于15个以上的工具，您的代理在进行实际工作之前就已经处于上下文饥饿状态。

技能通过渐进式披露解决了这个问题：代理最初看到的是轻量级技能列表，只有在需要时才会加载完整细节。这个项目将同样的效率带给了每个MCP兼容的代理。

特性

🚀 一行安装：pip install agentskill-mcp 或 uvx agentskill-mcp
🔌 通用MCP兼容性（逐步测试）：适用于Kilo Code、Cursor、Roo Code、Codex、Cherry Studio以及任何MCP兼容的代理
📦 官方技能格式：完全兼容Anthropic的Claude技能
🎯 渐进式披露：智能上下文加载——直到需要技能时才产生最小开销
🔄 热重载（尚未实现）：检测文件更改并在实时更新（在协议支持的情况下）
🗂️ 智能路径发现：自动检测.claude/skills/、.skill/或自定义目录
🌍 环境感知：项目级和全局技能目录，自动检测
🎨 ClaudeCode兼容：支持.claude/skills/（ClaudeCode格式）和.skill/（此项目的自定义格式）

项目状态

⚠️ 早期开发 —— 此项目尚处于早期阶段。目前仅在Windows上进行了测试。

已测试平台：

✅ Kilo Code（AI编码助手） —— Windows
✅ Roo Code（AI编码助手） —— Windows
✅ Cline（AI编码助手） —— Windows

下一步计划：

🔄 在更多MCP兼容的代理上进行测试（Codex、Cursor、QwenCode等）
🔄 跨平台测试（macOS、Linux）
🔄 更广泛的兼容性验证
🔄 基于MCP的List Changed Notification进行热重载可行性测试，详见： https://modelcontextprotocol.io/specification/2025-06-18/server/tools#list-changed-notification

理论上：任何实现了模型上下文协议的代理都应该可以工作，但我们正在进行积极测试以确认。

快速入门

配置

⚠️ 当前推荐用法：通过--skills-dir参数指定技能目录

添加到您的MCP客户端配置文件中。在代理的文档中找到配置位置：

Kilo Code：工作区中的.kilocode/mcp.json
Roo Code：查看代理文档
Cursor：工作区中的.cursor/mcp.json
其他代理：参考特定代理的MCP配置指南

推荐配置（Windows）：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": [
        "agentskill-mcp",
        "--skills-dir",
        "C:\\Users\\YourName\\path\\to\\skills"
      ]
    }
  }
}

对于macOS/Linux：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": [
        "agentskill-mcp",
        "--skills-dir",
        "/Users/YourName/path/to/skills"
      ]
    }
  }
}

使用pip安装的版本：

将"command": "uvx"替换为"command": "agentskill-mcp"，并从args中移除：

{
  "mcpServers": {
    "skills": {
      "command": "agentskill-mcp",
      "args": [
        "--skills-dir",
        "C:\\Users\\YourName\\path\\to\\skills"
      ]
    }
  }
}

💡 提示：

使用绝对路径在--skills-dir中以避免歧义
配置更改后，请重启您的代理应用程序或重新加载MCP服务器
先使用examples/目录进行测试，然后再创建自定义技能

加载技能

创建一个技能目录，并添加技能包：

格式1：ClaudeCode格式（推荐给ClaudeCode用户）

# 在当前项目中创建（推荐）
在项目根目录下创建 .claude/skills/

# 或者全局创建
mkdir -p ~/.claude/skills    # Linux/Mac
mkdir C:\Users\YourName\.claude\skills  # Windows

格式2：此项目的自定义格式（与其他代理兼容）

# 在当前项目中创建
在项目根目录下创建 .skill/

# 或者全局创建
mkdir ~/.skill         # Linux/Mac
mkdir C:\Users\YourName\.skill  # Windows

然后将您的技能包放置在技能目录中。./examples目录包含几个官方Anthropic技能包，足以用于测试。

# 示例迁移技能（ClaudeCode格式）
复制 examples/canvas-design -> .claude/skills/
复制 examples/brand-guidelines -> .claude/skills/

# 或者（此项目的自定义格式）
复制 examples/canvas-design -> .skill/
复制 examples/brand-guidelines -> .skill/

最终结构应如下所示：

ClaudeCode格式：.claude/skills/canvas-design/
此项目的自定义格式：.skill/canvas-design/

尝试一下

重启您的代理应用程序并进行测试：

使用Anthropic品牌风格创建一个1920x1080的促销海报。
主题：“AI属于未来？AI只是一个手段，而不是目的。”

会发生什么：

代理在load_skill工具描述中看到可用技能
代理识别相关技能（canvas-design，brand-guidelines）
代理调用load_skill获取完整技能详情
代理遵循技能指令创建海报

注意：代理可能会根据任务解释只调用一个技能。这是正常的——AI代理在工具选择上有一些固有的随机性。

技能格式

技能遵循官方Claude技能格式：

前言（YAML）

---
name: skill-name          # 必需：匹配文件夹名称
description: |            # 必需：详细的代理匹配描述
  这个技能做什么以及何时使用它。
  包括代理应该匹配的关键字。
license: MIT              # 可选：许可证信息
---

技能内容

在前言之后提供详细的Markdown指导：

清晰、可操作的指导
示例和最佳实践
辅助资源的引用

辅助资源

技能可以包括模板、字体、脚本等辅助资源：

# ClaudeCode格式
.claude/skills/
├── algorithmic-art/
│   ├── SKILL.md
│   └── templates/
│       ├── viewer.html
│       └── generator.js

# 或旧格式
.skill/
├── algorithmic-art/
│   ├── SKILL.md
│   └── templates/
│       ├── viewer.html
│       └── generator.js

在技能中引用资源：

使用Read工具读取`templates/viewer.html`

工作原理

渐进式披露实现

挑战：如何在MCP框架内实现渐进式披露？

官方Claude实现（根据行为推测）：

内置技能系统集成在代理的系统提示中
初始显示仅显示<available_skills>列表
特殊的load_skill命令触发完整内容加载

我们的MCP实现：

单一MCP工具：load_skill
- 将所有可用技能元数据嵌入工具的description中
- 代理可以看到技能列表而无需加载完整内容
工具描述结构：

Tool(
    name="load_skill",
    description="""在主对话中执行一个技能

<skills_instructions>
当用户请求您执行任务时，请检查以下可用技能是否可以帮助...
</skills_instructions>

<available_skills>
<skill>
  <name>code-reviewer</name>
  <description>全面的代码审查框架...</description>
</skill>
<skill>
  <name>calculator</name>
  <description>数学计算...</description>
</skill>
</available_skills>
""",
    inputSchema={
        "type": "object",
        "properties": {
            "skill": {"type": "string"}
        }
    }
)

按需加载：
- 代理将任务与<available_skills>中的技能匹配
- 调用load_skill(skill="code-reviewer")
- 服务器读取.skill/code-reviewer/SKILL.md
- 返回完整的技能内容

当前实现说明

版本0.1.3专注于最可靠的使用模式：

✅ 推荐：通过--skills-dir参数指定技能目录
⚠️ 实验性：动态set_skills_directory工具（当前生产环境中禁用）

这种方法确保了在我们继续测试和改进更高级功能的同时，跨不同代理实现的最大兼容性。

路径发现

服务器自动查找技能，优先级如下：

命令行参数：--skills-dir /path/to/skills ⭐ 推荐
环境变量：MCP_SKILLS_DIR=/path/to/skills
项目级：项目根目录下的.claude/skills/或.skill/（检测.git、.claude/、package.json等）
全局回退：~/.skill

注意：当两者都存在时，项目级发现优先考虑.claude/skills/（ClaudeCode格式）而非.skill/（此项目的自定义格式）。

当前推荐：始终使用--skills-dir参数以获得最佳兼容性。

使用示例

示例1：使用绝对路径（推荐）

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": [
        "agentskill-mcp",
        "--skills-dir",
        "C:\\userfolder\\DevFolder\\my-skills"
      ]
    }
  }
}

示例2：使用项目示例

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": [
        "agentskill-mcp",
        "--skills-dir",
        "C:\\path\\to\\Open-ClaudeSkill\\examples"
      ]
    }
  }
}

提供的工具

`load_skill`

通过名称加载并激活一个技能。

参数：

skill（字符串）：要加载的技能名称

示例：

load_skill(skill="code-reviewer")

高级配置

环境变量

MCP_SKILLS_DIR：覆盖默认技能目录

命令行参数

agentskill-mcp --skills-dir /custom/path --log-level DEBUG

日志记录

设置调试日志级别：

agentskill-mcp --log-level DEBUG

级别：DEBUG，INFO，WARNING，ERROR

示例

查看examples/目录中的样本技能：

algorithmic-art：使用p5.js生成艺术作品
canvas-design：设计视觉艺术和海报
brand-guidelines：应用Anthropic品牌样式
code-reviewer：全面的代码审查框架
calculator：数学计算

安装

方法1：使用pip（推荐）

pip install agentskill-mcp

方法2：使用uvx（无需安装即可试用）

# 直接运行而不安装
uvx agentskill-m- cp --help

方法3：使用uv

uv pip install agentskill-mcp

验证安装：

agentskill-mcp --help

# 预期输出：
# usage: agentskill-mcp [-h] [--skills-dir SKILLS_DIR]
#                       [--log-level {DEBUG,INFO,WARNING,ERROR}]
#
# AgentSkill MCP - MCP Server for Claude Skills with progressive disclosure

开发用途（如果您想修改代码）：

git clone https://github.com/QianjieTech/Open-ClaudeSkill.git
cd Open-ClaudeSkill
pip install -e .

开发

从源码运行

# 安装开发依赖
uv pip install -e .

# 运行服务器
uv run agentskill-mcp

# 使用调试日志运行
uv run agentskill-mcp --log-level DEBUG

创建自定义技能

复制一个示例技能作为模板
修改前言（名称、描述）
更新指令
添加任何辅助资源
使用您的代理进行测试

架构

核心组件

ServerState：管理运行时状态和路径发现
SkillLoader：发现并解析技能文件
SkillFileHandler：监控文件变化并进行防抖处理
SkillMCPServer：主要的MCP服务器实现

渐进式披露

技能通过一个单一的load_skill工具暴露，该工具在其描述中列出所有可用技能。这最大限度地减少了初始令牌使用，同时提供了完整的发现。

热重载

通过watchdog检测文件更改并触发技能重新加载。更改将在下一个代理请求时立即生效。

注意：热重载功能已在代码库中实现，但在实践中尚未验证其在所有MCP兼容代理上的可靠性。

贡献

欢迎贡献！请参阅CONTRIBUTING.md了解指南。

许可证

Apache License 2.0 - 详情见LICENSE

资源

文档：官方文档
代理技能规范：Anthropic规范
MCP协议：模型上下文协议
问题：GitHub问题

致谢

此项目基于以下开源项目构建：

MCP（模型上下文协议） - Anthropic
Claude技能 - Anthropic
watchdog - 文件系统监控
PyYAML - YAML解析

联系方式

QQ群：1065081197

由Open-ClaudeSkill社区制作 ❤️