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

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

Quick Security Check

For detailed security information, threat models, and best practices, see 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:

With uv (Recommended - Fastest)

uv is the fastest way to install Python applications:

With pipx (Alternative)

pipx is a reliable alternative for installing Python CLI applications:

With pip (Fallback)

Standard pip installation (not recommended for CLI tools):

From Source

Local Development (Without Installation)

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

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 (<5k tokens) when activated

• Auto-activate based on project context (toolchain, frameworks, keywords)

• Persist across sessions - once created, always available

• Follow best practices - templates ensure quality and consistency

Creating Skills

CLI: Interactive Mode (Recommended)

You'll be prompted for:

• Name: Skill identifier (e.g., "FastAPI Testing")

• Description: What it does and when to use it

• Domain: Category (e.g., "web development")

• Tags: Keywords for discovery (e.g., "fastapi,pytest,testing")

• Template: Choose from specialized templates

CLI: Command-Line Mode

CLI: Preview Mode

Preview the generated skill without deploying:

MCP Tool (For AI Agents)

Available Templates

Note: The base template is currently recommended for advanced users only due to validation limitations. Use specialized templates for production skills.

Examples

Creating a FastAPI testing skill:

Creating a GraphQL API skill:

Creating a TDD workflow skill:

Deployment

Skills are automatically deployed to ~/.claude/skills/skill-name/SKILL.md and become immediately available to:

• Claude Code (VS Code extension)

• Claude Desktop (standalone app)

• Auggie (if configured)

Skill Structure

Generated skills include:

• YAML Frontmatter: Metadata (name, description, tags, version)

• Overview: What the skill does

• When to Use: Activation context

• Core Principles: Best practices with examples

• Common Patterns: Proven approaches

• Anti-Patterns: What to avoid

• Testing Strategies: Validation approaches

• Related Skills: Complementary skills

Next Steps

After creating skills:

1. Test activation: Start a project matching your skill's tags

2. Verify loading: Check that Claude references your skill

3. Iterate: Update skills based on usage

4. Share: Export skills for team use

For detailed documentation, see:

• API Reference: docs/skill-builder-usage.md

• Examples: examples/skill_builder_demo.py

• QA Report: QA_REPORT_SKILL_BUILDER.md

Quick Start

1. Setup

Run the interactive setup wizard to configure mcp-skillset for your project:

Note: The first run will download the embedding model (~90MB) before proceeding with setup. Allow 2-5 minutes for this initial download. Subsequent runs will be much faster.

This complete one-command setup will:

• Download embedding model (first run only)

• Detect your project's toolchain

• Clone relevant skill repositories

• Build vector + knowledge graph indices

• Configure MCP server integration

• Install and configure for all detected AI agents (Claude Desktop, Claude Code, Auggie)

  • For Claude Code: Uses the official claude mcp add CLI command

  • For other agents: Configures via JSON config files

• Validate the setup

Tip: Use mcp-skillset setup --skip-agents if you prefer to configure AI agents manually using the install command.

2. Explore Available Skills

Before diving in, explore what's available:

3. Start the MCP Server

The server will start and expose skills to your code assistant via MCP protocol.

4. Use with Claude Code

Skills are automatically available in Claude Code. Try:

• "What testing skills are available for Python?"

• "Show me debugging skills"

• "Recommend skills for my project"

• "Use the pytest-fixtures skill to help me write better tests"

Real-World Usage Scenarios

Scenario 1: Starting a New Python Project

Scenario 2: Debugging Production Issues

Scenario 3: Code Review Preparation

Scenario 4: Learning New Framework

Project Structure

Architecture

mcp-skillset uses a hybrid RAG approach combining:

Vector Store (ChromaDB):

• Fast semantic search over skill descriptions

• Embeddings generated with sentence-transformers

• Persistent local storage with minimal configuration

Knowledge Graph (NetworkX):

• Skill relationships and dependencies

• Category and toolchain associations

• Related skill discovery

Toolchain Detection:

• Automatic detection of programming languages

• Framework and build tool identification

• Intelligent skill recommendations

Configuration

Global Configuration (~/.mcp-skillset/config.yaml)

Hybrid Search Modes

The hybrid search system combines vector similarity (semantic search) with knowledge graph relationships (dependency traversal) to find relevant skills. You can tune the weighting to optimize for different use cases:

