{"id":36934203,"url":"https://github.com/bobmatnyc/mcp-skillset","last_synced_at":"2026-04-15T14:39:46.705Z","repository":{"id":325562814,"uuid":"1101640542","full_name":"bobmatnyc/mcp-skillset","owner":"bobmatnyc","description":"Dynamic RAG-powered skills service for code assistants via MCP - Vector + Knowledge Graph hybrid search for intelligent skill discovery","archived":false,"fork":false,"pushed_at":"2026-02-09T00:14:50.000Z","size":1628,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-09T06:14:56.113Z","etag":null,"topics":["chromadb","code-assistant","hybrid-search","knowledge-graph","mcp","python","rag","skills","vector-search"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobmatnyc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-22T01:19:55.000Z","updated_at":"2026-02-09T00:14:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bobmatnyc/mcp-skillset","commit_stats":null,"previous_names":["bobmatnyc/mcp-skills","bobmatnyc/mcp-skillkit"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/bobmatnyc/mcp-skillset","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fmcp-skillset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fmcp-skillset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fmcp-skillset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fmcp-skillset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobmatnyc","download_url":"https://codeload.github.com/bobmatnyc/mcp-skillset/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fmcp-skillset/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31846418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T13:28:40.153Z","status":"ssl_error","status_checked_at":"2026-04-15T13:28:29.396Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chromadb","code-assistant","hybrid-search","knowledge-graph","mcp","python","rag","skills","vector-search"],"created_at":"2026-01-13T09:46:32.869Z","updated_at":"2026-04-15T14:39:46.664Z","avatar_url":"https://github.com/bobmatnyc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-skillset\n\n[![PyPI version](https://badge.fury.io/py/mcp-skillset.svg)](https://badge.fury.io/py/mcp-skillset)\n[![Python Versions](https://img.shields.io/pypi/pyversions/mcp-skillset)](https://pypi.org/project/mcp-skillset/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Test Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)](https://github.com/bobmatnyc/mcp-skillset)\n\n**Dynamic RAG-powered skills for code assistants via Model Context Protocol (MCP)**\n\nmcp-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.\n\n## Key Features\n\n- **🚀 Zero Config**: `mcp-skillset setup` handles everything automatically\n- **🧠 Intelligent**: Auto-detects your project's toolchain (Python, TypeScript, Rust, Go, etc.)\n- **🔍 Dynamic Discovery**: Vector similarity + knowledge graph for better skill finding\n- **📦 Multi-Source**: Pulls skills from multiple git repositories\n- **⚡ On-Demand Loading**: Skills loaded when needed, not all at startup\n- **🔌 MCP Native**: First-class Model Context Protocol integration\n- **🔒 Security First**: Multi-layer defense against prompt injection and malicious skills\n- **🌐 agentskills.io Compatible**: Supports both native and [agentskills.io](https://agentskills.io) specification formats\n\n## Security\n\nMCP Skillset implements comprehensive security validation to protect against malicious skills from public repositories.\n\n### Security Features\n\n- **🛡️ Prompt Injection Detection**: Automatic detection of instruction override attempts, role hijacking, and context escape\n- **🔍 Threat Classification**: Multi-level threat detection (BLOCKED, DANGEROUS, SUSPICIOUS)\n- **🏷️ Repository Trust Levels**: TRUSTED (official), VERIFIED (community), UNTRUSTED (public)\n- **📏 Size Limits**: DoS prevention through content size enforcement\n- **🎯 Content Sanitization**: All skills wrapped in clear boundaries to prevent context escape\n\n### Trust Levels\n\n| Level | Description | Security Policy |\n|-------|-------------|-----------------|\n| **TRUSTED** | Official Anthropic repos | Minimal filtering (only BLOCKED threats) |\n| **VERIFIED** | Known community repos | Moderate filtering (BLOCKED + DANGEROUS) |\n| **UNTRUSTED** | Public repos (default) | Strict filtering (all threats) |\n\n### Quick Security Check\n\n```bash\n# Skills from public repos are automatically validated\nmcp-skillset search \"python testing\"\n\n# View security details in logs\nmcp-skillset --debug search \"python testing\"\n```\n\nFor detailed security information, threat models, and best practices, see [SECURITY.md](./SECURITY.md).\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Claude Code (for Claude Code integration) with `claude` CLI available\n\n### With Homebrew (macOS/Linux)\n\nThe easiest way to install on macOS or Linux:\n\n```bash\nbrew tap bobmatnyc/tools\nbrew install mcp-skillset\n```\n\n### With uv (Recommended - Fastest)\n\n[uv](https://github.com/astral-sh/uv) is the fastest way to install Python applications:\n\n```bash\nuv tool install mcp-skillset\n```\n\n### With pipx (Alternative)\n\n[pipx](https://pipx.pypa.io/) is a reliable alternative for installing Python CLI applications:\n\n```bash\npipx install mcp-skillset\n```\n\n### With pip (Fallback)\n\nStandard pip installation (not recommended for CLI tools):\n\n```bash\npip install mcp-skillset\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/bobmatnyc/mcp-skillset.git\ncd mcp-skillset\nuv sync\n```\n\n### Local Development (Without Installation)\n\nFor development, you can run mcp-skillset directly from source without installing:\n\n```bash\n# Use the development script\n./mcp-skillset-dev --help\n./mcp-skillset-dev search \"python testing\"\n./mcp-skillset-dev setup --auto\n```\n\nThe `mcp-skillset-dev` script:\n- Runs the package from source code (not installed version)\n- Uses local virtual environment if available\n- Sets up PYTHONPATH automatically\n- Passes all arguments through to the CLI\n\nThis is useful for:\n- Testing changes without reinstalling\n- Developing new features\n- Debugging with source code\n- Contributing to the project\n\n**Note**: For production use, install the package normally with `uv tool install mcp-skillset` or `pipx install mcp-skillset`.\n\n### First-Run Requirements\n\n**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.\n\n**Requirements**:\n- ✅ Active internet connection\n- ✅ ~100MB free disk space\n- ✅ 2-5 minutes for initial download (depending on connection speed)\n\n**Model Caching**:\n- Models are cached in `~/.cache/huggingface/` for future use\n- Subsequent runs use the cached model (no download required)\n- The cache persists across mcp-skillset updates\n\n## Building Progressive Skills\n\nmcp-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.\n\n### What are Progressive Skills?\n\nProgressive skills are modular capabilities that:\n- **Load in two stages**: Lightweight metadata (~100 tokens) at startup, full body (\u003c5k tokens) when activated\n- **Auto-activate** based on project context (toolchain, frameworks, keywords)\n- **Persist across sessions** - once created, always available\n- **Follow best practices** - templates ensure quality and consistency\n\n### Creating Skills\n\n#### CLI: Interactive Mode (Recommended)\n```bash\nmcp-skillset build-skill --interactive\n```\n\nYou'll be prompted for:\n- **Name**: Skill identifier (e.g., \"FastAPI Testing\")\n- **Description**: What it does and when to use it\n- **Domain**: Category (e.g., \"web development\")\n- **Tags**: Keywords for discovery (e.g., \"fastapi,pytest,testing\")\n- **Template**: Choose from specialized templates\n\n#### CLI: Command-Line Mode\n```bash\nmcp-skillset build-skill \\\n  --name \"FastAPI Testing\" \\\n  --description \"Comprehensive testing strategies for FastAPI applications using pytest, httpx, and test clients\" \\\n  --domain \"web development\" \\\n  --tags \"fastapi,pytest,testing,web\" \\\n  --template web-development\n```\n\n#### CLI: Preview Mode\nPreview the generated skill without deploying:\n```bash\nmcp-skillset build-skill \\\n  --name \"FastAPI Testing\" \\\n  --description \"Comprehensive testing strategies for FastAPI applications\" \\\n  --domain \"web development\" \\\n  --preview\n```\n\n#### MCP Tool (For AI Agents)\n```python\n# Via MCP server\nresult = await skill_create(\n    name=\"GraphQL API Design\",\n    description=\"Design and implement GraphQL APIs with schema-first approach\",\n    domain=\"api development\",\n    tags=[\"graphql\", \"api\", \"apollo\"],\n    template=\"api-development\",\n    deploy=True\n)\n```\n\n### Available Templates\n\n| Template | Best For | Use Cases |\n|----------|----------|-----------|\n| **web-development** | Web apps | Frontend, backend, full-stack patterns |\n| **api-development** | APIs | REST, GraphQL, authentication, rate limiting |\n| **testing** | QA workflows | TDD, unit/integration/E2E testing |\n\n**Note**: The `base` template is currently recommended for advanced users only due to validation limitations. Use specialized templates for production skills.\n\n### Examples\n\n**Creating a FastAPI testing skill**:\n```bash\nmcp-skillset build-skill \\\n  --name \"FastAPI Testing\" \\\n  --description \"Test FastAPI endpoints with pytest and httpx clients\" \\\n  --domain \"web development\" \\\n  --tags \"fastapi,pytest,testing\" \\\n  --template web-development\n```\n\n**Creating a GraphQL API skill**:\n```bash\nmcp-skillset build-skill \\\n  --name \"GraphQL API Design\" \\\n  --description \"Schema-first GraphQL API design with Apollo Server\" \\\n  --domain \"api development\" \\\n  --tags \"graphql,apollo,api\" \\\n  --template api-development\n```\n\n**Creating a TDD workflow skill**:\n```bash\nmcp-skillset build-skill \\\n  --name \"TDD Workflow\" \\\n  --description \"Test-driven development workflow with red-green-refactor cycle\" \\\n  --domain \"testing\" \\\n  --tags \"tdd,testing,workflow\" \\\n  --template testing\n```\n\n### Deployment\n\nSkills are automatically deployed to `~/.claude/skills/skill-name/SKILL.md` and become immediately available to:\n- **Claude Code** (VS Code extension)\n- **Claude Desktop** (standalone app)\n- **Auggie** (if configured)\n\n### Skill Structure\n\nGenerated skills include:\n- **YAML Frontmatter**: Metadata (name, description, tags, version)\n- **Overview**: What the skill does\n- **When to Use**: Activation context\n- **Core Principles**: Best practices with examples\n- **Common Patterns**: Proven approaches\n- **Anti-Patterns**: What to avoid\n- **Testing Strategies**: Validation approaches\n- **Related Skills**: Complementary skills\n\n### Next Steps\n\nAfter creating skills:\n1. **Test activation**: Start a project matching your skill's tags\n2. **Verify loading**: Check that Claude references your skill\n3. **Iterate**: Update skills based on usage\n4. **Share**: Export skills for team use\n\nFor detailed documentation, see:\n- **API Reference**: [docs/skill-builder-usage.md](docs/skill-builder-usage.md)\n- **Examples**: [examples/skill_builder_demo.py](examples/skill_builder_demo.py)\n- **QA Report**: [QA_REPORT_SKILL_BUILDER.md](QA_REPORT_SKILL_BUILDER.md)\n\n## Quick Start\n\n### 1. Setup\n\nRun the interactive setup wizard to configure mcp-skillset for your project:\n\n```bash\nmcp-skillset setup\n```\n\n**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.\n\nThis complete one-command setup will:\n- Download embedding model (first run only)\n- Detect your project's toolchain\n- Clone relevant skill repositories\n- Build vector + knowledge graph indices\n- Configure MCP server integration\n- **Install and configure for all detected AI agents** (Claude Desktop, Claude Code, Auggie)\n  - For Claude Code: Uses the official `claude mcp add` CLI command\n  - For other agents: Configures via JSON config files\n- Validate the setup\n\n**Tip**: Use `mcp-skillset setup --skip-agents` if you prefer to configure AI agents manually using the `install` command.\n\n### 2. Explore Available Skills\n\nBefore diving in, explore what's available:\n\n```bash\n# Get personalized recommendations based on your project\nmcp-skillset recommend\n\n# Search for specific topics\nmcp-skillset search \"testing patterns\"\n\n# Browse all skills interactively\nmcp-skillset demo\n\n# List all skills in compact format\nmcp-skillset list --compact\n```\n\n### 3. Start the MCP Server\n\n```bash\nmcp-skillset mcp\n```\n\nThe server will start and expose skills to your code assistant via MCP protocol.\n\n### 4. Use with Claude Code\n\nSkills are automatically available in Claude Code. Try:\n- \"What testing skills are available for Python?\"\n- \"Show me debugging skills\"\n- \"Recommend skills for my project\"\n- \"Use the pytest-fixtures skill to help me write better tests\"\n\n### Real-World Usage Scenarios\n\n**Scenario 1: Starting a New Python Project**\n```bash\n# Get setup and testing recommendations\ncd ~/my-new-python-project\nmcp-skillset recommend\n\n# Search for testing frameworks\nmcp-skillset search \"python testing frameworks\" --limit 5\n\n# Learn about pytest best practices\nmcp-skillset info pytest-best-practices\n\n# Start MCP server for Claude integration\nmcp-skillset mcp\n```\n\n**Scenario 2: Debugging Production Issues**\n```bash\n# Find debugging techniques\nmcp-skillset search \"production debugging\" --search-mode semantic_focused\n\n# Get systematic debugging approach\nmcp-skillset info systematic-debugging\n\n# View example questions\nmcp-skillset demo systematic-debugging\n```\n\n**Scenario 3: Code Review Preparation**\n```bash\n# Find code review and quality skills\nmcp-skillset search \"code review\" --category \"Best Practices\"\n\n# Explore testing and quality skills\nmcp-skillset list --category \"Testing\"\n\n# Enrich your code review prompt\nmcp-skillset enrich \"Review this code for security and performance issues\" --max-skills 3\n```\n\n**Scenario 4: Learning New Framework**\n```bash\n# Search for framework-specific skills\nmcp-skillset search \"async python patterns\"\n\n# Get recommendations for async projects\ncd ~/async-project\nmcp-skillset recommend --search-mode graph_focused\n\n# Explore related skills interactively\nmcp-skillset demo\n```\n\n## Project Structure\n\n```\n~/.mcp-skillset/\n├── config.yaml              # User configuration\n├── repos/                   # Cloned skill repositories\n│   ├── anthropics/skills/\n│   ├── obra/superpowers/\n│   └── custom-repo/\n├── indices/                 # Vector + KG indices\n│   ├── vector_store/\n│   └── knowledge_graph/\n└── metadata.db             # SQLite metadata\n```\n\n## Architecture\n\nmcp-skillset uses a hybrid RAG approach combining:\n\n**Vector Store** (ChromaDB):\n- Fast semantic search over skill descriptions\n- Embeddings generated with sentence-transformers\n- Persistent local storage with minimal configuration\n\n**Knowledge Graph** (NetworkX):\n- Skill relationships and dependencies\n- Category and toolchain associations\n- Related skill discovery\n\n**Toolchain Detection**:\n- Automatic detection of programming languages\n- Framework and build tool identification\n- Intelligent skill recommendations\n\n## Configuration\n\n### Global Configuration (`~/.mcp-skillset/config.yaml`)\n\n```yaml\n# Hybrid Search Configuration\n# Controls weighting between vector similarity and knowledge graph relationships\nhybrid_search:\n  # Option 1: Use a preset (recommended)\n  preset: current  # current, semantic_focused, graph_focused, or balanced\n\n  # Option 2: Specify custom weights (must sum to 1.0)\n  # vector_weight: 0.7  # Weight for vector similarity (0.0-1.0)\n  # graph_weight: 0.3   # Weight for knowledge graph (0.0-1.0)\n\nrepositories:\n  - url: https://github.com/anthropics/skills.git\n    priority: 100\n    auto_update: true\n  - url: https://github.com/obra/superpowers.git\n    priority: 90\n    auto_update: true\n  - url: https://github.com/ComposioHQ/awesome-claude-skills.git\n    priority: 85\n    auto_update: true\n  - url: https://github.com/Prat011/awesome-llm-skills.git\n    priority: 85\n    auto_update: true\n\nvector_store:\n  backend: chromadb\n  embedding_model: all-MiniLM-L6-v2\n\nserver:\n  transport: stdio\n  log_level: info\n```\n\n#### Hybrid Search Modes\n\nThe 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:\n\n**Available Presets:**\n\n| Preset | Vector | Graph | Best For | Use Case |\n|--------|--------|-------|----------|----------|\n| `current` | 70% | 30% | **General purpose** (default) | Balanced skill discovery with slight semantic emphasis |\n| `semantic_focused` | 90% | 10% | Natural language queries | \"help me debug async code\" → emphasizes semantic understanding |\n| `graph_focused` | 30% | 70% | Related skill discovery | Starting from \"pytest\" → discovers pytest-fixtures, pytest-mock |\n| `balanced` | 50% | 50% | Equal weighting | General purpose when unsure which approach is better |\n\n**When to use each mode:**\n\n- **`current`** (default): Best for most users. Proven through testing to work well for typical skill discovery patterns.\n- **`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\".\n- **`graph_focused`**: Use when you want to explore skill ecosystems and dependencies. Perfect for \"what else works with X?\" queries.\n- **`balanced`**: Use when you want equal emphasis on both approaches, or as a starting point for experimentation.\n\n**Configuration Examples:**\n\n```yaml\n# Use preset (recommended)\nhybrid_search:\n  preset: current\n\n# OR specify custom weights\nhybrid_search:\n  vector_weight: 0.8\n  graph_weight: 0.2\n```\n\n**CLI Override:**\n\nYou can override the config file setting using the `--search-mode` flag:\n\n```bash\n# Use semantic-focused mode for this search\nmcp-skillset search \"python testing\" --search-mode semantic_focused\n\n# Use graph-focused mode for recommendations\nmcp-skillset recommend --search-mode graph_focused\n\n# Available modes: semantic_focused, graph_focused, balanced, current\n```\n\n### Project Configuration (`.mcp-skillset.yaml`)\n\n```yaml\nproject:\n  name: my-project\n  toolchain:\n    primary: Python\n    frameworks: [Flask, SQLAlchemy]\n\nauto_load:\n  - systematic-debugging\n  - test-driven-development\n```\n\n## CLI Commands\n\nmcp-skillset provides a rich, interactive CLI with comprehensive command-line options and beautiful terminal output powered by Rich and Questionary.\n\n### Quick Reference\n\n| Command | Purpose | Key Options |\n|---------|---------|-------------|\n| `setup` | Initial configuration wizard | `--auto`, `--project-dir` |\n| `config` | View/modify configuration | `--show`, `--set` |\n| `index` | Rebuild indices | `--incremental`, `--force` |\n| `install` | Install for AI agents | `--agent`, `--dry-run` |\n| `mcp` | Start MCP server | `--dev` |\n| `build-skill` | Create progressive skills | `--interactive`, `--preview`, `--template` |\n| `search` | Find skills by query | `--limit`, `--category`, `--search-mode` |\n| `list` | List all skills | `--category`, `--compact` |\n| `info` / `show` | Show skill details | (skill-id argument) |\n| `recommend` | Get recommendations | `--search-mode` |\n| `demo` | Interactive skill explorer | `--interactive` |\n| `repo add` | Add skill repository | `--priority` |\n| `repo list` | List repositories | - |\n| `repo update` | Update repositories | (optional repo-id) |\n| `discover search` | Search GitHub for repos | `--min-stars`, `--limit` |\n| `discover trending` | Get trending repos | `--timeframe`, `--topic` |\n| `discover topic` | Search by GitHub topic | `--min-stars` |\n| `discover verify` | Verify SKILL.md files | (repo-url argument) |\n| `discover limits` | Show API rate limits | - |\n| `doctor` | Health check | - |\n| `stats` | Usage statistics | - |\n| `enrich` | Enrich prompts | `--max-skills`, `--full`, `--output` |\n\n**Global options:** `--version`, `--verbose`, `--debug`, `--help`\n\n### Core Commands\n\n#### `setup` - Initial Configuration\n\nAuto-configure mcp-skillset for your project with intelligent toolchain detection and automatic agent installation.\n\n```bash\n# Interactive setup wizard (recommended for first-time setup)\nmcp-skillset setup\n\n# Non-interactive setup with defaults (CI/automation)\nmcp-skillset setup --auto\n\n# Skip automatic agent installation (configure manually later)\nmcp-skillset setup --skip-agents\n\n# Setup for specific project directory\nmcp-skillset setup --project-dir /path/to/project\n\n# Custom config file location\nmcp-skillset setup --config ~/.config/mcp-skillset/custom.yaml\n```\n\n**What it does:**\n- Downloads embedding model (~90MB, first run only)\n- Detects project toolchain (Python, TypeScript, Rust, Go, etc.)\n- Clones relevant skill repositories\n- Builds vector + knowledge graph indices\n- Configures MCP server integration\n- **Automatically installs and configures for all detected AI agents** (Claude Desktop, Claude Code, Auggie)\n- Validates setup completion\n\n**First-Run Note:** Allow 2-5 minutes for initial model download. Subsequent runs are instant.\n\n**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.\n\n#### `config` - Configuration Management\n\nView or modify mcp-skillset configuration settings.\n\n```bash\n# Show current configuration (read-only)\nmcp-skillset config\nmcp-skillset config --show\n\n# Set configuration value interactively\nmcp-skillset config --set hybrid_search.preset=semantic_focused\nmcp-skillset config --set repositories[0].auto_update=true\n```\n\n**Configuration file:** `~/.mcp-skillset/config.yaml`\n\n#### `index` - Rebuild Indices\n\nRebuild vector and knowledge graph indices from skill repositories.\n\n```bash\n# Full rebuild (recommended after adding repositories)\nmcp-skillset index\n\n# Incremental indexing (only new/changed skills)\nmcp-skillset index --incremental\n\n# Force full reindex (bypass cache)\nmcp-skillset index --force\n```\n\n**Use cases:**\n- After adding new repositories with `repo add`\n- When skill content has changed\n- Troubleshooting search issues\n- Switching embedding models\n\n#### `install` - Agent Integration\n\nInstall MCP SkillSet configuration for AI agents with auto-detection.\n\n```bash\n# Auto-detect and install for all supported agents\nmcp-skillset install\n\n# Install for specific agent\nmcp-skillset install --agent claude-desktop\nmcp-skillset install --agent claude-code\nmcp-skillset install --agent auggie\n\n# Preview installation without making changes\nmcp-skillset install --dry-run\n\n# Force overwrite existing configuration\nmcp-skillset install --force\n```\n\n**Supported agents:**\n- `claude-desktop` - Claude Desktop App\n- `claude-code` - Claude Code CLI\n- `auggie` - Auggie AI Assistant\n- `all` - Install for all detected agents\n\n#### `build-skill` - Progressive Skill Creation\n\nCreate custom progressive skills from templates. Skills are deployed to `~/.claude/skills/` for immediate use.\n\n```bash\n# Interactive mode (recommended)\nmcp-skillset build-skill --interactive\n\n# Standard mode with all parameters\nmcp-skillset build-skill \\\n  --name \"FastAPI Testing\" \\\n  --description \"Comprehensive testing strategies for FastAPI applications\" \\\n  --domain \"web development\" \\\n  --tags \"fastapi,pytest,testing,web\" \\\n  --template web-development\n\n# Preview mode (no deployment)\nmcp-skillset build-skill \\\n  --name \"GraphQL API Design\" \\\n  --description \"Schema-first GraphQL API design\" \\\n  --domain \"api development\" \\\n  --preview\n\n# Disable auto-deployment\nmcp-skillset build-skill \\\n  --name \"Test Skill\" \\\n  --description \"Testing skill creation\" \\\n  --domain \"testing\" \\\n  --no-deploy\n```\n\n**Parameters:**\n- `--name` (required in standard mode): Skill name\n- `--description` (required in standard mode): What the skill does (min 20 chars)\n- `--domain` (required in standard mode): Category (e.g., \"web development\")\n- `--tags` (optional): Comma-separated keywords\n- `--template` (optional): Template choice (default: base)\n  - `web-development` - Full-stack web patterns\n  - `api-development` - REST/GraphQL APIs\n  - `testing` - TDD and testing workflows\n  - `base` - Generic template (advanced users only)\n- `--interactive` (optional): Interactive mode with prompts\n- `--preview` (optional): Show generated content without deploying\n- `--no-deploy` (optional): Disable automatic deployment\n\n**Available Templates:**\n- **web-development**: Frontend, backend, full-stack patterns ✅ Production ready\n- **api-development**: REST, GraphQL, authentication ✅ Production ready\n- **testing**: TDD, unit/integration/E2E testing ✅ Production ready\n- **base**: Generic template ⚠️ Advanced users only (validation limitations)\n\n**Output:**\n- Skills deployed to: `~/.claude/skills/{skill-name}/SKILL.md`\n- Immediately available to Claude Code, Claude Desktop, and Auggie\n- Validation results and warnings displayed\n- Skill ID and path returned\n\n**See also:** [Building Progressive Skills](#building-progressive-skills) section for examples and detailed usage.\n\n#### `mcp` - MCP Server\n\nStart the Model Context Protocol server for integration with code assistants.\n\n```bash\n# Start MCP server (stdio transport)\nmcp-skillset mcp\n\n# Development mode (auto-reload on changes)\nmcp-skillset mcp --dev\n```\n\n**Server details:**\n- Transport: stdio (standard input/output)\n- Protocol: Model Context Protocol v1.0\n- Tools exposed: skills_search, skill_get, skills_recommend, skill_categories, skills_reindex, skill_templates_list, skill_create\n\n### Search \u0026 Discovery Commands\n\n#### `search` - Semantic Search\n\nSearch for skills using natural language queries with hybrid RAG (vector + knowledge graph).\n\n```bash\n# Basic search\nmcp-skillset search \"python testing\"\n\n# Limit results\nmcp-skillset search \"debugging\" --limit 5\n\n# Filter by category\nmcp-skillset search \"testing\" --category \"Python\"\n\n# Override search mode (semantic vs graph weighting)\nmcp-skillset search \"async patterns\" --search-mode semantic_focused\nmcp-skillset search \"pytest fixtures\" --search-mode graph_focused\n```\n\n**Search modes:**\n- `current` (default) - 70% semantic, 30% graph\n- `semantic_focused` - 90% semantic, 10% graph (best for fuzzy queries)\n- `graph_focused` - 30% semantic, 70% graph (best for related skills)\n- `balanced` - 50% semantic, 50% graph\n\n**Examples:**\n```bash\n# Find testing skills for Python\nmcp-skillset search \"python unit testing frameworks\"\n\n# Discover debugging techniques\nmcp-skillset search \"debugging techniques\" --limit 3\n\n# Find skills related to async programming\nmcp-skillset search \"asynchronous programming\" --search-mode graph_focused\n```\n\n#### `list` - List All Skills\n\nDisplay all available skills with filtering options.\n\n```bash\n# List all skills\nmcp-skillset list\n\n# Filter by category\nmcp-skillset list --category \"Testing\"\n\n# Compact output (table format)\nmcp-skillset list --compact\n```\n\n**Output formats:**\n- Default: Rich panels with descriptions\n- Compact: Table view with ID, title, category\n\n#### `info` / `show` - Skill Details\n\nShow detailed information about a specific skill.\n\n```bash\n# Show skill details (both commands are identical)\nmcp-skillset info pytest-fixtures\nmcp-skillset show systematic-debugging\n\n# Output includes:\n# - Full skill ID and title\n# - Description\n# - Category\n# - Repository source\n# - Full instructions preview\n```\n\n#### `recommend` - Smart Recommendations\n\nGet intelligent skill recommendations based on your project's toolchain.\n\n```bash\n# Get recommendations for current directory\nmcp-skillset recommend\n\n# Override search mode for recommendations\nmcp-skillset recommend --search-mode graph_focused\n```\n\n**How it works:**\n1. Analyzes project directory (package.json, pyproject.toml, Cargo.toml, etc.)\n2. Detects primary language and frameworks\n3. Searches for relevant skills using detected toolchain\n4. Ranks by relevance to your tech stack\n\n**Example output:**\n```\n🎯 Recommended Skills for Python Project\n\n1. pytest-advanced-fixtures\n   Category: Testing | Relevance: 0.92\n   Advanced pytest fixture patterns for complex test scenarios\n\n2. python-async-debugging\n   Category: Debugging | Relevance: 0.88\n   Debug async/await code with modern Python tools\n```\n\n#### `demo` - Interactive Skill Explorer\n\nGenerate example prompts and explore skills interactively.\n\n```bash\n# Interactive menu (browse all skills)\nmcp-skillset demo\n\n# Interactive mode explicitly\nmcp-skillset demo --interactive\n\n# Generate examples for specific skill\nmcp-skillset demo pytest-fixtures\nmcp-skillset demo systematic-debugging\n```\n\n**Features:**\n- Browse all skills with Rich menu\n- Auto-generates relevant example questions\n- Extracts key concepts from skill instructions\n- Shows practical use cases\n\n**Example output:**\n```\n📚 Demo: pytest-fixtures\n\nKey Concepts:\n- Fixture scopes (function, class, module, session)\n- Fixture dependencies and chaining\n- Parametrized fixtures\n- Fixture cleanup and teardown\n\nExample Questions:\n1. How do I create a database fixture with session scope?\n2. Show me how to parametrize fixtures for multiple test cases\n3. What's the best way to chain fixtures together?\n```\n\n### Repository Management Commands\n\n#### `repo add` - Add Repository\n\nAdd a new skill repository to your configuration.\n\n```bash\n# Add repository with default priority\nmcp-skillset repo add https://github.com/user/skills.git\n\n# Add with custom priority (higher = searched first)\nmcp-skillset repo add https://github.com/user/skills.git --priority 100\n```\n\n**Priority levels:**\n- 100: Highest (official repositories)\n- 50: Medium (default, community repositories)\n- 10: Low (experimental repositories)\n\n#### `repo list` - List Repositories\n\nDisplay all configured skill repositories.\n\n```bash\nmcp-skillset repo list\n```\n\n**Output includes:**\n- Repository URL\n- Priority level\n- Auto-update status\n- Last update timestamp\n- Number of skills indexed\n\n#### `repo update` - Update Repositories\n\nPull latest changes from skill repositories.\n\n```bash\n# Update all repositories\nmcp-skillset repo update\n\n# Update specific repository by ID\nmcp-skillset repo update anthropic-skills\n```\n\n**Note:** After updating, run `mcp-skillset index --incremental` to index new skills.\n\n### GitHub Discovery Commands\n\nAutomatically discover skill repositories on GitHub.\n\n#### `discover search` - Search GitHub\n\nSearch GitHub for skill repositories using natural language queries.\n\n```bash\n# Basic search\nmcp-skillset discover search \"python testing\"\n\n# With minimum stars filter\nmcp-skillset discover search \"fastapi\" --min-stars 10\n\n# Limit results\nmcp-skillset discover search \"react typescript\" --limit 20\n```\n\n**Features:**\n- Natural language search queries\n- Automatic SKILL.md verification\n- Star count filtering\n- Rich metadata display (stars, forks, topics, license)\n\n#### `discover trending` - Get Trending Repos\n\nFind recently updated skill repositories.\n\n```bash\n# Weekly trending (default)\nmcp-skillset discover trending\n\n# Monthly trending\nmcp-skillset discover trending --timeframe month\n\n# Filter by topic\nmcp-skillset discover trending --topic claude-skills\n```\n\n**Timeframes:** `week`, `month`, `year`\n\n#### `discover topic` - Search by Topic\n\nSearch repositories by GitHub topic.\n\n```bash\n# Search by topic\nmcp-skillset discover topic claude-skills\n\n# With stars filter\nmcp-skillset discover topic mcp-skills --min-stars 5\n```\n\n**Common topics:**\n- `claude-skills` - Claude AI skills\n- `anthropic-skills` - Anthropic skills\n- `mcp-skills` - MCP protocol skills\n- `ai-skills` - General AI skills\n\n#### `discover verify` - Verify Repository\n\nVerify that a repository contains SKILL.md files before adding.\n\n```bash\nmcp-skillset discover verify https://github.com/anthropics/skills.git\n```\n\n**Output includes:**\n- SKILL.md verification status\n- Repository metadata (stars, forks, license)\n- Topics and description\n- Command to add repository if valid\n\n#### `discover limits` - API Rate Limits\n\nCheck your current GitHub API rate limit status.\n\n```bash\nmcp-skillset discover limits\n```\n\n**Rate limits:**\n- Unauthenticated: 60 requests/hour\n- Authenticated (with token): 5000 requests/hour\n\n**To increase limits:**\n```bash\nexport GITHUB_TOKEN=your_github_token_here\n```\n\n**See also:** [GitHub Discovery Documentation](./docs/GITHUB_DISCOVERY.md) for detailed usage and configuration.\n\n### Utility Commands\n\n#### `doctor` - Health Check\n\nRun comprehensive system health check and validation.\n\n```bash\nmcp-skillset doctor\n```\n\n**Checks performed:**\n- Configuration file validity\n- Repository accessibility\n- Index integrity (vector + knowledge graph)\n- Embedding model availability\n- Database connectivity\n- Disk space and permissions\n\n**Example output:**\n```\n🏥 MCP SkillSet Health Check\n\n✅ Configuration: OK\n✅ Repositories: 3 configured, all accessible\n✅ Vector Store: 147 skills indexed\n✅ Knowledge Graph: 147 nodes, 423 edges\n✅ Embedding Model: all-MiniLM-L6-v2 (cached)\n✅ Database: SQLite OK\n✅ Disk Space: 2.3 GB available\n\nSystem Status: Healthy ✅\n```\n\n#### `stats` - Usage Statistics\n\nDisplay usage statistics and metrics.\n\n```bash\nmcp-skillset stats\n```\n\n**Metrics displayed:**\n- Total skills indexed\n- Skills by category\n- Skills by repository\n- Search query counts\n- Most used skills\n- Index size and memory usage\n\n#### `enrich` - Prompt Enrichment\n\nEnrich prompts with relevant skill context (advanced feature).\n\n```bash\n# Enrich a prompt with relevant skills\nmcp-skillset enrich \"help me write tests for async functions\"\n\n# Limit skills included\nmcp-skillset enrich \"debug memory leak\" --max-skills 2\n\n# Include full skill instructions (vs brief summaries)\nmcp-skillset enrich \"testing strategy\" --full\n\n# Set relevance threshold (0.0-1.0)\nmcp-skillset enrich \"python patterns\" --threshold 0.8\n\n# Save enriched prompt to file\nmcp-skillset enrich \"code review checklist\" --output enriched_prompt.txt\n\n# Copy to clipboard (requires pyperclip)\nmcp-skillset enrich \"refactoring\" --clipboard\n```\n\n**What it does:**\n1. Searches for relevant skills based on your prompt\n2. Extracts key concepts and instructions from top matches\n3. Augments your prompt with skill context\n4. Outputs enriched prompt for use with LLMs\n\n### Global Options\n\nAll commands support these global flags:\n\n```bash\n# Show version\nmcp-skillset --version\n\n# Verbose output\nmcp-skillset --verbose search \"testing\"\n\n# Debug mode (detailed logs)\nmcp-skillset --debug search \"testing\"\n\n# Help for any command\nmcp-skillset --help\nmcp-skillset search --help\nmcp-skillset repo --help\n```\n\n### Command Workflows\n\n**First-Time Setup Flow:**\n```bash\n# 1. Install mcp-skillset (recommended - fastest)\nuv tool install mcp-skillset\n\n# Alternative installation methods:\n# pipx install mcp-skillset\n# pip install mcp-skillset\n\n# 2. Run setup wizard (includes agent installation)\nmcp-skillset setup\n\n# 3. Verify installation\nmcp-skillset doctor\n\n# 4. Explore available skills\nmcp-skillset list\n```\n\n**Daily Usage Pattern:**\n```bash\n# Morning: Get recommendations for your project\ncd ~/my-project\nmcp-skillset recommend\n\n# Search for specific skill when needed\nmcp-skillset search \"async debugging\"\n\n# View skill details before using\nmcp-skillset info python-async-debugging\n\n# Start MCP server for Claude integration\nmcp-skillset mcp\n```\n\n**Adding New Skill Repository:**\n```bash\n# 1. Add repository\nmcp-skillset repo add https://github.com/user/custom-skills.git\n\n# 2. Rebuild index to include new skills\nmcp-skillset index --incremental\n\n# 3. Search new skills\nmcp-skillset search \"custom skill topic\"\n```\n\n## Shell Completions\n\nEnable tab completion for the `mcp-skillset` command to speed up your workflow:\n\n### Quick Install\n\n**Bash** (requires Bash 4.4+):\n```bash\neval \"$(_MCP_SKILLS_COMPLETE=bash_source mcp-skillset)\" \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n**Zsh** (macOS default):\n```zsh\neval \"$(_MCP_SKILLS_COMPLETE=zsh_source mcp-skillset)\" \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n**Fish**:\n```fish\necho 'eval (env _MCP_SKILLS_COMPLETE=fish_source mcp-skillset)' \u003e\u003e ~/.config/fish/config.fish\nsource ~/.config/fish/config.fish\n```\n\n### Features\n\n- ✅ Complete all commands and subcommands\n- ✅ Complete option flags (`--help`, `--limit`, etc.)\n- ✅ Works with `mcp-skillset`, `mcp-skillset repo`, and all other commands\n\n### Verification\n\nTest completions are working:\n```bash\nmcp-skillset \u003cTAB\u003e        # Shows: config health index info list mcp recommend repo search setup stats\nmcp-skillset repo \u003cTAB\u003e   # Shows: add list update\nmcp-skillset search --\u003cTAB\u003e  # Shows: --category --help --limit\n```\n\n### Documentation\n\nFor detailed installation instructions, troubleshooting, and advanced usage, see [docs/SHELL_COMPLETIONS.md](docs/SHELL_COMPLETIONS.md).\n\n## MCP Tools\n\nmcp-skillset provides 7 MCP tools for AI assistants:\n\n1. **skills_search** - Semantic search with hybrid RAG (vector + knowledge graph)\n2. **skill_get** - Retrieve complete skill details by ID\n3. **skills_recommend** - Context-aware skill recommendations based on project toolchain\n4. **skill_categories** - Browse available skill categories and toolchains\n5. **skills_reindex** - Rebuild search indices (vector store + knowledge graph)\n6. **skill_templates_list** - List available skill templates for progressive skill creation\n7. **skill_create** - Create progressive skills from templates and deploy to ~/.claude/skills/\n\n### Tool Details\n\n#### 1. skills_search\nNatural language semantic search over all indexed skills using hybrid RAG.\n\n**Parameters**:\n- `query` (required): Search query string\n- `limit` (optional): Maximum number of results (default: 10)\n- `category` (optional): Filter by skill category\n\n**Returns**: Array of matching skills with relevance scores\n\n**Example**:\n```python\n# Search for testing skills\nresults = await skills_search(\n    query=\"python unit testing frameworks\",\n    limit=5\n)\n\n# Search with category filter\nresults = await skills_search(\n    query=\"debugging\",\n    category=\"Python\"\n)\n```\n\n#### 2. skill_get\nRetrieve complete skill details and instructions by skill ID.\n\n**Parameters**:\n- `skill_id` (required): Unique skill identifier\n\n**Returns**: Full skill object with instructions, metadata, and examples\n\n**Example**:\n```python\n# Get specific skill details\nskill = await skill_get(skill_id=\"pytest-fixtures\")\n\n# Use skill instructions\nprint(skill.instructions)\n```\n\n#### 3. skills_recommend\nGet intelligent skill recommendations based on project toolchain detection.\n\n**Parameters**: None (auto-detects current project)\n\n**Returns**: Array of recommended skills ranked by relevance to detected toolchain\n\n**Example**:\n```python\n# Get recommendations for current project\nrecommendations = await skills_recommend()\n\n# Returns skills relevant to detected languages, frameworks, and tools\n```\n\n#### 4. skill_categories\nList all available skill categories and toolchain associations.\n\n**Parameters**: None\n\n**Returns**: Array of category names with skill counts\n\n**Example**:\n```python\n# List all categories\ncategories = await skill_categories()\n\n# Returns: [\"Python\", \"Testing\", \"Debugging\", \"Web Development\", ...]\n```\n\n#### 5. skills_reindex\nRebuild vector store and knowledge graph indices from skill repositories.\n\n**Parameters**:\n- `force` (optional): Force full reindex (default: false)\n\n**Returns**: Indexing status and statistics\n\n**Example**:\n```python\n# Incremental reindex (only new/changed skills)\nstatus = await skills_reindex()\n\n# Force full reindex\nstatus = await skills_reindex(force=True)\n```\n\n#### 6. skill_templates_list\nList available skill templates with descriptions and use cases.\n\n**Parameters**: None\n\n**Returns**: Array of templates with metadata (name, description, best_for, use_cases)\n\n**Example**:\n```python\ntemplates = await skill_templates_list()\n# Returns: [\n#   {\n#     \"name\": \"web-development\",\n#     \"description\": \"Full-stack web development patterns\",\n#     \"best_for\": \"Web applications\",\n#     \"use_cases\": [\"Frontend\", \"Backend\", \"Full-stack\"]\n#   },\n#   ...\n# ]\n```\n\n#### 7. skill_create\nCreate progressive skills from templates. Skills are deployed to `~/.claude/skills/` for immediate use.\n\n**Parameters**:\n- `name` (required): Skill name\n- `description` (required): What the skill does\n- `domain` (required): Category (e.g., \"web development\")\n- `tags` (optional): List of keywords\n- `template` (optional): Template choice (web-development, api-development, testing, base)\n- `deploy` (optional): Whether to deploy (default: true)\n\n**Returns**: Status, skill_id, skill_path, validation results\n\n**Example**:\n```python\nresult = await skill_create(\n    name=\"FastAPI Testing\",\n    description=\"Comprehensive testing strategies for FastAPI applications\",\n    domain=\"web development\",\n    tags=[\"fastapi\", \"pytest\", \"testing\"],\n    template=\"web-development\",\n    deploy=True\n)\n```\n\n## Development\n\n### Requirements\n\n- Python 3.11+\n- Git\n- uv (recommended) or pip\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/bobmatnyc/mcp-skillset.git\ncd mcp-skillset\n\n# Recommended: Use uv for fastest setup\nuv sync\n\n# Alternative: Use pip\npip install -e \".[dev]\"\n```\n\n### Running from Source (Development Mode)\n\nUse the `./mcp-skillset-dev` script to run commands directly from source without installation:\n\n```bash\n# Run any CLI command\n./mcp-skillset-dev --version\n./mcp-skillset-dev search \"debugging\"\n./mcp-skillset-dev serve --dev\n\n# All arguments pass through\n./mcp-skillset-dev info systematic-debugging\n```\n\n**How it works**:\n1. Sets `PYTHONPATH` to include `src/` directory\n2. Activates local `.venv` if present\n3. Runs `python -m mcp_skills.cli.main` with all arguments\n\n**When to use**:\n- ✅ Rapid iteration during development\n- ✅ Testing changes without reinstalling\n- ✅ Debugging with source code modifications\n- ❌ Production deployments (use `pip install` instead)\n\n**Installed vs. Source**:\n```bash\n# Installed version (from pip install -e .)\nmcp-skillset search \"testing\"\n\n# Source version (no installation required)\n./mcp-skillset-dev search \"testing\"\n```\n\n### Run Tests\n\n```bash\n# With uv (recommended)\nuv run pytest\n\n# With coverage\nuv run pytest --cov\n\n# Or use make\nmake quality\n```\n\n### Performance Benchmarks\n\nmcp-skillset includes comprehensive performance benchmarks to track and prevent regressions:\n\n```bash\n# Run all benchmarks (includes slow tests)\nmake benchmark\n\n# Run fast benchmarks only (skip 10k skill tests)\nmake benchmark-fast\n\n# Compare current performance with baseline\nmake benchmark-compare\n```\n\n**Benchmark Categories**:\n- **Indexing Performance**: Measure time to index 100, 1000, and 10000 skills\n- **Search Performance**: Track query latency (p50, p95, p99) for vector and hybrid search\n- **Database Performance**: Benchmark SQLite operations (lookup, query, batch insert)\n- **Memory Usage**: Monitor memory consumption during large-scale operations\n\n**Baseline Thresholds**:\n- Index 100 skills: \u003c 10 seconds\n- Index 1000 skills: \u003c 100 seconds\n- Search query (p50): \u003c 100ms\n- Search query (p95): \u003c 500ms\n- SQLite lookup by ID: \u003c 1ms\n\n**Benchmark Results**:\n- Results are saved to `.benchmarks/` directory (git-ignored)\n- Use `make benchmark-compare` to detect performance regressions\n- CI/CD can be configured to fail on significant performance degradation\n\n**Example Output**:\n```\n-------------------------- benchmark: 15 tests --------------------------\nName (time in ms)                    Min      Max     Mean   StdDev\n---------------------------------------------------------------------\ntest_vector_search_latency_100      45.2     52.1    47.8     2.1\ntest_lookup_by_id_single             0.3      0.8     0.4     0.1\ntest_hybrid_search_end_to_end       89.5    105.2    94.3     5.2\n---------------------------------------------------------------------\n```\n\n### Linting and Formatting\n\n```bash\nmake lint-fix\n```\n\n### Security Scanning\n\nmcp-skillset includes comprehensive security scanning to identify vulnerabilities in dependencies and code:\n\n#### Automated Security (Dependabot + GitHub Actions)\n\n**Dependabot** automatically:\n- Scans dependencies weekly for vulnerabilities\n- Creates pull requests for security updates\n- Groups minor/patch updates for easier review\n\n**GitHub Actions** runs security scans on every push:\n- Safety: Python dependency vulnerability scanner\n- pip-audit: PyPI package vulnerability auditor\n- Bandit: Python code security linter\n- detect-secrets: Secret detection scanner\n\n#### Manual Security Scanning\n\n```bash\n# Basic security scan (Safety + pip-audit)\nmake security-check\n\n# Comprehensive security audit with reports\nmake security-check-full\n\n# Install security scanning tools\nmake security-install\n\n# Pre-publish with security checks\nmake pre-publish\n```\n\n#### Security Reports\n\nAfter running `make security-check-full`, reports are saved to `.security-reports/`:\n- `safety-report.json` - Dependency vulnerabilities\n- `pip-audit-report.json` - Package vulnerabilities\n- `bandit-report.json` - Code security issues\n\n#### Security Policy\n\nFor vulnerability reporting and security best practices, see [.github/SECURITY.md](.github/SECURITY.md).\n\n**Key security features:**\n- Automated dependency scanning (Dependabot)\n- Weekly security scans (GitHub Actions)\n- Pre-publish security gate\n- Secret detection (detect-secrets)\n- Code security linting (Bandit)\n\n## Documentation\n\n### Deployment \u0026 Release\nSee [docs/DEPLOY.md](docs/DEPLOY.md) for the complete deployment and release workflow, including:\n- Automated release process with Claude MPM multi-agent coordination\n- PyPI publishing with stored credentials\n- Homebrew tap management (consolidated bobmatnyc/tools tap)\n- Pre-release validation, quality gates, and security scanning\n- Post-release verification across all channels\n- Rollback procedures and troubleshooting\n- Quick reference commands for next release\n\n### Architecture\nSee [docs/architecture/README.md](docs/architecture/README.md) for detailed architecture design.\n\n### Skills Collections\nSee [docs/skills/RESOURCES.md](docs/skills/RESOURCES.md) for a comprehensive index of skill repositories compatible with mcp-skillset, including:\n- Official Anthropic skills\n- Community collections (obra/superpowers, claude-mpm-skills, etc.)\n- Toolchain-specific skills (Python, TypeScript, Rust, Go, Java)\n- Operations \u0026 DevOps skills\n- MCP servers that provide skill-like capabilities\n\n## Troubleshooting\n\n### Claude CLI Integration\n\n#### \"Claude CLI not found\" error\n\n**Symptom**: Setup or installation fails with \"Claude CLI not found\" error.\n\n**Solutions**:\n\n1. **Verify Claude Code is installed**:\n   - Make sure Claude Code (VS Code extension) is installed and activated\n   - Check that the extension is up to date\n\n2. **Check if `claude` command is available**:\n   ```bash\n   which claude\n   ```\n   - If the command is not found, reinstall Claude Code\n   - On macOS, the CLI should be at: `/usr/local/bin/claude` or in your PATH\n\n3. **Add to PATH if necessary**:\n   ```bash\n   # Find where Claude CLI is installed\n   find /Applications -name \"claude\" 2\u003e/dev/null\n\n   # Add to PATH in your shell profile (~/.zshrc, ~/.bashrc, etc.)\n   export PATH=\"/path/to/claude/bin:$PATH\"\n   ```\n\n4. **Verify CLI is working**:\n   ```bash\n   claude --version\n   claude mcp list\n   ```\n\n5. **Fallback option**: Use `--skip-agents` flag and configure manually:\n   ```bash\n   mcp-skillset setup --skip-agents\n   # Then use: mcp-skillset install --agent claude-desktop\n   ```\n\n### Model Download Issues\n\nIf you encounter problems downloading the embedding model on first run:\n\n#### 1. Check Internet Connection\n\nThe model is downloaded from HuggingFace Hub. Verify you can reach:\n```bash\ncurl -I https://huggingface.co\n```\n\n#### 2. Manual Model Download\n\nPre-download the model manually if automatic download fails:\n```bash\npython -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')\"\n```\n\nThis downloads the model to `~/.cache/huggingface/` and verifies it works.\n\n#### 3. Proxy Configuration\n\nIf behind a corporate proxy, configure environment variables:\n```bash\nexport HTTP_PROXY=http://proxy.example.com:8080\nexport HTTPS_PROXY=http://proxy.example.com:8080\nexport HF_ENDPOINT=https://huggingface.co  # Or your mirror\n```\n\n#### 4. Offline/Air-Gapped Installation\n\nFor environments without internet access:\n\n**On a machine with internet:**\n1. Download the model:\n   ```bash\n   python -c \"from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')\"\n   ```\n\n2. Package the model cache:\n   ```bash\n   cd ~/.cache/huggingface\n   tar -czf sentence-transformers-model.tar.gz hub/\n   ```\n\n**On the air-gapped machine:**\n1. Transfer `sentence-transformers-model.tar.gz` to the target machine\n\n2. Extract to the HuggingFace cache directory:\n   ```bash\n   mkdir -p ~/.cache/huggingface\n   cd ~/.cache/huggingface\n   tar -xzf /path/to/sentence-transformers-model.tar.gz\n   ```\n\n3. Install mcp-skillset (transfer wheel if needed):\n   ```bash\n   pip install mcp-skillset  # Or install from wheel\n   ```\n\n4. Verify the setup:\n   ```bash\n   mcp-skillset doctor\n   ```\n\n#### 5. Custom Cache Location\n\nIf you need to use a different cache directory:\n```bash\nexport HF_HOME=/custom/path/to/cache\nexport TRANSFORMERS_CACHE=/custom/path/to/cache\nmcp-skillset setup\n```\n\n#### 6. Disk Space Issues\n\nCheck available space in the cache directory:\n```bash\ndf -h ~/.cache/huggingface\n```\n\nThe model requires ~90MB, but allow ~100MB for temporary files during download.\n\n#### 7. Permission Issues\n\nEnsure the cache directory is writable:\n```bash\nmkdir -p ~/.cache/huggingface\nchmod 755 ~/.cache/huggingface\n```\n\n### Common Issues\n\n#### \"Connection timeout\" during model download\n- Check internet connection and firewall settings\n- Try manual download (see step 2 above)\n- Configure proxy if behind corporate network (see step 3 above)\n\n#### \"No space left on device\"\n- Check disk space: `df -h ~/.cache`\n- Clear old HuggingFace cache: `rm -rf ~/.cache/huggingface/*`\n- Use custom cache location (see step 5 above)\n\n#### \"Permission denied\" on cache directory\n- Fix permissions: `chmod 755 ~/.cache/huggingface`\n- Or use custom cache location with proper permissions\n\n#### Slow initial setup\n- First run downloads ~90MB and builds indices\n- Expected time: 2-10 minutes depending on connection speed and number of skills\n- Subsequent runs use cached model and are much faster\n\n### Getting Help\n\nIf you encounter issues not covered here:\n1. Check [GitHub Issues](https://github.com/bobmatnyc/mcp-skillset/issues)\n2. Review logs: `~/.mcp-skillset/logs/`\n3. Run health check: `mcp-skillset doctor`\n4. Open a new issue with:\n   - Error message and stack trace\n   - Output of `mcp-skillset --version`\n   - Operating system and Python version\n   - Steps to reproduce\n\n## Contributing\n\nContributions welcome! Please read our contributing guidelines first.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `make quality` to ensure tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io)\n- Inspired by [Claude Skills](https://github.com/anthropics/skills)\n- Uses [ChromaDB](https://www.trychroma.com/) for vector search\n- Embeddings via [sentence-transformers](https://www.sbert.net/)\n\n## Links\n\n- **PyPI Package**: [mcp-skillset on PyPI](https://pypi.org/project/mcp-skillset/)\n- **Documentation**: [GitHub Wiki](https://github.com/bobmatnyc/mcp-skillset/wiki)\n- **Issue Tracker**: [GitHub Issues](https://github.com/bobmatnyc/mcp-skillset/issues)\n- **MCP Registry**: [MCP Servers](https://registry.modelcontextprotocol.io)\n- **Publishing Guide**: [docs/publishing.md](docs/publishing.md)\n\n---\n\n**Status**: ✅ v0.5.0 - Production Ready | **Test Coverage**: 85-96% | **Tests**: 77 passing (48 unit + 29 security)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobmatnyc%2Fmcp-skillset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobmatnyc%2Fmcp-skillset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobmatnyc%2Fmcp-skillset/lists"}