Progressive Skills MCP

进步技能MCP

用于SKILL.md文件的MCP服务器 渐进式披露 -实现 13倍代币效率 与传统的MCP方法相比。

基于 智力/技能 受Claude.ai技能体系的启发，逐步进行披露修改。

为什么是渐进式披露？

许多MCP服务器预先加载所有信息——每个工具描述、参数和指令都包含在每个请求中。即使不需要大多数信息，这也会消耗大量令牌。

传统MCP方法：

• 为每个技能/能力创建1个工具
• 随每个请求发送的所有工具说明
• 20个技能=20个工具×~100个代币= 约2000个令牌/请求
• 无论是否需要，信息都已发送

渐进技能MCP：

• 创建3个按需加载技能的通用工具
• 最初仅发送技能名称/描述
• 仅在需要时加载完整指令
• 20个技能=3个工具×~50个令牌+技能列表= 约150个令牌/请求
• 效率提高13倍！ 🎉

三个层次：

1. 系统提示：简短技能列表（约200个令牌，发送一次）
2. 按需加载：完整技能说明（在请求之前为0个令牌）
3. 参考资源：其他文件（在访问之前为0个令牌）

当处理许多技能或有限的上下文窗口时，这种方法尤其有价值。

特性

✅ 渐进式披露（3级代币效率）\ ✅ 与所有SKILL.md格式文件兼容\ ✅ 支持.zip和.skill档案\ ✅ 灵活的技能来源（本地目录、VPS卷）\ ✅ 简单 uvx 安装-适用于任何MCP客户端

安装

重要提示： 在安装之前，您必须创建一个技能目录，并可选择向其中添加一些技能。没有有效的技能目录，服务器将无法启动。

设置步骤

第一步：创建技能目录

选择存储技能的位置：

本地（Linux/Mac）：

mkdir -p ~/.skills
# Or any other location you prefer
mkdir -p /home/username/skills

本地（Windows）：

mkdir C:\Users\YourName\skills

VPS/容器：

• 在主机上创建卷或持久目录
• 将其安装到您的容器上（例如。， /mnt/data/skills → /app/skills)

第二步：添加技能（可选）

您可以从一个空目录开始，但在MCP服务器可以做任何有用的事情之前，您需要添加技能：

# Clone example skills
git clone https://github.com/Flowtrica/agent-skills.git ~/.skills

# Or create your own
mkdir -p ~/.skills/my-skill
# (See "Creating Your Own Skills" section below)

步骤3：配置MCP客户端

选项1：本地安装（PC/笔记本电脑）

供当地开发或个人使用：

Linux/Mac：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["progressive-skills-mcp"],
      "env": {
        "SKILLS_SOURCE": "/home/username/skills"
      }
    }
  }
}

窗户：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["progressive-skills-mcp"],
      "env": {
        "SKILLS_SOURCE": "C:\\Users\\YourName\\skills"
      }
    }
  }
}

选项2：带挂载卷的VPS

对于具有持久存储的服务器部署：

首先，将卷装入容器中：

• 在Docker中：将主机目录挂载到容器路径
• 示例：主机 /mnt/data/skills → 容器 /app/skills

然后配置：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["progressive-skills-mcp"],
      "env": {
        "SKILLS_SOURCE": "/app/skills"
      }
    }
  }
}

稍后添加更多技能

您可以随时将技能添加到您的目录中：

方法1：克隆技能库

cd ~/.skills  # Or your skills directory
git clone https://github.com/Flowtrica/agent-skills.git . # Your own skills repository or aone you have found that contains skills.

方法2：创造个人技能

# Example: Adding a weather skill
mkdir -p ~/.skills/weather
cat > ~/.skills/weather/SKILL.md << 'EOF'
---
name: weather
description: Get weather forecasts for any location
---

# Weather Skill

This skill helps you get weather information...
EOF

重新启动时，服务器将自动找到它。

系统提示配置

渐进式披露的工作原理是将技能元数据添加到LLM代理的系统提示中。这告诉特工有哪些可用技能 没有 提前加载所有详细说明。

系统提示模板

复制此模板并将其添加到代理的系统提示中。用您的实际技能更新技能列表：

## Available Skills

You have access to specialized skills that provide detailed instructions for specific tasks.

### How to Use Skills

**Before responding to each user message:**
1. Review the available skills list below
2. Determine if any skill would improve your response quality
3. If a skill is relevant, call `load_skill("skill-name")` to get detailed instructions
4. Follow the skill's instructions to complete the task

**Important:** Proactively use skills based on message context - don't wait for the user to explicitly request a skill. For example, if the user asks "What's the weather like?", immediately use the weather skill without asking.

**When you load a skill:**
- Follow its instructions exactly
- Use `read_skill_file("skill-name", "path/to/file")` if the skill references additional resources
- Use `list_skill_files("skill-name")` to see what resources are available

**MCP Tool Skills:** Some skills provide guidance for other MCP tools. Before using an MCP tool, check if a corresponding skill exists and load it first for usage instructions.

### Available Skills:

- **skill-name-1**: Brief description of what this skill does
- **skill-name-2**: Instructions for how to use the [MCP Tool Name]. Brief description of what the MCP tool does
- **skill-name-3**: Brief description of what this skill does

[Add more skills as needed...]

**Note:** For skills that provide instructions for other MCP tools, always start the description with "Instructions for how to use the [MCP Tool Name]" followed by what the tool does. This helps the agent recognize when to use the skill before calling the MCP tool.