Available Presets:

When to use each mode:

• current (default): Best for most users. Proven through testing to work well for typical skill discovery patterns.

• semantic_focused: Use when you have vague requirements or want fuzzy semantic matching. Good for concept-based searches like "help me with error handling" or "testing strategies".

• graph_focused: Use when you want to explore skill ecosystems and dependencies. Perfect for "what else works with X?" queries.

• balanced: Use when you want equal emphasis on both approaches, or as a starting point for experimentation.

Configuration Examples:

CLI Override:

You can override the config file setting using the --search-mode flag:

Project Configuration (.mcp-skillset.yaml)

CLI Commands

mcp-skillset provides a rich, interactive CLI with comprehensive command-line options and beautiful terminal output powered by Rich and Questionary.

Quick Reference

Global options: --version, --verbose, --debug, --help

Core Commands

setup - Initial Configuration

Auto-configure mcp-skillset for your project with intelligent toolchain detection and automatic agent installation.

What it does:

• Downloads embedding model (~90MB, first run only)

• Detects project toolchain (Python, TypeScript, Rust, Go, etc.)

• Clones relevant skill repositories

• Builds vector + knowledge graph indices

• Configures MCP server integration

• Automatically installs and configures for all detected AI agents (Claude Desktop, Claude Code, Auggie)

• Validates setup completion

First-Run Note: Allow 2-5 minutes for initial model download. Subsequent runs are instant.

Agent Installation: The setup command now automatically detects and configures all supported AI agents on your system, providing a complete one-command installation experience similar to mcp-ticketer. Use --skip-agents if you prefer to configure agents manually with the install command.

config - Configuration Management

View or modify mcp-skillset configuration settings.

Configuration file: ~/.mcp-skillset/config.yaml

index - Rebuild Indices

Rebuild vector and knowledge graph indices from skill repositories.

Use cases:

• After adding new repositories with repo add

• When skill content has changed

• Troubleshooting search issues

• Switching embedding models

install - Agent Integration

Install MCP SkillSet configuration for AI agents with auto-detection.

Supported agents:

• claude-desktop - Claude Desktop App

• claude-code - Claude Code CLI

• auggie - Auggie AI Assistant

• all - Install for all detected agents

build-skill - Progressive Skill Creation

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

Parameters:

• --name (required in standard mode): Skill name

• --description (required in standard mode): What the skill does (min 20 chars)

• --domain (required in standard mode): Category (e.g., "web development")

• --tags (optional): Comma-separated keywords

• --template (optional): Template choice (default: base)

  • web-development - Full-stack web patterns

  • api-development - REST/GraphQL APIs

  • testing - TDD and testing workflows

  • base - Generic template (advanced users only)

• --interactive (optional): Interactive mode with prompts

• --preview (optional): Show generated content without deploying

• --no-deploy (optional): Disable automatic deployment

Available Templates:

• web-development: Frontend, backend, full-stack patterns ✅ Production ready

• api-development: REST, GraphQL, authentication ✅ Production ready

• testing: TDD, unit/integration/E2E testing ✅ Production ready

• base: Generic template ⚠️ Advanced users only (validation limitations)

Output:

• Skills deployed to: ~/.claude/skills/{skill-name}/SKILL.md

• Immediately available to Claude Code, Claude Desktop, and Auggie

• Validation results and warnings displayed

• Skill ID and path returned

See also: Building Progressive Skills section for examples and detailed usage.

mcp - MCP Server

Start the Model Context Protocol server for integration with code assistants.

Server details:

• Transport: stdio (standard input/output)

• Protocol: Model Context Protocol v1.0

• Tools exposed: skills_search, skill_get, skills_recommend, skill_categories, skills_reindex, skill_templates_list, skill_create

Search & Discovery Commands

search - Semantic Search

Search for skills using natural language queries with hybrid RAG (vector + knowledge graph).

Search modes:

• current (default) - 70% semantic, 30% graph

• semantic_focused - 90% semantic, 10% graph (best for fuzzy queries)

• graph_focused - 30% semantic, 70% graph (best for related skills)

• balanced - 50% semantic, 50% graph

Examples:

list - List All Skills

Display all available skills with filtering options.

Output formats:

• Default: Rich panels with descriptions

• Compact: Table view with ID, title, category

