Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Progressive Skills MCP what skills do you have?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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:
System Prompt: Brief skill list (~200 tokens, sent once)
On-Demand Loading: Full skill instructions (0 tokens until requested)
Referenced Resources: Additional files (0 tokens until accessed)
This approach is especially valuable when working with many skills or limited context windows.
Related MCP server: skilldb-mcp
✅ 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
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.
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/skillsLocal (Windows):
mkdir C:\Users\YourName\skillsVPS/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
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"
}
}
}
}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"
}
}
}
}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...
EOFThe server will find it automatically when restarted.
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.
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.## 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 formattingIf 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.
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.
## Available Skills
- **context7-docs**: Look up technical documentationCost: ~200 tokens, sent ONCE at the start of conversation
load_skill("context7-docs") # Returns full SKILL.mdCost: 0 tokens until the agent actually needs it!
read_skill_file("context7-docs", "references/api-guide.md")Cost: 0 tokens until the skill specifically references it!
These tools are available regardless of how many skills you have:
load_skill(skill_name) - Returns the complete SKILL.md instructions
read_skill_file(skill_name, file_path) - Returns a specific resource file from the skill
list_skill_files(skill_name, subdirectory?) - Lists all available resources in a skill
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---
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.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.
Want to share your skills with others?
Create a public GitHub repository with your skills
Share the repository URL
Others can clone it to their local directory or VPS volume
Point SKILLS_SOURCE to the cloned directory
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! 🎉 |
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.
Check that SKILLS_SOURCE points to the correct directory
Verify the directory contains valid SKILL.md files
Check server logs for specific errors
Ensure the path is accessible to the MCP server
Some MCP clients may require specific formatting for environment variables. Check your client's documentation for the correct syntax.
Windows paths need double backslashes in JSON:
"SKILLS_SOURCE": "C:\\Users\\YourName\\skills"Or use forward slashes:
"SKILLS_SOURCE": "C:/Users/YourName/skills"MIT (same as original skillz)
Based on skillz by Eleanor Berger
Progressive disclosure modifications by Flowtrica
Inspired by Claude.ai's skills system
[FALLBACK ONLY] Fetch a skill resource by URI. IMPORTANT: Only use this if your client does NOT support native MCP resource fetching. If your client supports MCP resources, use the native resource fetching mechanism instead. This tool only supports URIs in the format: resource://skillz/{skill-slug}/{path}. Resource URIs are provided in skill tool responses under the 'resources' field.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_uri | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the fallback nature and URI format constraint, but doesn't describe what happens on invalid URIs, error behavior, or return format. The output schema exists, so return values are partially covered, but behavioral details like failure modes are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the fallback warning, then the URI format. It is slightly repetitive with the IMPORTANT emphasis, but every sentence earns its place. Could be trimmed slightly but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers the key context: when to use, URI format, and where resource URIs come from. It lacks error-handling details and examples, but given the simplicity and output schema, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only explains the URI format (resource://skillz/{skill-slug}/{path}) but does not explain what the resource_uri parameter represents beyond that. It adds some meaning but leaves the parameter semantics incomplete—no examples or clarification of path components.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a skill resource by URI, with a specific verb and resource. It distinguishes itself from siblings by emphasizing it is a fallback for clients without native MCP resource fetching, though it doesn't explicitly contrast with load_skill/read_skill_file/list_skill_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (only if client does NOT support native MCP resource fetching) and when not to use it (use native mechanism instead). It also specifies the URI format, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files available in a skill's directory. Use this to discover what reference files, scripts, or resources a skill provides. Optionally specify a subdirectory like 'references' or 'scripts'.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_name | Yes | ||
| subdirectory | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It conveys that the tool is a read-only listing operation and that subdirectory filtering is available, but it does not mention potential side effects, ordering, hidden-file inclusion, or error behavior. Some behavioral context is added beyond the tool name (listing 'reference files, scripts, or resources' ), but it is sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core verb-resource and followed by a clear directive on a parameter. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with an output schema present, the description covers the main use case and parameter guidance. It doesn't need to describe return values (output schema exists). Minor gaps like recursion or sorting behavior are acceptable for this simplicity, and the available context signals are sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes only parameter names given 0% coverage, so the description must compensate. It explicitly explains the optional subdirectory parameter with examples ('references' or 'scripts'), but it leaves skill_name to implicit understanding from the phrase 'a skill's directory'. This partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List files') and the resource ('in a skill's directory'), and explains it's for discovery of reference files, scripts, or resources. This separates it from sibling tools like read_skill_file (reads a specific file) and fetch_resource (retrieves a resource), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this to discover...' gives explicit context for when this tool is appropriate. It doesn't explicitly state when not to use it or name alternatives, but the listing intent is clear, so a strong 'when' cue is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load the complete instructions for a skill. Use this when you've decided a skill is relevant based on the skill metadata in your system prompt. Returns the full SKILL.md content without frontmatter.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that it returns the full SKILL.md content without frontmatter, which is a key behavioral detail. However, it doesn't mention whether the operation is read-only, any permissions needed, or behavior on failure (e.g., if the skill doesn't exist). It gives some transparency but not exhaustive detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that immediately state the action and return value, then provide the usage condition. Every word earns its place, and the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers the core purpose, the trigger condition, and the return format. It lacks details about error handling or edge cases, but given the simplicity and the presence of an output schema, it is fairly complete. An agent can call it correctly based on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the only parameter, skill_name. The description does not explicitly define what skill_name is or its format, only implying it's the skill identifier from metadata. There are no examples or constraints, so the agent must infer the expected value. This is a significant gap given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Load') and the resource ('complete instructions for a skill'), and specifies that it returns 'the full SKILL.md content without frontmatter'. This distinguishes it from sibling tools like fetch_resource (generic resource retrieval) and read_skill_file (likely reading a specific file), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit condition for use: 'when you've decided a skill is relevant based on the skill metadata in your system prompt'. This tells the agent when to invoke it, though it doesn't explicitly mention alternatives or when not to use it. The guidance is clear enough to avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific file from a skill's directory. Use this when skill instructions reference a file (e.g., 'See references/api_reference.md'). Provide the skill name and relative file path.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| skill_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It communicates read-only behavior and relative paths, but does not mention errors, access constraints, or what happens when the file is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences convey purpose, usage trigger, and required inputs without repetition or fluff. The most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with only two primitive parametersholistic, the description sufficiently covers when and how to use it. It omits edge-case behavior, but the overall scenario is simple enough that this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names both parameters and clarifies that file_path is relative, but it does not elaborate on format, constraints, or path resolution beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Begins with a specific verb and resource ('Read a specific file from a skill's directory') and distinguishes itself from list_skill_files by emphasizing 'specific file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit trigger condition ('Use this when skill instructions reference a file') with a concrete example, but does not contrast with fetch_resource or other potential alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.3fetch_resourcelist_skill_filesload_skillread_skill_fileScored across 4 tools
Each tool targets a distinct action: loading the main skill, reading a specific file, listing files, and fetching resources as a fallback. The purposes are clearly separated with specific use-case guidance, so an agent can reliably choose the right one.
All tools follow a consistent verb_noun pattern (fetch_resource, load_skill, read_skill_file, list_skill_files) with no mixed conventions or vague verbs. The naming is predictable and matches the operation performed.
Four tools is well-scoped for a skill management server: loading, reading, listing, and fetching resources. Each tool earns its place without redundancy, and the count is neither sparse nor excessive for the domain.
The set covers the core operations needed to interact with skills (load, read, list, fetch). The only potential gap is the absence of a dedicated 'list all skills' tool, but skills are advertised in the system prompt, so this is a minor gap that agents can work around.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for skill documentation, generated by doc2mcp.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Capability registry for the agentic economy. Semantic search over verified MCP server listings.