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

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.

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 (<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)

mcp-skillset build-skill --interactive

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

mcp-skillset build-skill \
  --name "FastAPI Testing" \
  --description "Comprehensive testing strategies for FastAPI applications using pytest, httpx, and test clients" \
  --domain "web development" \
  --tags "fastapi,pytest,testing,web" \
  --template web-development

CLI: Preview Mode

Preview the generated skill without deploying:

mcp-skillset build-skill \
  --name "FastAPI Testing" \
  --description "Comprehensive testing strategies for FastAPI applications" \
  --domain "web development" \
  --preview

MCP Tool (For AI Agents)

# Via MCP server
result = await skill_create(
    name="GraphQL API Design",
    description="Design and implement GraphQL APIs with schema-first approach",
    domain="api development",
    tags=["graphql", "api", "apollo"],
    template="api-development",
    deploy=True
)

Available Templates

Template	Best For	Use Cases
web-development	Web apps	Frontend, backend, full-stack patterns
api-development	APIs	REST, GraphQL, authentication, rate limiting
testing	QA workflows	TDD, unit/integration/E2E testing

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:

mcp-skillset build-skill \
  --name "FastAPI Testing" \
  --description "Test FastAPI endpoints with pytest and httpx clients" \
  --domain "web development" \
  --tags "fastapi,pytest,testing" \
  --template web-development

Creating a GraphQL API skill:

mcp-skillset build-skill \
  --name "GraphQL API Design" \
  --description "Schema-first GraphQL API design with Apollo Server" \
  --domain "api development" \
  --tags "graphql,apollo,api" \
  --template api-development

Creating a TDD workflow skill:

mcp-skillset build-skill \
  --name "TDD Workflow" \
  --description "Test-driven development workflow with red-green-refactor cycle" \
  --domain "testing" \
  --tags "tdd,testing,workflow" \
  --template testing

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:

Test activation: Start a project matching your skill's tags
Verify loading: Check that Claude references your skill
Iterate: Update skills based on usage
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:

mcp-skillset setup

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:

# Get personalized recommendations based on your project
mcp-skillset recommend

# Search for specific topics
mcp-skillset search "testing patterns"

# Browse all skills interactively
mcp-skillset demo

# List all skills in compact format
mcp-skillset list --compact

3. Start the MCP Server

mcp-skillset mcp

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

# Get setup and testing recommendations
cd ~/my-new-python-project
mcp-skillset recommend

# Search for testing frameworks
mcp-skillset search "python testing frameworks" --limit 5

# Learn about pytest best practices
mcp-skillset info pytest-best-practices

# Start MCP server for Claude integration
mcp-skillset mcp

Scenario 2: Debugging Production Issues

# Find debugging techniques
mcp-skillset search "production debugging" --search-mode semantic_focused

# Get systematic debugging approach
mcp-skillset info systematic-debugging

# View example questions
mcp-skillset demo systematic-debugging

Scenario 3: Code Review Preparation

# Find code review and quality skills
mcp-skillset search "code review" --category "Best Practices"

# Explore testing and quality skills
mcp-skillset list --category "Testing"

# Enrich your code review prompt
mcp-skillset enrich "Review this code for security and performance issues" --max-skills 3

Scenario 4: Learning New Framework

# Search for framework-specific skills
mcp-skillset search "async python patterns"

# Get recommendations for async projects
cd ~/async-project
mcp-skillset recommend --search-mode graph_focused

# Explore related skills interactively
mcp-skillset demo

Project Structure

~/.mcp-skillset/
├── config.yaml              # User configuration
├── repos/                   # Cloned skill repositories
│   ├── anthropics/skills/
│   ├── obra/superpowers/
│   └── custom-repo/
├── indices/                 # Vector + KG indices
│   ├── vector_store/
│   └── knowledge_graph/
└── metadata.db             # SQLite metadata

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 Configuration
# Controls weighting between vector similarity and knowledge graph relationships
hybrid_search:
  # Option 1: Use a preset (recommended)
  preset: current  # current, semantic_focused, graph_focused, or balanced

  # Option 2: Specify custom weights (must sum to 1.0)
  # vector_weight: 0.7  # Weight for vector similarity (0.0-1.0)
  # graph_weight: 0.3   # Weight for knowledge graph (0.0-1.0)