info / show - Skill Details

Show detailed information about a specific skill.

recommend - Smart Recommendations

Get intelligent skill recommendations based on your project's toolchain.

How it works:

1. Analyzes project directory (package.json, pyproject.toml, Cargo.toml, etc.)

2. Detects primary language and frameworks

3. Searches for relevant skills using detected toolchain

4. Ranks by relevance to your tech stack

Example output:

demo - Interactive Skill Explorer

Generate example prompts and explore skills interactively.

Features:

• Browse all skills with Rich menu

• Auto-generates relevant example questions

• Extracts key concepts from skill instructions

• Shows practical use cases

Example output:

Repository Management Commands

repo add - Add Repository

Add a new skill repository to your configuration.

Priority levels:

• 100: Highest (official repositories)

• 50: Medium (default, community repositories)

• 10: Low (experimental repositories)

repo list - List Repositories

Display all configured skill repositories.

Output includes:

• Repository URL

• Priority level

• Auto-update status

• Last update timestamp

• Number of skills indexed

repo update - Update Repositories

Pull latest changes from skill repositories.

Note: After updating, run mcp-skillset index --incremental to index new skills.

GitHub Discovery Commands

Automatically discover skill repositories on GitHub.

discover search - Search GitHub

Search GitHub for skill repositories using natural language queries.

Features:

• Natural language search queries

• Automatic SKILL.md verification

• Star count filtering

• Rich metadata display (stars, forks, topics, license)

discover trending - Get Trending Repos

Find recently updated skill repositories.

Timeframes: week, month, year

discover topic - Search by Topic

Search repositories by GitHub topic.

Common topics:

• claude-skills - Claude AI skills

• anthropic-skills - Anthropic skills

• mcp-skills - MCP protocol skills

• ai-skills - General AI skills

discover verify - Verify Repository

Verify that a repository contains SKILL.md files before adding.

Output includes:

• SKILL.md verification status

• Repository metadata (stars, forks, license)

• Topics and description

• Command to add repository if valid

discover limits - API Rate Limits

Check your current GitHub API rate limit status.

Rate limits:

• Unauthenticated: 60 requests/hour

• Authenticated (with token): 5000 requests/hour

To increase limits:

See also: GitHub Discovery Documentation for detailed usage and configuration.

Utility Commands

doctor - Health Check

Run comprehensive system health check and validation.

Checks performed:

• Configuration file validity

• Repository accessibility

• Index integrity (vector + knowledge graph)

• Embedding model availability

• Database connectivity

• Disk space and permissions

Example output:

stats - Usage Statistics

Display usage statistics and metrics.

Metrics displayed:

• Total skills indexed

• Skills by category

• Skills by repository

• Search query counts

• Most used skills

• Index size and memory usage

enrich - Prompt Enrichment

Enrich prompts with relevant skill context (advanced feature).

What it does:

1. Searches for relevant skills based on your prompt

2. Extracts key concepts and instructions from top matches

3. Augments your prompt with skill context

4. Outputs enriched prompt for use with LLMs

Global Options

All commands support these global flags:

Command Workflows

First-Time Setup Flow:

Daily Usage Pattern:

Adding New Skill Repository:

Shell Completions

Enable tab completion for the mcp-skillset command to speed up your workflow:

Quick Install

Bash (requires Bash 4.4+):

Zsh (macOS default):

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:

Documentation

For detailed installation instructions, troubleshooting, and advanced usage, see docs/SHELL_COMPLETIONS.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. skill_templates_list - 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:

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:

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:

4. skill_categories

List all available skill categories and toolchain associations.

Parameters: None

Returns: Array of category names with skill counts

Example:

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:

6. skill_templates_list

List available skill templates with descriptions and use cases.

Parameters: None

Returns: Array of templates with metadata (name, description, best_for, use_cases)

Example:

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, skill_id, skill_path, validation results

Example:

Development

Requirements

• Python 3.11+

• Git

• uv (recommended) or pip

Setup Development Environment

Running from Source (Development Mode)

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

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:

Run Tests

Performance Benchmarks

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

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: < 10 seconds

• Index 1000 skills: < 100 seconds

• Search query (p50): < 100ms

• Search query (p95): < 500ms

• SQLite lookup by ID: < 1ms

Benchmark Results:

