progressive-skills-mcp 0.2.0__tar.gz → 0.2.2__tar.gz

{progressive_skills_mcp-0.2.0 → progressive_skills_mcp-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: progressive-skills-mcp
-Version: 0.2.0
+Version: 0.2.2
 Summary: MCP server that exposes Claude-style skills to any MCP client.
 Keywords: mcp,skills,fastmcp,claude
 Author: Eleanor Berger
@@ -39,7 +39,7 @@ Project-URL: Homepage, https://github.com/Flowtrica/skills-mcp
 Project-URL: Issues, https://github.com/Flowtrica/skills-mcp/issues
 Description-Content-Type: text/markdown
 
-# Skills MCP
+# Progressive Skills MCP
 
 MCP server for SKILL.md files with **progressive disclosure** - achieving **13x token efficiency** over traditional approaches.
 
@@ -51,7 +51,7 @@ Based on [intellectronica/skillz](https://github.com/intellectronica/skillz) wit
 - Creates 1 tool per skill
 - 20 skills = 20 tools × ~100 tokens = **2000 tokens/request**
 
-**Skills MCP (this fork):**
+**Progressive Skills MCP:**
 - Creates 3 universal tools (`load_skill`, `read_skill_file`, `list_skill_files`)
 - 20 skills = 3 tools × ~50 tokens = **150 tokens/request**
 - **13x improvement!** 🎉
@@ -62,23 +62,14 @@ Based on [intellectronica/skillz](https://github.com/intellectronica/skillz) wit
 ✅ Metadata generation for system prompts  
 ✅ Compatible with all SKILL.md format files  
 ✅ Supports .zip and .skill archives  
-✅ Docker image available  
+✅ Bundled skills ready to use  
 
 ## Quick Start
 
-### Using Docker
+### Using uvx (Recommended)
 
 ```bash
-docker run -i --rm \
-  -v /path/to/skills:/skills \
-  flowtrica/skills-mcp:latest \
-  /skills
-```
-
-### Using uvx
-
-```bash
-uvx skills-mcp@latest /path/to/skills
+uvx progressive-skills-mcp
 ```
 
 ### With MCPHub
@@ -87,84 +78,155 @@ uvx skills-mcp@latest /path/to/skills
 {
   "mcpServers": {
     "skills": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "--entrypoint", "sh",
-        "flowtrica/skills-mcp:latest",
-        "-c",
-        "git clone https://github.com/YOUR_USERNAME/your-skills.git /tmp/skills && skills-mcp /tmp/skills"
-      ]
+      "command": "uvx",
+      "args": ["progressive-skills-mcp"]
     }
   }
 }
 ```
 
+### Using pip
+
+```bash
+pip install progressive-skills-mcp
+progressive-skills-mcp
+```
+
+## 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.
+
+### Step 1: Generate Metadata
+
+```bash
+progressive-skills-mcp --generate-metadata > skills-metadata.txt
+```
+
+This outputs:
+
+```markdown
+## Available Skills
+
+You have access to specialized skills that provide detailed instructions for specific tasks. When a task requires specialized knowledge or a specific workflow, use the `load_skill` tool to get the full instructions.
+
+### How to Use Skills
+
+1. Check if a skill is relevant to the user's request
+2. Call `load_skill("skill-name")` to get detailed instructions
+3. Follow the instructions in the skill
+4. Use `read_skill_file()` if the skill references additional resources
+
+**Available skills:**
+
+- **context7-docs-lookup**: Look up documentation from Context7 for libraries and frameworks
+```
+
+### Step 2: Add to Agent System Prompt
+
+Copy the metadata output and add it to your LLM agent's system prompt. For example, in **Onyx**, **LibreChat**, or **Open WebUI**:
+
+```
+You are a helpful AI assistant.
+
+[... other system prompt content ...]
+
+## Available Skills
+
+You have access to specialized skills that provide detailed instructions for specific tasks...
+
+- **context7-docs-lookup**: Look up documentation from Context7...
+```
+
+### Step 3: Agent Uses Skills
+
+When relevant, the agent will:
+
+1. **See skill in system prompt** → "context7-docs-lookup is available"
+2. **Call load_skill** → `load_skill("context7-docs-lookup")`
+3. **Receive full instructions** → Complete SKILL.md content
+4. **Follow instructions** → Execute the skill workflow
+
+### Example Conversation
+
+**User:** "How do I use React hooks in Next.js?"
+
+**Agent thinks:** *The context7-docs-lookup skill can help with documentation lookup*
+
+**Agent calls:** `load_skill("context7-docs-lookup")`
+
+**Agent receives:** Full skill instructions on how to use Context7 API
+
+**Agent executes:** Follows skill instructions to look up Next.js documentation
+
+**Agent responds:** "Here's how to use React hooks in Next.js..." (with accurate docs)
+
 ## Progressive Disclosure
 
 ### Level 1: System Prompt (Once per conversation)
 ```markdown
 ## Available Skills
-- **weather**: Get weather forecasts
-- **pptx**: Create presentations
+- **context7-docs-lookup**: Look up documentation
 ```
 **Cost:** ~200 tokens, sent ONCE
 
 ### Level 2: On-Demand Instructions
 ```python
-load_skill("pptx")  # Returns full SKILL.md
+load_skill("context7-docs-lookup")  # Returns full SKILL.md
 ```
 **Cost:** 0 tokens until loaded
 
 ### Level 3: Referenced Resources  
 ```python
-read_skill_file("pptx", "references/api.md")
+read_skill_file("context7-docs-lookup", "references/api.md")
 ```
 **Cost:** 0 tokens until accessed
 
+## Three Universal Tools
+
+1. **`load_skill(skill_name)`** - Returns SKILL.md body without frontmatter
+2. **`read_skill_file(skill_name, file_path)`** - Returns specific resource file
+3. **`list_skill_files(skill_name, subdirectory?)`** - Lists available resources
+
 ## Generate Metadata
 
 For Onyx or other MCP clients that support system prompts:
 
 ```bash
-skills-mcp --generate-metadata /path/to/skills
-```
+# Markdown format (default)
+progressive-skills-mcp --generate-metadata
 
-Output:
-```markdown
-## Available Skills
-
-You have access to specialized skills...
-
-- **test-skill**: A simple test skill
-- **weather**: Get weather forecasts
-```
-
-## Installation
-
-```bash
-pip install skills-mcp
+# JSON format
+progressive-skills-mcp --generate-metadata --format json
 ```
 
-Or use with `uv`:
-```bash
-uv tool install skills-mcp
+JSON output:
+```json
+[
+  {
+    "name": "context7-docs-lookup",
+    "description": "Look up documentation from Context7 for libraries and frameworks",
+    "allowed_tools": []
+  }
+]
 ```
 
 ## Usage
 
 ```bash
-# Run MCP server
-skills-mcp /path/to/skills
+# Run MCP server with bundled skills
+progressive-skills-mcp
+
+# Run with custom skills directory
+progressive-skills-mcp /path/to/skills
 
 # Generate metadata
-skills-mcp --generate-metadata /path/to/skills
+progressive-skills-mcp --generate-metadata
 
 # Generate JSON metadata
-skills-mcp --generate-metadata --format json /path/to/skills
+progressive-skills-mcp --generate-metadata --format json
 
 # List discovered skills
-skills-mcp --list-skills /path/to/skills
+progressive-skills-mcp --list-skills
 ```
 
 ## Skill Format
@@ -196,19 +258,12 @@ description: Brief description
 Detailed skill instructions here...
 ```
 
-## Building Docker Image
-
-```bash
-docker build -t flowtrica/skills-mcp:latest .
-docker push flowtrica/skills-mcp:latest
-```
-
 ## Token Efficiency Comparison
 
 | Approach | Tools/Request | Tokens/Request | 20 Skills |
 |----------|--------------|----------------|-----------|
 | Original | 20 tools | ~100 each | 2000 tokens |
-| **Skills MCP** | **3 tools** | **~50 each** | **150 tokens** |
+| **Progressive Skills MCP** | **3 tools** | **~50 each** | **150 tokens** |
 | **Improvement** | | | **13x better!** 🎉 |
 
 ## License
@@ -223,6 +278,6 @@ MIT (same as original skillz)
 
 ## Links
 
-- Original skillz: https://github.com/intellectronica/skillz
+- GitHub: https://github.com/Flowtrica/skills-mcp
+- PyPI: https://pypi.org/project/progressive-skills-mcp/
 - Skills repo: https://github.com/Flowtrica/agent-skills
-- Docker Hub: https://hub.docker.com/r/flowtrica/skills-mcp

progressive_skills_mcp-0.2.2/README.md

@@ -0,0 +1,242 @@
+# Progressive Skills MCP
+
+MCP server for SKILL.md files with **progressive disclosure** - achieving **13x token efficiency** over traditional approaches.
+
+Based on [intellectronica/skillz](https://github.com/intellectronica/skillz) with progressive disclosure modifications inspired by Claude.ai's approach.
+
+## What's Different?
+
+**Original skillz:**
+- Creates 1 tool per skill
+- 20 skills = 20 tools × ~100 tokens = **2000 tokens/request**
+
+**Progressive Skills MCP:**
+- Creates 3 universal tools (`load_skill`, `read_skill_file`, `list_skill_files`)
+- 20 skills = 3 tools × ~50 tokens = **150 tokens/request**
+- **13x improvement!** 🎉
+
+## Features
+
+✅ Progressive disclosure (3-level token efficiency)  
+✅ Metadata generation for system prompts  
+✅ Compatible with all SKILL.md format files  
+✅ Supports .zip and .skill archives  
+✅ Bundled skills ready to use  
+
+## Quick Start
+
+### Using uvx (Recommended)
+
+```bash
+uvx progressive-skills-mcp
+```
+
+### With MCPHub
+
+```json
+{
+  "mcpServers": {
+    "skills": {
+      "command": "uvx",
+      "args": ["progressive-skills-mcp"]
+    }
+  }
+}
+```
+
+### Using pip
+
+```bash
+pip install progressive-skills-mcp
+progressive-skills-mcp
+```
+
+## 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.
+
+### Step 1: Generate Metadata
+
+```bash
+progressive-skills-mcp --generate-metadata > skills-metadata.txt
+```
+
+This outputs:
+
+```markdown
+## Available Skills
+
+You have access to specialized skills that provide detailed instructions for specific tasks. When a task requires specialized knowledge or a specific workflow, use the `load_skill` tool to get the full instructions.
+
+### How to Use Skills
+
+1. Check if a skill is relevant to the user's request
+2. Call `load_skill("skill-name")` to get detailed instructions
+3. Follow the instructions in the skill
+4. Use `read_skill_file()` if the skill references additional resources
+
+**Available skills:**
+
+- **context7-docs-lookup**: Look up documentation from Context7 for libraries and frameworks
+```
+
+### Step 2: Add to Agent System Prompt
+
+Copy the metadata output and add it to your LLM agent's system prompt. For example, in **Onyx**, **LibreChat**, or **Open WebUI**:
+
+```
+You are a helpful AI assistant.
+
+[... other system prompt content ...]
+
+## Available Skills
+
+You have access to specialized skills that provide detailed instructions for specific tasks...
+
+- **context7-docs-lookup**: Look up documentation from Context7...
+```
+
+### Step 3: Agent Uses Skills
+
+When relevant, the agent will:
+
+1. **See skill in system prompt** → "context7-docs-lookup is available"
+2. **Call load_skill** → `load_skill("context7-docs-lookup")`
+3. **Receive full instructions** → Complete SKILL.md content
+4. **Follow instructions** → Execute the skill workflow
+
+### Example Conversation
+
+**User:** "How do I use React hooks in Next.js?"
+
+**Agent thinks:** *The context7-docs-lookup skill can help with documentation lookup*
+
+**Agent calls:** `load_skill("context7-docs-lookup")`
+
+**Agent receives:** Full skill instructions on how to use Context7 API
+
+**Agent executes:** Follows skill instructions to look up Next.js documentation
+
+**Agent responds:** "Here's how to use React hooks in Next.js..." (with accurate docs)
+
+## Progressive Disclosure
+
+### Level 1: System Prompt (Once per conversation)
+```markdown
+## Available Skills
+- **context7-docs-lookup**: Look up documentation
+```
+**Cost:** ~200 tokens, sent ONCE
+
+### Level 2: On-Demand Instructions
+```python
+load_skill("context7-docs-lookup")  # Returns full SKILL.md
+```
+**Cost:** 0 tokens until loaded
+
+### Level 3: Referenced Resources  
+```python
+read_skill_file("context7-docs-lookup", "references/api.md")
+```
+**Cost:** 0 tokens until accessed
+
+## Three Universal Tools
+
+1. **`load_skill(skill_name)`** - Returns SKILL.md body without frontmatter
+2. **`read_skill_file(skill_name, file_path)`** - Returns specific resource file
+3. **`list_skill_files(skill_name, subdirectory?)`** - Lists available resources
+
+## Generate Metadata
+
+For Onyx or other MCP clients that support system prompts:
+
+```bash
+# Markdown format (default)
+progressive-skills-mcp --generate-metadata
+
+# JSON format
+progressive-skills-mcp --generate-metadata --format json
+```
+
+JSON output:
+```json
+[
+  {
+    "name": "context7-docs-lookup",
+    "description": "Look up documentation from Context7 for libraries and frameworks",
+    "allowed_tools": []
+  }
+]
+```
+
+## Usage
+
+```bash
+# Run MCP server with bundled skills
+progressive-skills-mcp
+
+# Run with custom skills directory
+progressive-skills-mcp /path/to/skills
+
+# Generate metadata
+progressive-skills-mcp --generate-metadata
+
+# Generate JSON metadata
+progressive-skills-mcp --generate-metadata --format json
+
+# List discovered skills
+progressive-skills-mcp --list-skills
+```
+
+## Skill Format
+
+Skills can be:
+- **Directories** with SKILL.md file
+- **Zip archives** containing SKILL.md
+- **.skill archives**
+
+Example structure:
+```
+skills/
+├── weather/
+│   ├── SKILL.md
+│   └── references/
+│       └── api.md
+└── pptx.zip
+```
+
+SKILL.md format:
+```markdown
+---
+name: skill-name
+description: Brief description
+---
+
+# Full Instructions
+
+Detailed skill instructions here...
+```
+
+## Token Efficiency Comparison
+
+| Approach | Tools/Request | Tokens/Request | 20 Skills |
+|----------|--------------|----------------|-----------|
+| Original | 20 tools | ~100 each | 2000 tokens |
+| **Progressive Skills MCP** | **3 tools** | **~50 each** | **150 tokens** |
+| **Improvement** | | | **13x better!** 🎉 |
+
+## License
+
+MIT (same as original skillz)
+
+## Credits
+
+- Based on [skillz](https://github.com/intellectronica/skillz) by Eleanor Berger
+- Progressive disclosure modifications by Flowtrica
+- Inspired by Claude.ai's skills system
+
+## Links
+
+- GitHub: https://github.com/Flowtrica/skills-mcp
+- PyPI: https://pypi.org/project/progressive-skills-mcp/
+- Skills repo: https://github.com/Flowtrica/agent-skills

{progressive_skills_mcp-0.2.0 → progressive_skills_mcp-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "progressive-skills-mcp"
-version = "0.2.0"
+version = "0.2.2"
 description = "MCP server that exposes Claude-style skills to any MCP client."
 readme = "README.md"
 authors = [

{progressive_skills_mcp-0.2.0 → progressive_skills_mcp-0.2.2}/src/progressive_skills_mcp/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

progressive_skills_mcp-0.2.0/README.md

@@ -1,187 +0,0 @@
-# Skills MCP
-
-MCP server for SKILL.md files with **progressive disclosure** - achieving **13x token efficiency** over traditional approaches.
-
-Based on [intellectronica/skillz](https://github.com/intellectronica/skillz) with progressive disclosure modifications inspired by Claude.ai's approach.
-
-## What's Different?
-
-**Original skillz:**
-- Creates 1 tool per skill
-- 20 skills = 20 tools × ~100 tokens = **2000 tokens/request**
-
-**Skills MCP (this fork):**
-- Creates 3 universal tools (`load_skill`, `read_skill_file`, `list_skill_files`)
-- 20 skills = 3 tools × ~50 tokens = **150 tokens/request**
-- **13x improvement!** 🎉
-
-## Features
-
-✅ Progressive disclosure (3-level token efficiency)  
-✅ Metadata generation for system prompts  
-✅ Compatible with all SKILL.md format files  
-✅ Supports .zip and .skill archives  
-✅ Docker image available  
-
-## Quick Start
-
-### Using Docker
-
-```bash
-docker run -i --rm \
-  -v /path/to/skills:/skills \
-  flowtrica/skills-mcp:latest \
-  /skills
-```
-
-### Using uvx
-
-```bash
-uvx skills-mcp@latest /path/to/skills
-```
-
-### With MCPHub
-
-```json
-{
-  "mcpServers": {
-    "skills": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "--entrypoint", "sh",
-        "flowtrica/skills-mcp:latest",
-        "-c",
-        "git clone https://github.com/YOUR_USERNAME/your-skills.git /tmp/skills && skills-mcp /tmp/skills"
-      ]
-    }
-  }
-}
-```
-
-## Progressive Disclosure
-
-### Level 1: System Prompt (Once per conversation)
-```markdown
-## Available Skills
-- **weather**: Get weather forecasts
-- **pptx**: Create presentations
-```
-**Cost:** ~200 tokens, sent ONCE
-
-### Level 2: On-Demand Instructions
-```python
-load_skill("pptx")  # Returns full SKILL.md
-```
-**Cost:** 0 tokens until loaded
-
-### Level 3: Referenced Resources  
-```python
-read_skill_file("pptx", "references/api.md")
-```
-**Cost:** 0 tokens until accessed
-
-## Generate Metadata
-
-For Onyx or other MCP clients that support system prompts:
-
-```bash
-skills-mcp --generate-metadata /path/to/skills
-```
-
-Output:
-```markdown
-## Available Skills
-
-You have access to specialized skills...
-
-- **test-skill**: A simple test skill
-- **weather**: Get weather forecasts
-```
-
-## Installation
-
-```bash
-pip install skills-mcp
-```
-
-Or use with `uv`:
-```bash
-uv tool install skills-mcp
-```
-
-## Usage
-
-```bash
-# Run MCP server
-skills-mcp /path/to/skills
-
-# Generate metadata
-skills-mcp --generate-metadata /path/to/skills
-
-# Generate JSON metadata
-skills-mcp --generate-metadata --format json /path/to/skills
-
-# List discovered skills
-skills-mcp --list-skills /path/to/skills
-```
-
-## Skill Format
-
-Skills can be:
-- **Directories** with SKILL.md file
-- **Zip archives** containing SKILL.md
-- **.skill archives**
-
-Example structure:
-```
-skills/
-├── weather/
-│   ├── SKILL.md
-│   └── references/
-│       └── api.md
-└── pptx.zip
-```
-
-SKILL.md format:
-```markdown
----
-name: skill-name
-description: Brief description
----
-
-# Full Instructions
-
-Detailed skill instructions here...
-```
-
-## Building Docker Image
-
-```bash
-docker build -t flowtrica/skills-mcp:latest .
-docker push flowtrica/skills-mcp:latest
-```
-
-## Token Efficiency Comparison
-
-| Approach | Tools/Request | Tokens/Request | 20 Skills |
-|----------|--------------|----------------|-----------|
-| Original | 20 tools | ~100 each | 2000 tokens |
-| **Skills MCP** | **3 tools** | **~50 each** | **150 tokens** |
-| **Improvement** | | | **13x better!** 🎉 |
-
-## License
-
-MIT (same as original skillz)
-
-## Credits
-
-- Based on [skillz](https://github.com/intellectronica/skillz) by Eleanor Berger
-- Progressive disclosure modifications by Flowtrica
-- Inspired by Claude.ai's skills system
-
-## Links
-
-- Original skillz: https://github.com/intellectronica/skillz
-- Skills repo: https://github.com/Flowtrica/agent-skills
-- Docker Hub: https://hub.docker.com/r/flowtrica/skills-mcp