# Mcp Skillset

> Dynamic RAG-powered skills service for code assistants via MCP - Vector + Knowledge Graph hybrid search for intelligent skill discovery

- **Type:** MCP server
- **Install:** `agentstack add mcp-bobmatnyc-mcp-skillset`
- **Verified:** Pending review
- **Seller:** [bobmatnyc](https://agentstack.voostack.com/s/bobmatnyc)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bobmatnyc](https://github.com/bobmatnyc)
- **Source:** https://github.com/bobmatnyc/mcp-skillset

## Install

```sh
agentstack add mcp-bobmatnyc-mcp-skillset
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://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

```bash
# 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:

```bash
brew tap bobmatnyc/tools
brew install mcp-skillset
```

### With uv (Recommended - Fastest)

[uv](https://github.com/astral-sh/uv) is the fastest way to install Python applications:

```bash
uv tool install mcp-skillset
```

### With pipx (Alternative)

[pipx](https://pipx.pypa.io/) is a reliable alternative for installing Python CLI applications:

```bash
pipx install mcp-skillset
```

### With pip (Fallback)

Standard pip installation (not recommended for CLI tools):

```bash
pip install mcp-skillset
```

### From Source

```bash
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:

```bash
# 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**:
```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:
```bash
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/SHELL_COMPLETIONS.md](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**:
```python
# 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**:
```python
# 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**:
```python
# 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**:
```python
# 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**:
```python
# 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**:
```python
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**:
```python
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

```bash
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:

```bash
# 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**:
```bash
# Installed version (from pip install -e .)
mcp-skillset search "testing"

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

### Run Tests

```bash
# 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:

```bash
# 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"
   ```

4. **Verify CLI is working**:
   ```bash
   claude --version
   claude mcp list
   ```

5. **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:
```bash
curl -I https://huggingface.co
```

#### 2. Manual Model Download

Pre-download the model manually if automatic download fails:
```bash
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:
```bash
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')"
   ```

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

2. Extract to the HuggingFace cache directory:
   ```bash
   mkdir -p ~/.cache/huggingface
   cd ~/.cache/huggingface
   tar -xzf /path/to/sentence-transformers-model.tar.gz
   ```

3. Install mcp-skillset (transfer wheel if needed):
   ```bash
   pip install mcp-skillset  # Or install from wheel
   ```

4. Verify the setup:
   ```bash
   mcp-skillset doctor
   ```

#### 5. Custom Cache Location

If you need to use a different cache directory:
```bash
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:
```bash
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:
```bash
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](https://github.com/bobmatnyc/mcp-skillset/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](https://github.com/bobmatnyc)
- **Source:** [bobmatnyc/mcp-skillset](https://github.com/bobmatnyc/mcp-skillset)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bobmatnyc-mcp-skillset
- Seller: https://agentstack.voostack.com/s/bobmatnyc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.