Skill Management MCP Server

A Model Context Protocol (MCP) server that enables Claude to manage skills stored in ~/.skill-mcp/skills. This system allows Claude to create, edit, run, and manage skills programmatically, including execution of skill scripts with environment variables.

Quick Status

Status: ✅ Production Ready Test Coverage: 86% (145/145 tests passing) Deployed: October 18, 2025 Architecture: 22-module modular Python package with unified CRUD architecture

Overview

TL;DR: Write Python code that unifies multiple skills in one execution - follows Anthropic's MCP pattern for 98.7% more efficient agents.

This project consists of two main components:

1. MCP Server (src/skill_mcp/server.py) - A Python package providing 5 unified CRUD tools for skill management
2. Skills Directory (~/.skill-mcp/skills/) - Where you store and manage your skills

Key Advantages

🚀 Unified Multi-Skill Execution (Code Execution with MCP)

Build once, compose everywhere - Execute Python code that seamlessly combines multiple skills in a single run:

# One execution, multiple skills unified!
# Imports from calculator, data-processor, and weather skills
from math_utils import calculate_average          # calculator skill
from json_fetcher import fetch_json                # data-processor skill
from weather_api import get_forecast               # weather skill

# Fetch weather data
weather = fetch_json('https://api.weather.com/cities')

# Calculate averages using calculator utilities
temps = [city['temp'] for city in weather['cities']]
avg_temp = calculate_average(temps)

# Get detailed forecast
forecast = get_forecast('London')
print(f"Average temperature: {avg_temp}°F")
print(f"London forecast: {forecast}")

What makes this powerful:

• ✅ Context-efficient - Dependencies and env vars auto-aggregated from all referenced skills
• ✅ Composable - Mix and match utilities from any skill like building blocks
• ✅ No redundancy - Declare PEP 723 dependencies once in library skills, reuse everywhere
• ✅ Progressive disclosure - Load only the skills you need, when you need them
• ✅ Follows Anthropic's MCP pattern - Code execution with MCP for efficient agents

Efficiency gains:

• 📉 98.7% fewer tokens when discovering tools progressively vs loading all upfront
• 🔄 Intermediate results stay in code - Process large datasets without bloating context
• ⚡ Single execution - Complex multi-step workflows in one code block instead of chained tool calls

This aligns with Anthropic's research showing agents scale better by writing code to call tools rather than making direct tool calls for each operation.

🔓 Not Locked to Claude UI

Unlike the Claude interface, this system uses the Model Context Protocol (MCP), which is:

• ✅ Universal - Works with Claude Desktop, claude.ai, Cursor, and any MCP-compatible client
• ✅ Not tied to Claude - Same skills work everywhere MCP is supported
• ✅ Future-proof - Not dependent on Claude's ecosystem or policy changes
• ✅ Local-first - Full control over your skills and data

🎯 Use Skills Everywhere

Your skills can run in:

• Cursor - IDE integration with MCP support
• Claude Desktop - Native app with MCP access
• claude.ai - Web interface with MCP support
• Any MCP client - Growing ecosystem of compatible applications

📦 Independent & Modular

• ✅ Each skill is self-contained with its own files, scripts, and environment
• ✅ No dependency on proprietary Claude features
• ✅ Can be versioned, shared, and reused across projects
• ✅ Standard MCP protocol ensures compatibility

🔄 Share Skills Across All MCP Clients

• ✅ One skill directory, multiple clients - Create once, use everywhere
• ✅ Same skills in Cursor and Claude - No duplication needed
• ✅ Seamless switching - Move between tools without reconfiguring
• ✅ Consistent experience - Skills work identically across all MCP clients
• ✅ Centralized management - Update skills in one place, available everywhere

🤖 LLM-Managed Skills (No Manual Copy-Paste)

Instead of manually copying, zipping, and uploading files:

❌ OLD WAY: Manual process
   1. Create skill files locally
   2. Zip the skill folder
   3. Upload to Claude interface
   4. Wait for processing
   5. Can't easily modify or version

✅ NEW WAY: LLM-managed programmatically
   1. Tell Claude: "Create a new skill called 'data-processor'"
   2. Claude creates the skill directory and SKILL.md
   3. Tell Claude: "Add a Python script to process CSVs"
   4. Claude creates and tests the script
   5. Tell Claude: "Set the API key for this skill"
   6. Claude updates the .env file
   7. Tell Claude: "Run the script with this data"
   8. Claude executes it and shows results - all instantly!