repositories:
  - url: https://github.com/anthropics/skills.git
    priority: 100
    auto_update: true
  - url: https://github.com/obra/superpowers.git
    priority: 90
    auto_update: true
  - url: https://github.com/ComposioHQ/awesome-claude-skills.git
    priority: 85
    auto_update: true
  - url: https://github.com/Prat011/awesome-llm-skills.git
    priority: 85
    auto_update: true

vector_store:
  backend: chromadb
  embedding_model: all-MiniLM-L6-v2

server:
  transport: stdio
  log_level: info

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:

Preset	Vector	Graph	Best For	Use Case
`current`	70%	30%	General purpose (default)	Balanced skill discovery with slight semantic emphasis
`semantic_focused`	90%	10%	Natural language queries	"help me debug async code" → emphasizes semantic understanding
`graph_focused`	30%	70%	Related skill discovery	Starting from "pytest" → discovers pytest-fixtures, pytest-mock
`balanced`	50%	50%	Equal weighting	General purpose when unsure which approach is better

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:

# Use preset (recommended)
hybrid_search:
  preset: current

# OR specify custom weights
hybrid_search:
  vector_weight: 0.8
  graph_weight: 0.2

CLI Override:

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

# Use semantic-focused mode for this search
mcp-skillset search "python testing" --search-mode semantic_focused

# Use graph-focused mode for recommendations
mcp-skillset recommend --search-mode graph_focused

# Available modes: semantic_focused, graph_focused, balanced, current

Project Configuration (`.mcp-skillset.yaml`)

project:
  name: my-project
  toolchain:
    primary: Python
    frameworks: [Flask, SQLAlchemy]

auto_load:
  - systematic-debugging
  - test-driven-development

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

Command	Purpose	Key Options
`setup`	Initial configuration wizard	`--auto`, `--project-dir`
`config`	View/modify configuration	`--show`, `--set`
`index`	Rebuild indices	`--incremental`, `--force`
`install`	Install for AI agents	`--agent`, `--dry-run`
`mcp`	Start MCP server	`--dev`
`build-skill`	Create progressive skills	`--interactive`, `--preview`, `--template`
`search`	Find skills by query	`--limit`, `--category`, `--search-mode`
`list`	List all skills	`--category`, `--compact`
`info` / `show`	Show skill details	(skill-id argument)
`recommend`	Get recommendations	`--search-mode`
`demo`	Interactive skill explorer	`--interactive`
`repo add`	Add skill repository	`--priority`
`repo list`	List repositories	-
`repo update`	Update repositories	(optional repo-id)
`discover search`	Search GitHub for repos	`--min-stars`, `--limit`
`discover trending`	Get trending repos	`--timeframe`, `--topic`
`discover topic`	Search by GitHub topic	`--min-stars`
`discover verify`	Verify SKILL.md files	(repo-url argument)
`discover limits`	Show API rate limits	-
`doctor`	Health check	-
`stats`	Usage statistics	-
`enrich`	Enrich prompts	`--max-skills`, `--full`, `--output`

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.

# Interactive setup wizard (recommended for first-time setup)
mcp-skillset setup

# Non-interactive setup with defaults (CI/automation)
mcp-skillset setup --auto

# Skip automatic agent installation (configure manually later)
mcp-skillset setup --skip-agents

# Setup for specific project directory
mcp-skillset setup --project-dir /path/to/project

# Custom config file location
mcp-skillset setup --config ~/.config/mcp-skillset/custom.yaml

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.

# Show current configuration (read-only)
mcp-skillset config
mcp-skillset config --show

# Set configuration value interactively
mcp-skillset config --set hybrid_search.preset=semantic_focused
mcp-skillset config --set repositories[0].auto_update=true

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

`index` - Rebuild Indices

Rebuild vector and knowledge graph indices from skill repositories.

# Full rebuild (recommended after adding repositories)
mcp-skillset index

# Incremental indexing (only new/changed skills)
mcp-skillset index --incremental

# Force full reindex (bypass cache)
mcp-skillset index --force

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.

# Auto-detect and install for all supported agents
mcp-skillset install

# Install for specific agent
mcp-skillset install --agent claude-desktop
mcp-skillset install --agent claude-code
mcp-skillset install --agent auggie

# Preview installation without making changes
mcp-skillset install --dry-run

