Progressive Skills

MCP server for SKILL.md files with progressive disclosure - achieving 13x token efficiency over traditional MCP approaches.

Based on intellectronica/skillz with progressive disclosure modifications inspired by Claude.ai's skills system.

Why Progressive Disclosure?

Many MCP servers load all their information upfront - every tool description, parameter, and instruction is included in each request. This consumes significant tokens even when most information isn't needed.

Traditional MCP Approach:

• Creates 1 tool per skill/capability
• All tool descriptions sent with every request
• 20 skills = 20 tools × ~100 tokens = ~2000 tokens/request
• Information sent whether needed or not

Progressive Skills MCP:

• Creates 3 universal tools that load skills on-demand
• Only skill names/descriptions sent initially
• Full instructions loaded only when needed
• 20 skills = 3 tools × ~50 tokens + skill list = ~150 tokens/request
• 13x more efficient! 🎉

The Three Levels:

1. System Prompt: Brief skill list (~200 tokens, sent once)
2. On-Demand Loading: Full skill instructions (0 tokens until requested)
3. Referenced Resources: Additional files (0 tokens until accessed)

This approach is especially valuable when working with many skills or limited context windows.

Features

✅ Progressive disclosure (3-level token efficiency)
✅ Compatible with all SKILL.md format files
✅ Supports .zip and .skill archives
✅ Flexible skills source (local directories, VPS volumes)
✅ Simple uvx installation - works with any MCP client

Installation

Important: Before installing, you must create a skills directory and optionally add some skills to it. The server will not start without a valid skills directory.

Setup Steps

Step 1: Create Your Skills Directory

Choose where to store your skills:

Local (Linux/Mac):

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

Local (Windows):

mkdir C:\Users\YourName\skills

VPS/Container:

• Create a volume or persistent directory on your host
• Mount it to your container (e.g., /mnt/data/skills → /app/skills)

Step 2: Add Skills (Optional)

You can start with an empty directory, but you'll need to add skills before the MCP server can do anything useful:

# 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)

Step 3: Configure Your MCP Client

Option 1: Local Installation (PC/Laptop)

For local development or personal use:

Linux/Mac:

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

Windows:

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

Option 2: VPS with Mounted Volume

For server deployments with persistent storage:

First, mount the volume in your container:

• In Docker: Mount host directory to container path
• Example: Host /mnt/data/skills → Container /app/skills

Then configure:

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

Adding More Skills Later

You can add skills to your directory at any time:

Method 1: Clone a skills repository

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.

Method 2: Create individual skills

# 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

The server will find it automatically when restarted.

System Prompt Configuration

Progressive disclosure works by adding skill metadata to your LLM agent's system prompt. This tells the agent what skills are available without loading all the detailed instructions upfront.

System Prompt Template

Copy this template and add it to your agent's system prompt. Update the skill list with your actual skills:

## 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.

Example (Filled In)

## 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

Adding Skills for MCP Tools

If you're adding a skill that provides instructions for another MCP tool, use this format in the system prompt;

- **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

Why this format matters: Starting the description with "Instructions for how to use the [MCP Tool Name]" is critical. It tells the agent this skill should be loaded before using that MCP tool. Without this pattern, the agent won't consistently recognize when to use the skill.

When to Update the System Prompt

Update your system prompt whenever you:

• Add a new skill to your skills directory
• Remove a skill
• Change a skill's name or description

Simply edit the skill list in your agent's system prompt - no need to restart the MCP server.

Progressive Disclosure Explained

Level 1: System Prompt (Once per conversation)

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

Cost: ~200 tokens, sent ONCE at the start of conversation

Level 2: On-Demand Instructions

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

Cost: 0 tokens until the agent actually needs it!

Level 3: Referenced Resources

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

Cost: 0 tokens until the skill specifically references it!

Three Universal Tools

These tools are available regardless of how many skills you have:

1. load_skill(skill_name) - Returns the complete SKILL.md instructions
2. read_skill_file(skill_name, file_path) - Returns a specific resource file from the skill
3. list_skill_files(skill_name, subdirectory?) - Lists all available resources in a skill

Creating Your Own Skills

Skill Structure

Skills can be:

• Directories with a SKILL.md file
• Zip archives containing SKILL.md
• .skill archives

Example directory structure:

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

SKILL.md Format

---
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.

Example Skills Repository

Check out the example skills repo to get started:

• Repository: https://github.com/Flowtrica/agent-skills
• What's included: Sample skills demonstrating best practices

You can clone it to your local machine or VPS to use as a starting point.

Sharing Skills

Want to share your skills with others?

1. Create a public GitHub repository with your skills
2. Share the repository URL
3. Others can clone it to their local directory or VPS volume
4. Point SKILLS_SOURCE to the cloned directory

Token Efficiency Comparison

Approach	Tools/Request	Tokens/Request	20 Skills
Traditional MCP (one tool per skill)	20 tools	~100 each	~2000 tokens
Progressive Disclosure	3 tools	~50 each	~150 tokens
Improvement	-85%	-85%	13x better! 🎉

Supported MCP Clients

Progressive Skills MCP works with any MCP-compatible client:

• Claude Desktop
• Cherry Studio
• Cline
• Zed
• And any other client supporting the MCP protocol

Configuration is similar across all clients - just adjust the JSON format to match your client's requirements.

Troubleshooting

Skills not loading

1. Check that SKILLS_SOURCE points to the correct directory
2. Verify the directory contains valid SKILL.md files
3. Check server logs for specific errors
4. Ensure the path is accessible to the MCP server

Environment variable not recognized

Some MCP clients may require specific formatting for environment variables. Check your client's documentation for the correct syntax.

Path issues on Windows

Windows paths need double backslashes in JSON:

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

Or use forward slashes:

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

License

MIT (same as original skillz)

Credits

• Based on skillz by Eleanor Berger
• Progressive disclosure modifications by Flowtrica
• Inspired by Claude.ai's skills system

Links

• GitHub: https://github.com/Flowtrica/progressive-skills-mcp
• PyPI: https://pypi.org/project/progressive-skills-mcp/
• Example Skills: https://github.com/Flowtrica/agent-skills