Key Benefits:

• ✅ No manual file operations - LLM handles creation, editing, deletion
• ✅ Instant changes - No upload/download/reload cycles
• ✅ Full version control - Skills are regular files, can use git
• ✅ Easy modification - LLM can edit scripts on the fly
• ✅ Testable - LLM can create and run scripts immediately
• ✅ Collaborative - Teams can develop skills together via MCP

Features

Skill Management

• ✅ List all available skills
• ✅ Browse skill files and directory structure
• ✅ Read skill files (SKILL.md, scripts, references, assets)
• ✅ Create new skill files and directories
• ✅ Update existing skill files
• ✅ Delete skill files

Script Execution

• ✅ Run Python, Bash, and other executable scripts
• ✅ Automatic dependency management for Python scripts using uv inline metadata (PEP 723)
• ✅ Automatic environment variable injection from secrets
• ✅ Command-line argument support
• ✅ Custom working directory support
• ✅ Capture stdout and stderr
• ✅ 30-second timeout for safety

Direct Python Execution - Multi-Skill Unification 🚀

• ✅ UNIFY MULTIPLE SKILLS in one execution - Combine utilities from different skills seamlessly
• ✅ Execute Python code directly without creating script files
• ✅ Cross-skill imports - Import modules from ANY skill as reusable libraries
• ✅ Automatic dependency aggregation - Dependencies from ALL imported skills auto-merged
• ✅ Environment variable loading - .env files from ALL referenced skills auto-loaded
• ✅ PEP 723 support - Inline dependency declarations in code
• ✅ 98.7% more efficient - Follows Anthropic's recommended MCP pattern for scalable agents
• ✅ Perfect for multi-skill workflows, quick experiments, data analysis, and complex pipelines

Environment Variables

• ✅ List environment variable keys (secure - no values shown)
• ✅ Set or update environment variables per skill
• ✅ Persistent storage in per-skill .env files
• ✅ Automatic injection into script execution

Directory Structure

~/.skill-mcp/
└── skills/                       # Your skills directory
    ├── example-skill/
    │   ├── SKILL.md             # Required: skill definition
    │   ├── .env                 # Optional: skill-specific environment variables
    │   ├── scripts/             # Optional: executable scripts
    │   ├── references/          # Optional: documentation
    │   └── assets/              # Optional: templates, files
    └── another-skill/
        ├── SKILL.md
        └── .env

Note: The MCP server is installed via uvx from PyPI and runs automatically. No local server file needed!

Quick Start

1. Install uv

This project uses uv for fast, reliable Python package management.

# Install uv (includes uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Configure Your MCP Client

Add the MCP server to your configuration. The server will be automatically downloaded and run via uvx from PyPI.

Claude Desktop - Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor - Edit the config file:

• macOS: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json
• Linux: ~/.cursor/mcp.json

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ]
    }
  }
}

That's it! No installation needed - uvx will automatically download and run the latest version from PyPI.

3. Restart Your MCP Client

Restart Claude Desktop or Cursor to load the MCP server.

4. Test It

In a new conversation:

List all available skills

Claude should use the skill-mcp tools to show skills in ~/.skill-mcp/skills/.

Common uv Commands

For development in this repository:

uv sync              # Install/update dependencies
uv run python script.py   # Run Python with project environment
uv add package-name  # Add a new dependency
uv pip list          # Show installed packages
uv run pytest tests/ -v   # Run tests

Note: uv automatically creates and manages .venv/ - no need to manually create virtual environments!

Script Dependencies (PEP 723)

✅ BOTH run_skill_script AND execute_python_code support PEP 723!

Python scripts and code can declare their own dependencies using uv's inline metadata. The server automatically detects this and uses uv run to handle dependencies:

#!/usr/bin/env python3
# /// script
# dependencies = [
#   "requests>=2.31.0",
#   "pandas>=2.0.0",
# ]
# ///

import requests
import pandas as pd

# Your script code here - dependencies are automatically installed!
response = requests.get("https://api.example.com/data")
df = pd.DataFrame(response.json())
print(df.head())

Benefits:

• ✅ No manual dep

---