# Force overwrite existing configuration
mcp-skillset install --force

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.

# Interactive mode (recommended)
mcp-skillset build-skill --interactive

# Standard mode with all parameters
mcp-skillset build-skill \
  --name "FastAPI Testing" \
  --description "Comprehensive testing strategies for FastAPI applications" \
  --domain "web development" \
  --tags "fastapi,pytest,testing,web" \
  --template web-development

# Preview mode (no deployment)
mcp-skillset build-skill \
  --name "GraphQL API Design" \
  --description "Schema-first GraphQL API design" \
  --domain "api development" \
  --preview

# Disable auto-deployment
mcp-skillset build-skill \
  --name "Test Skill" \
  --description "Testing skill creation" \
  --domain "testing" \
  --no-deploy

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.

# Start MCP server (stdio transport)
mcp-skillset mcp

# Development mode (auto-reload on changes)
mcp-skillset mcp --dev

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).

# Basic search
mcp-skillset search "python testing"

# Limit results
mcp-skillset search "debugging" --limit 5

# Filter by category
mcp-skillset search "testing" --category "Python"

# Override search mode (semantic vs graph weighting)
mcp-skillset search "async patterns" --search-mode semantic_focused
mcp-skillset search "pytest fixtures" --search-mode graph_focused

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:

# Find testing skills for Python
mcp-skillset search "python unit testing frameworks"

# Discover debugging techniques
mcp-skillset search "debugging techniques" --limit 3

# Find skills related to async programming
mcp-skillset search "asynchronous programming" --search-mode graph_focused

`list` - List All Skills

Display all available skills with filtering options.

# List all skills
mcp-skillset list

# Filter by category
mcp-skillset list --category "Testing"

# Compact output (table format)
mcp-skillset list --compact

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.

# Show skill details (both commands are identical)
mcp-skillset info pytest-fixtures
mcp-skillset show systematic-debugging

# Output includes:
# - Full skill ID and title
# - Description
# - Category
# - Repository source
# - Full instructions preview

`recommend` - Smart Recommendations

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

# Get recommendations for current directory
mcp-skillset recommend

# Override search mode for recommendations
mcp-skillset recommend --search-mode graph_focused

How it works:

Analyzes project directory (package.json, pyproject.toml, Cargo.toml, etc.)
Detects primary language and frameworks
Searches for relevant skills using detected toolchain
Ranks by relevance to your tech stack

Example output:

🎯 Recommended Skills for Python Project

1. pytest-advanced-fixtures
   Category: Testing | Relevance: 0.92
   Advanced pytest fixture patterns for complex test scenarios

2. python-async-debugging
   Category: Debugging | Relevance: 0.88
   Debug async/await code with modern Python tools

`demo` - Interactive Skill Explorer

Generate example prompts and explore skills interactively.

# Interactive menu (browse all skills)
mcp-skillset demo

# Interactive mode explicitly
mcp-skillset demo --interactive

# Generate examples for specific skill
mcp-skillset demo pytest-fixtures
mcp-skillset demo systematic-debugging

Features:

Browse all skills with Rich menu
Auto-generates relevant example questions
Extracts key concepts from skill instructions
Shows practical use cases

Example output:

📚 Demo: pytest-fixtures

Key Concepts:
- Fixture scopes (function, class, module, session)
- Fixture dependencies and chaining
- Parametrized fixtures
- Fixture cleanup and teardown

Example Questions:
1. How do I create a database fixture with session scope?
2. Show me how to parametrize fixtures for multiple test cases
3. What's the best way to chain fixtures together?

Repository Management Commands

`repo add` - Add Repository

Add a new skill repository to your configuration.

# Add repository with default priority
mcp-skillset repo add https://github.com/user/skills.git

# Add with custom priority (higher = searched first)
mcp-skillset repo add https://github.com/user/skills.git --priority 100

Priority levels:

100: Highest (official repositories)
50: Medium (default, community repositories)
10: Low (experimental repositories)

`repo list` - List Repositories

Display all configured skill repositories.

mcp-skillset repo list

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.

# Update all repositories
mcp-skillset repo update

# Update specific repository by ID
mcp-skillset repo update anthropic-skills

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.

# Basic search
mcp-skillset discover search "python testing"

# With minimum stars filter
mcp-skillset discover search "fastapi" --min-stars 10