示例（已填写）

## Available Skills

You have access to specialized skills that provide detailed instructions for specific tasks.

### How to Use Skills

**Before responding to each user message:**
1. Review the available skills list below
2. Determine if any skill would improve your response quality
3. If a skill is relevant, call `load_skill("skill-name")` to get detailed instructions
4. Follow the skill's instructions to complete the task

**Important:** Proactively use skills based on message context - don't wait for the user to explicitly request a skill. For example, if the user asks "What's the weather like?", immediately use the weather skill without asking.

**When you load a skill:**
- Follow its instructions exactly
- Use `read_skill_file("skill-name", "path/to/file")` if the skill references additional resources
- Use `list_skill_files("skill-name")` to see what resources are available

**MCP Tool Skills:** Some skills provide guidance for other MCP tools. Before using an MCP tool, check if a corresponding skill exists and load it first for usage instructions.

### Available Skills:

- **weather**: Get weather forecasts and conditions for any location
- **pptx**: Create professional PowerPoint presentations
- **context7**: Instructions for how to use the Context7 MCP which pulls up-to-date, version-specific documentation and code examples straight from the source
- **docx**: Create and edit Word documents with formatting

为MCP工具添加技能

如果您要添加一项技能，为另一个MCP工具提供说明，请在系统提示中使用此格式；

- **skill name**: description

- **Context7**: Instructions for how to use the Context7 MCP which pulls up-to-date, version-specific documentation and code examples straight from the source

为什么这种格式很重要： 以“如何使用\[MCP工具名称\]的说明”开始描述至关重要。它告诉特工这个技能应该加载 *之前* 使用MCP工具。如果没有这种模式，代理将无法始终识别何时使用该技能。

何时更新系统提示

在以下情况下更新系统提示：

• 将新技能添加到技能目录
• 删除技能
• 更改技能的名称或描述

只需在代理的系统提示中编辑技能列表，无需重新启动MCP服务器。

逐步披露解释

级别1：系统提示（每次对话一次）

## Available Skills
- **context7-docs**: Look up technical documentation

成本： 约200个令牌，在对话开始时发送一次

第二级：按需指令

load_skill("context7-docs")  # Returns full SKILL.md

成本： 0个令牌，直到代理真正需要它！

第三级：参考资源

read_skill_file("context7-docs", "references/api-guide.md")

成本： 0个标记，直到技能特别引用它！

三种通用工具

无论你拥有多少技能，这些工具都是可用的：

1. load_skill(skill_name) -返回完整的SKILL.md指令
2. read_skill_file(skill_name, file_path) -从技能返回特定的资源文件
3. list_skill_files(skill_name, subdirectory?) -列出技能中的所有可用资源

创造自己的技能

技能结构

技能可以是：

• 目录 使用SKILL.md文件
• Zip存档 包含SKILL.md
• .技能档案

目录结构示例：

my-skills/
├── weather/
│   ├── SKILL.md
│   └── references/
│       └── api-docs.md
├── pptx/
│   ├── SKILL.md
│   └── templates/
│       └── example.pptx
└── custom-skill.zip

SKILL.md格式

---
name: skill-name
description: Brief one-line description shown in system prompt
---

# Skill Instructions

Detailed instructions for the AI agent to follow when using this skill.

## Purpose

Explain what this skill does and when to use it.

## Steps

1. First, do this...
2. Then, do that...
3. Finally, complete the task...

## Resources

You can reference additional files:
- See `references/api-docs.md` for API details
- Use `templates/example.pptx` as a template

## Notes

Any additional tips or warnings for using this skill.

技能库示例

查看示例技能库以开始：

• 存储库： https://github.com/Flowtrica/agent-skills
• 内容包括： 展示最佳实践的示例技能

您可以将其克隆到本地计算机或VPS上作为起点。

分享技能

想与他人分享你的技能吗？

1. 用你的技能创建一个公共GitHub存储库
2. 共享存储库URL
3. 其他人可以将其克隆到本地目录或VPS卷
4. 点 SKILLS_SOURCE 到克隆目录

令牌效率比较

支持的MCP客户端

渐进式技能MCP适用于任何兼容MCP的客户端：

• 克劳德桌面版
• 樱桃工作室
• 克莱恩
• 泽德
• 以及支持MCP协议的任何其他客户端

所有客户端的配置都是相似的——只需调整JSON格式以满足客户端的要求。

故障排除

技能未加载

1. 检查一下 SKILLS_SOURCE 指向正确的目录
2. 验证目录是否包含有效的SKILL.md文件
3. 检查服务器日志中的特定错误
4. 确保MCP服务器可以访问该路径

无法识别环境变量

一些MCP客户端可能需要特定的环境变量格式。检查客户的文档以了解正确的语法。

Windows上的路径问题

Windows路径需要JSON格式的双反斜杠：

"SKILLS_SOURCE": "C:\\Users\\YourName\\skills"

或者使用正斜杠：

"SKILLS_SOURCE": "C:/Users/YourName/skills"

许可证

麻省理工学院（与原始技能相同）

学分

• 基于 斯基尔茨 作者：埃莉诺·伯杰
• Flowtrica逐步修改披露内容
• 受Claude.ai技能体系启发

链接

• github： https://github.com/Flowtrica/progressive-skills-mcp
• PyPI： https://pypi.org/project/progressive-skills-mcp/
• 示例技能： https://github.com/Flowtrica/agent-skills