• Results are saved to .benchmarks/ directory (git-ignored)

• Use make benchmark-compare to detect performance regressions

• CI/CD can be configured to fail on significant performance degradation

Example Output:

Linting and Formatting

Security Scanning

mcp-skillset includes comprehensive security scanning to identify vulnerabilities in dependencies and code:

Automated Security (Dependabot + GitHub Actions)

Dependabot automatically:

• Scans dependencies weekly for vulnerabilities

• Creates pull requests for security updates

• Groups minor/patch updates for easier review

GitHub Actions runs security scans on every push:

• Safety: Python dependency vulnerability scanner

• pip-audit: PyPI package vulnerability auditor

• Bandit: Python code security linter

• detect-secrets: Secret detection scanner

Manual Security Scanning

Security Reports

After running make security-check-full, reports are saved to .security-reports/:

• safety-report.json - Dependency vulnerabilities

• pip-audit-report.json - Package vulnerabilities

• bandit-report.json - Code security issues

Security Policy

For vulnerability reporting and security best practices, see .github/SECURITY.md.

Key security features:

• Automated dependency scanning (Dependabot)

• Weekly security scans (GitHub Actions)

• Pre-publish security gate

• Secret detection (detect-secrets)

• Code security linting (Bandit)

Documentation

Deployment & Release

See docs/DEPLOY.md for the complete deployment and release workflow, including:

• Automated release process with Claude MPM multi-agent coordination

• PyPI publishing with stored credentials

• Homebrew tap management (consolidated bobmatnyc/tools tap)

• Pre-release validation, quality gates, and security scanning

• Post-release verification across all channels

• Rollback procedures and troubleshooting

• Quick reference commands for next release

Architecture

See docs/architecture/README.md for detailed architecture design.

Skills Collections

See docs/skills/RESOURCES.md for a comprehensive index of skill repositories compatible with mcp-skillset, including:

• Official Anthropic skills

• Community collections (obra/superpowers, claude-mpm-skills, etc.)

• Toolchain-specific skills (Python, TypeScript, Rust, Go, Java)

• Operations & DevOps skills

• MCP servers that provide skill-like capabilities

Troubleshooting

Claude CLI Integration

"Claude CLI not found" error

Symptom: Setup or installation fails with "Claude CLI not found" error.

Solutions:

1. Verify Claude Code is installed:

   • Make sure Claude Code (VS Code extension) is installed and activated

   • Check that the extension is up to date

2. Check if :

   which claude

   • If the command is not found, reinstall Claude Code

   • On macOS, the CLI should be at: /usr/local/bin/claude or in your PATH

3. Add to PATH if necessary:

   # Find where Claude CLI is installed find /Applications -name "claude" 2>/dev/null # Add to PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.) export PATH="/path/to/claude/bin:$PATH"

4. Verify CLI is working:

   claude --version claude mcp list

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

   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:

2. Manual Model Download

Pre-download the model manually if automatic download fails:

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

3. Proxy Configuration

If behind a corporate proxy, configure environment variables:

4. Offline/Air-Gapped Installation

For environments without internet access:

On a machine with internet:

1. Download the model:

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

2. Package the model cache:

   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

2. Extract to the HuggingFace cache directory:

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

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

   pip install mcp-skillset # Or install from wheel

4. Verify the setup:

   mcp-skillset doctor

5. Custom Cache Location

If you need to use a different cache directory:

6. Disk Space Issues

Check available space in the cache directory:

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

7. Permission Issues

Ensure the cache directory is writable:

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:

   • Error message and stack trace

   • Output of mcp-skillset --version

   • Operating system and Python version

   • Steps to reproduce

Contributing

Contributions welcome! Please read our contributing guidelines first.

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run make quality to ensure tests pass

5. Submit a pull request

License

MIT License - see LICENSE for details.

Acknowledgments

• Built on the Model Context Protocol

• Inspired by Claude Skills

• Uses ChromaDB for vector search

• Embeddings via sentence-transformers

Links

• PyPI Package: mcp-skillset on PyPI

• Documentation: GitHub Wiki

• Issue Tracker: GitHub Issues

• MCP Registry: MCP Servers

• Publishing Guide: docs/publishing.md

Status: ✅ v0.5.0 - Production Ready | Test Coverage: 85-96% | Tests: 77 passing (48 unit + 29 security)