# Limit results
mcp-skillset discover search "react typescript" --limit 20

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.

# Weekly trending (default)
mcp-skillset discover trending

# Monthly trending
mcp-skillset discover trending --timeframe month

# Filter by topic
mcp-skillset discover trending --topic claude-skills

Timeframes: week, month, year

`discover topic` - Search by Topic

Search repositories by GitHub topic.

# Search by topic
mcp-skillset discover topic claude-skills

# With stars filter
mcp-skillset discover topic mcp-skills --min-stars 5

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.

mcp-skillset discover verify https://github.com/anthropics/skills.git

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.

mcp-skillset discover limits

Rate limits:

Unauthenticated: 60 requests/hour
Authenticated (with token): 5000 requests/hour

To increase limits:

export GITHUB_TOKEN=your_github_token_here

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

Utility Commands

`doctor` - Health Check

Run comprehensive system health check and validation.

mcp-skillset doctor

Checks performed:

Configuration file validity
Repository accessibility
Index integrity (vector + knowledge graph)
Embedding model availability
Database connectivity
Disk space and permissions

Example output:

🏥 MCP SkillSet Health Check

✅ Configuration: OK
✅ Repositories: 3 configured, all accessible
✅ Vector Store: 147 skills indexed
✅ Knowledge Graph: 147 nodes, 423 edges
✅ Embedding Model: all-MiniLM-L6-v2 (cached)
✅ Database: SQLite OK
✅ Disk Space: 2.3 GB available

System Status: Healthy ✅

`stats` - Usage Statistics

Display usage statistics and metrics.

mcp-skillset stats

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).

# Enrich a prompt with relevant skills
mcp-skillset enrich "help me write tests for async functions"

# Limit skills included
mcp-skillset enrich "debug memory leak" --max-skills 2

# Include full skill instructions (vs brief summaries)
mcp-skillset enrich "testing strategy" --full

# Set relevance threshold (0.0-1.0)
mcp-skillset enrich "python patterns" --threshold 0.8

# Save enriched prompt to file
mcp-skillset enrich "code review checklist" --output enriched_prompt.txt

# Copy to clipboard (requires pyperclip)
mcp-skillset enrich "refactoring" --clipboard

What it does:

Searches for relevant skills based on your prompt
Extracts key concepts and instructions from top matches
Augments your prompt with skill context
Outputs enriched prompt for use with LLMs

Global Options

All commands support these global flags:

# Show version
mcp-skillset --version

# Verbose output
mcp-skillset --verbose search "testing"

# Debug mode (detailed logs)
mcp-skillset --debug search "testing"

# Help for any command
mcp-skillset --help
mcp-skillset search --help
mcp-skillset repo --help

Command Workflows

First-Time Setup Flow:

# 1. Install mcp-skillset (recommended - fastest)
uv tool install mcp-skillset

# Alternative installation methods:
# pipx install mcp-skillset
# pip install mcp-skillset

# 2. Run setup wizard (includes agent installation)
mcp-skillset setup

# 3. Verify installation
mcp-skillset doctor

# 4. Explore available skills
mcp-skillset list

Daily Usage Pattern:

# Morning: Get recommendations for your project
cd ~/my-project
mcp-skillset recommend

# Search for specific skill when needed
mcp-skillset search "async debugging"

# View skill details before using
mcp-skillset info python-async-debugging

# Start MCP server for Claude integration
mcp-skillset mcp

Adding New Skill Repository:

# 1. Add repository
mcp-skillset repo add https://github.com/user/custom-skills.git

# 2. Rebuild index to include new skills
mcp-skillset index --incremental

# 3. Search new skills
mcp-skillset search "custom skill topic"

Shell Completions

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

Quick Install

Bash (requires Bash 4.4+):

eval "$(_MCP_SKILLS_COMPLETE=bash_source mcp-skillset)" >> ~/.bashrc
source ~/.bashrc

Zsh (macOS default):

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 <TAB>        # Shows: config health index info list mcp recommend repo search setup stats
mcp-skillset repo <TAB>   # Shows: add list update
mcp-skillset search --<TAB>  # Shows: --category --help --limit

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:

