Mcp Skillset

mcp-skillset

[](https://badge.fury.io/py/mcp-skillset) [](https://pypi.org/project/mcp-skillset/) [](https://opensource.org/licenses/MIT) [](https://github.com/bobmatnyc/mcp-skillset)

Dynamic RAG-powered skills for code assistants via Model Context Protocol (MCP)

mcp-skillset is a standalone Python application that provides intelligent, context-aware skills to code assistants through hybrid RAG (vector + knowledge graph). Unlike static skills that load at startup, mcp-skillset enables runtime skill discovery, automatic recommendations based on your project's toolchain, and dynamic loading optimized for your workflow.

Key Features

• 🚀 Zero Config: mcp-skillset setup handles everything automatically
• 🧠 Intelligent: Auto-detects your project's toolchain (Python, TypeScript, Rust, Go, etc.)
• 🔍 Dynamic Discovery: Vector similarity + knowledge graph for better skill finding
• 📦 Multi-Source: Pulls skills from multiple git repositories
• ⚡ On-Demand Loading: Skills loaded when needed, not all at startup
• 🔌 MCP Native: First-class Model Context Protocol integration
• 🔒 Security First: Multi-layer defense against prompt injection and malicious skills
• 🌐 agentskills.io Compatible: Supports both native and agentskills.io specification formats

Security

MCP Skillset implements comprehensive security validation to protect against malicious skills from public repositories.

Security Features

• 🛡️ Prompt Injection Detection: Automatic detection of instruction override attempts, role hijacking, and context escape
• 🔍 Threat Classification: Multi-level threat detection (BLOCKED, DANGEROUS, SUSPICIOUS)
• 🏷️ Repository Trust Levels: TRUSTED (official), VERIFIED (community), UNTRUSTED (public)
• 📏 Size Limits: DoS prevention through content size enforcement
• 🎯 Content Sanitization: All skills wrapped in clear boundaries to prevent context escape

Trust Levels

| Level | Description | Security Policy | |-------|-------------|-----------------| | TRUSTED | Official Anthropic repos | Minimal filtering (only BLOCKED threats) | | VERIFIED | Known community repos | Moderate filtering (BLOCKED + DANGEROUS) | | UNTRUSTED | Public repos (default) | Strict filtering (all threats) |

Quick Security Check

# Skills from public repos are automatically validated
mcp-skillset search "python testing"

# View security details in logs
mcp-skillset --debug search "python testing"

For detailed security information, threat models, and best practices, see [SECURITY.md](./SECURITY.md).

Installation

Prerequisites

• Python 3.11 or higher
• Claude Code (for Claude Code integration) with claude CLI available

With Homebrew (macOS/Linux)

The easiest way to install on macOS or Linux:

brew tap bobmatnyc/tools
brew install mcp-skillset

With uv (Recommended - Fastest)

uv is the fastest way to install Python applications:

uv tool install mcp-skillset

With pipx (Alternative)

pipx is a reliable alternative for installing Python CLI applications:

pipx install mcp-skillset

With pip (Fallback)

Standard pip installation (not recommended for CLI tools):

pip install mcp-skillset

From Source

git clone https://github.com/bobmatnyc/mcp-skillset.git
cd mcp-skillset
uv sync

Local Development (Without Installation)

For development, you can run mcp-skillset directly from source without installing:

# Use the development script
./mcp-skillset-dev --help
./mcp-skillset-dev search "python testing"
./mcp-skillset-dev setup --auto

The mcp-skillset-dev script:

• Runs the package from source code (not installed version)
• Uses local virtual environment if available
• Sets up PYTHONPATH automatically
• Passes all arguments through to the CLI

This is useful for:

• Testing changes without reinstalling
• Developing new features
• Debugging with source code
• Contributing to the project

Note: For production use, install the package normally with uv tool install mcp-skillset or pipx install mcp-skillset.

First-Run Requirements

Important: On first run, mcp-skillset will automatically download a ~90MB sentence-transformer model (all-MiniLM-L6-v2) for semantic search. This happens during the initial mcp-skillset setup or when you first run any command that requires indexing.

Requirements:

• ✅ Active internet connection
• ✅ ~100MB free disk space
• ✅ 2-5 minutes for initial download (depending on connection speed)

Model Caching:

• Models are cached in ~/.cache/huggingface/ for future use
• Subsequent runs use the cached model (no download required)
• The cache persists across mcp-skillset updates

Building Progressive Skills

mcp-skillset now includes the ability to create custom progressive skills that become immediately available to Claude Code and other AI assistants. Skills are stored in ~/.claude/skills/ and loaded automatically.

What are Progressive Skills?

Progressive skills are modular capabilities that:

• Load in two stages: Lightweight metadata (~100 tokens) at startup, full body (> ~/.bashrc

source ~/.bashrc

**Zsh** (macOS default):
```zsh
eval "$(_MCP_SKILLS_COMPLETE=zsh_source mcp-skillset)" >> ~/.zshrc
source ~/.zshrc

Fish:

echo 'eval (env _MCP_SKILLS_COMPLETE=fish_source mcp-skillset)' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Features

• ✅ Complete all commands and subcommands
• ✅ Complete option flags (--help, --limit, etc.)
• ✅ Works with mcp-skillset, mcp-skillset repo, and all other commands

Verification

Test completions are working:

mcp-skillset         # Shows: config health index info list mcp recommend repo search setup stats
mcp-skillset repo    # Shows: add list update
mcp-skillset search --  # Shows: --category --help --limit

Documentation

For detailed installation instructions, troubleshooting, and advanced usage, see [docs/SHELLCOMPLETIONS.md](docs/SHELLCOMPLETIONS.md).

MCP Tools

mcp-skillset provides 7 MCP tools for AI assistants:

1. skills_search - Semantic search with hybrid RAG (vector + knowledge graph)
2. skill_get - Retrieve complete skill details by ID
3. skills_recommend - Context-aware skill recommendations based on project toolchain
4. skill_categories - Browse available skill categories and toolchains
5. skills_reindex - Rebuild search indices (vector store + knowledge graph)
6. skilltemplateslist - List available skill templates for progressive skill creation
7. skill_create - Create progressive skills from templates and deploy to ~/.claude/skills/

Tool Details

1. skills_search

Natural language semantic search over all indexed skills using hybrid RAG.

Parameters:

• query (required): Search query string
• limit (optional): Maximum number of results (default: 10)
• category (optional): Filter by skill category

Returns: Array of matching skills with relevance scores

Example:

# Search for testing skills
results = await skills_search(
    query="python unit testing frameworks",
    limit=5
)

# Search with category filter
results = await skills_search(
    query="debugging",
    category="Python"
)

2. skill_get

Retrieve complete skill details and instructions by skill ID.

Parameters:

• skill_id (required): Unique skill identifier

Returns: Full skill object with instructions, metadata, and examples

Example:

# Get specific skill details
skill = await skill_get(skill_id="pytest-fixtures")

# Use skill instructions
print(skill.instructions)

3. skills_recommend

Get intelligent skill recommendations based on project toolchain detection.

Parameters: None (auto-detects current project)

Returns: Array of recommended skills ranked by relevance to detected toolchain

Example:

# Get recommendations for current project
recommendations = await skills_recommend()

# Returns skills relevant to detected languages, frameworks, and tools

4. skill_categories

List all available skill categories and toolchain associations.

Parameters: None

Returns: Array of category names with skill counts

Example:

# List all categories
categories = await skill_categories()

# Returns: ["Python", "Testing", "Debugging", "Web Development", ...]

5. skills_reindex

Rebuild vector store and knowledge graph indices from skill repositories.

Parameters:

• force (optional): Force full reindex (default: false)

Returns: Indexing status and statistics

Example:

# Incremental reindex (only new/changed skills)
status = await skills_reindex()

# Force full reindex
status = await skills_reindex(force=True)

6. skilltemplateslist

List available skill templates with descriptions and use cases.

Parameters: None

Returns: Array of templates with metadata (name, description, bestfor, usecases)

Example:

templates = await skill_templates_list()
# Returns: [
#   {
#     "name": "web-development",
#     "description": "Full-stack web development patterns",
#     "best_for": "Web applications",
#     "use_cases": ["Frontend", "Backend", "Full-stack"]
#   },
#   ...
# ]

7. skill_create

Create progressive skills from templates. Skills are deployed to ~/.claude/skills/ for immediate use.

Parameters:

• name (required): Skill name
• description (required): What the skill does
• domain (required): Category (e.g., "web development")
• tags (optional): List of keywords
• template (optional): Template choice (web-development, api-development, testing, base)
• deploy (optional): Whether to deploy (default: true)

Returns: Status, skillid, skillpath, validation results

Example:

result = await skill_create(
    name="FastAPI Testing",
    description="Comprehensive testing strategies for FastAPI applications",
    domain="web development",
    tags=["fastapi", "pytest", "testing"],
    template="web-development",
    deploy=True
)

Development

Requirements

• Python 3.11+
• Git
• uv (recommended) or pip

Setup Development Environment

git clone https://github.com/bobmatnyc/mcp-skillset.git
cd mcp-skillset

# Recommended: Use uv for fastest setup
uv sync

# Alternative: Use pip
pip install -e ".[dev]"

Running from Source (Development Mode)

Use the ./mcp-skillset-dev script to run commands directly from source without installation:

# Run any CLI command
./mcp-skillset-dev --version
./mcp-skillset-dev search "debugging"
./mcp-skillset-dev serve --dev

# All arguments pass through
./mcp-skillset-dev info systematic-debugging

How it works:

1. Sets PYTHONPATH to include src/ directory
2. Activates local .venv if present
3. Runs python -m mcp_skills.cli.main with all arguments

When to use:

• ✅ Rapid iteration during development
• ✅ Testing changes without reinstalling
• ✅ Debugging with source code modifications
• ❌ Production deployments (use pip install instead)

Installed vs. Source:

# Installed version (from pip install -e .)
mcp-skillset search "testing"

# Source version (no installation required)
./mcp-skillset-dev search "testing"

Run Tests

# With uv (recommended)
uv run pytest

# With coverage
uv run pytest --cov

# Or use make
make quality

Performance Benchmarks

mcp-skillset includes comprehensive performance benchmarks to track and prevent regressions:

# Run all benchmarks (includes slow tests)
make benchmark

# Run fast benchmarks only (skip 10k skill tests)
make benchmark-fast

# Compare current performance with baseline
make benchmark-compare

Benchmark Categories:

• Indexing Performance: Measure time to index 100, 1000, and 10000 skills
• Search Performance: Track query latency (p50, p95, p99) for vector and hybrid search
• Database Performance: Benchmark SQLite operations (lookup, query, batch insert)
• Memory Usage: Monitor memory consumption during large-scale operations

Baseline Thresholds:

• Index 100 skills: /dev/null

# Add to PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.) export PATH="/path/to/claude/bin:$PATH" ```

1. Verify CLI is working:

``bash claude --version claude mcp list ``

1. Fallback option: Use --skip-agents flag and configure manually:

``bash mcp-skillset setup --skip-agents # Then use: mcp-skillset install --agent claude-desktop ``

Model Download Issues

If you encounter problems downloading the embedding model on first run:

1. Check Internet Connection

The model is downloaded from HuggingFace Hub. Verify you can reach:

curl -I https://huggingface.co

2. Manual Model Download

Pre-download the model manually if automatic download fails:

python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

This downloads the model to ~/.cache/huggingface/ and verifies it works.

3. Proxy Configuration

If behind a corporate proxy, configure environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export HF_ENDPOINT=https://huggingface.co  # Or your mirror

4. Offline/Air-Gapped Installation

For environments without internet access:

On a machine with internet:

1. Download the model:

``bash python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')" ``

1. Package the model cache:

``bash cd ~/.cache/huggingface tar -czf sentence-transformers-model.tar.gz hub/ ``

On the air-gapped machine:

1. Transfer sentence-transformers-model.tar.gz to the target machine

1. Extract to the HuggingFace cache directory:

``bash mkdir -p ~/.cache/huggingface cd ~/.cache/huggingface tar -xzf /path/to/sentence-transformers-model.tar.gz ``

1. Install mcp-skillset (transfer wheel if needed):

``bash pip install mcp-skillset # Or install from wheel ``

1. Verify the setup:

``bash mcp-skillset doctor ``

5. Custom Cache Location

If you need to use a different cache directory:

export HF_HOME=/custom/path/to/cache
export TRANSFORMERS_CACHE=/custom/path/to/cache
mcp-skillset setup

6. Disk Space Issues

Check available space in the cache directory:

df -h ~/.cache/huggingface

The model requires ~90MB, but allow ~100MB for temporary files during download.

7. Permission Issues

Ensure the cache directory is writable:

mkdir -p ~/.cache/huggingface
chmod 755 ~/.cache/huggingface

Common Issues

"Connection timeout" during model download

• Check internet connection and firewall settings
• Try manual download (see step 2 above)
• Configure proxy if behind corporate network (see step 3 above)

"No space left on device"

• Check disk space: df -h ~/.cache
• Clear old HuggingFace cache: rm -rf ~/.cache/huggingface/*
• Use custom cache location (see step 5 above)

"Permission denied" on cache directory

• Fix permissions: chmod 755 ~/.cache/huggingface
• Or use custom cache location with proper permissions

Slow initial setup

• First run downloads ~90MB and builds indices
• Expected time: 2-10 minutes depending on connection speed and number of skills
• Subsequent runs use cached model and are much faster

Getting Help

If you encounter issues not covered here:

1. Check GitHub Issues
2. Review logs: ~/.mcp-skillset/logs/
3. Run health check: mcp-skillset doctor
4. Open a new issue with

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bobmatnyc
• Source: bobmatnyc/mcp-skillset
• License: MIT

Install and usage instructions live in the source repository linked above.