skills_search - Semantic search with hybrid RAG (vector + knowledge graph)
skill_get - Retrieve complete skill details by ID
skills_recommend - Context-aware skill recommendations based on project toolchain
skill_categories - Browse available skill categories and toolchains
skills_reindex - Rebuild search indices (vector store + knowledge graph)
skill_templates_list - List available skill templates for progressive skill creation
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. 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:

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, skill_id, skill_path, 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:

Sets PYTHONPATH to include src/ directory
Activates local .venv if present
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: < 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:

-------------------------- benchmark: 15 tests --------------------------
Name (time in ms)                    Min      Max     Mean   StdDev
---------------------------------------------------------------------
test_vector_search_latency_100      45.2     52.1    47.8     2.1
test_lookup_by_id_single             0.3      0.8     0.4     0.1
test_hybrid_search_end_to_end       89.5    105.2    94.3     5.2
---------------------------------------------------------------------

Linting and Formatting

make lint-fix

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

# Basic security scan (Safety + pip-audit)
make security-check

# Comprehensive security audit with reports
make security-check-full

# Install security scanning tools
make security-install

# Pre-publish with security checks
make pre-publish

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:

Verify Claude Code is installed:
- Make sure Claude Code (VS Code extension) is installed and activated
- Check that the extension is up to date
Check if claude command is available:
```
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

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"

Verify CLI is working:
```
claude --version
claude mcp list
```

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:

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:

Download the model:

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

Package the model cache:

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

On the air-gapped machine:

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

Extract to the HuggingFace cache directory:

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

Install mcp-skillset (transfer wheel if needed):

pip install mcp-skillset  # Or install from wheel

Verify the setup:
```
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:

Check GitHub Issues
Review logs: ~/.mcp-skillset/logs/
Run health check: mcp-skillset doctor
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.

Fork the repository
Create a feature branch
Make your changes
Run make quality to ensure tests pass
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

mcp-skills

mcp-skillset

Key Features

Security

Security Features

Trust Levels

Quick Security Check

Installation

Prerequisites

With Homebrew (macOS/Linux)

With uv (Recommended - Fastest)

With pipx (Alternative)

With pip (Fallback)

From Source

Local Development (Without Installation)

First-Run Requirements

Building Progressive Skills

What are Progressive Skills?

Creating Skills

CLI: Interactive Mode (Recommended)

CLI: Command-Line Mode

CLI: Preview Mode

MCP Tool (For AI Agents)

Available Templates

Examples

Deployment

Skill Structure

Next Steps

Quick Start

1. Setup

2. Explore Available Skills

3. Start the MCP Server

4. Use with Claude Code

Real-World Usage Scenarios

Project Structure

Architecture

Configuration

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

Hybrid Search Modes

Project Configuration (.mcp-skillset.yaml)

CLI Commands

Quick Reference

Core Commands

setup - Initial Configuration

config - Configuration Management

index - Rebuild Indices

install - Agent Integration

build-skill - Progressive Skill Creation

mcp - MCP Server

Search & Discovery Commands

search - Semantic Search

list - List All Skills

info / show - Skill Details

recommend - Smart Recommendations

demo - Interactive Skill Explorer

Repository Management Commands

repo add - Add Repository

repo list - List Repositories

repo update - Update Repositories

GitHub Discovery Commands

discover search - Search GitHub

discover trending - Get Trending Repos

discover topic - Search by Topic

discover verify - Verify Repository

discover limits - API Rate Limits

Utility Commands

doctor - Health Check

stats - Usage Statistics

enrich - Prompt Enrichment

Global Options

Command Workflows

Shell Completions

Quick Install

Features

Verification

Documentation

MCP Tools

Tool Details

1. skills_search

2. skill_get

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

Project Configuration (`.mcp-skillset.yaml`)

`setup` - Initial Configuration

`config` - Configuration Management

`index` - Rebuild Indices

`install` - Agent Integration

`build-skill` - Progressive Skill Creation

`mcp` - MCP Server

`search` - Semantic Search

`list` - List All Skills

`info` / `show` - Skill Details

`recommend` - Smart Recommendations

`demo` - Interactive Skill Explorer

`repo add` - Add Repository

`repo list` - List Repositories

`repo update` - Update Repositories

`discover search` - Search GitHub

`discover trending` - Get Trending Repos

`discover topic` - Search by Topic

`discover verify` - Verify Repository

`discover limits` - API Rate Limits

`doctor` - Health Check

`stats` - Usage Statistics

`enrich` - Prompt Enrichment