Skill & Agent Gateway

Dynamic Context Loading for Claude Code Skills and Agents

An MCP server that provides intelligent discovery, search, and on-demand loading of Claude Code skills and agents — inspired by DCL Wrapper's lazy-loading pattern for MCP servers.

Problem

When using Claude Code with many extensions (OMC, SuperClaude, ECC, Superpowers, etc.), you accumulate 200+ skills and 100+ agents. All their descriptions are loaded into the system prompt on every conversation, consuming thousands of tokens before you even start working.

Solution

This gateway replaces the "load everything" approach with 6 lightweight MCP tools:

| Tool | Purpose | |------|---------| | gateway_discover | Browse skills/agents by category | | gateway_search | Keyword search (CN/EN) | | gateway_load | Load specific skill/agent details | | gateway_recommend | Task-based skill+agent recommendations | | gateway_stats | Ecosystem statistics | | gateway_rebuild_index | Refresh index from disk |

Zero impact on existing frameworks — Cursor's <available_skills>, OMC, SuperClaude, and Superpowers continue working unchanged. The gateway is a purely additive layer.

Quick Start

# Clone
git clone https://github.com/YanShawn/skill-agent-gateway.git
cd skill-agent-gateway

# Setup (creates venv, installs deps, builds index)
chmod +x setup.sh
./setup.sh

# Or manual setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python indexer.py --stats

MCP Configuration

Claude Code (`~/.claude.json`)

Add to the mcpServers section:

{
  "skill-agent-gateway": {
    "command": "/path/to/skill-agent-gateway/.venv/bin/python",
    "args": ["/path/to/skill-agent-gateway/gateway.py"],
    "env": {}
  }
}

Cursor IDE (`~/.cursor/mcp.json`)

{
  "mcpServers": {
    "skill-agent-gateway": {
      "command": "/path/to/skill-agent-gateway/.venv/bin/python",
      "args": ["/path/to/skill-agent-gateway/gateway.py"],
      "env": {}
    }
  }
}

Usage Examples

Discover categories

gateway_discover()
→ Lists all categories with counts (development, architecture, testing, etc.)

Search for skills

gateway_search(query="飞书日历")
→ Finds lark-calendar, lark-workflow-standup-report, etc.

gateway_search(query="tdd", resource_type="skill")
→ Finds tdd-workflow, tdd-guide, test-driven-development, etc.

Get task recommendations

gateway_recommend(task_description="重构后端 API 并写测试")
→ Skills: backend-patterns, tdd-workflow, api-design
→ Agents: code-reviewer, tdd-guide, refactoring-expert

Load specific skill

gateway_load(name="web-access", resource_type="skill")
→ Category, description, triggers, keywords, file path

gateway_load(name="web-access", resource_type="skill", detail_level="full")
→ Complete SKILL.md content

Architecture

┌─────────────────────────────────────────────┐
│              AI Agent (Claude)               │
├─────────────────────────────────────────────┤
│   gateway_discover / search / load / ...    │ ← 6 MCP tools
├─────────────────────────────────────────────┤
│           Skill Agent Gateway               │ ← This server
│    ┌──────────┐  ┌──────────┐               │
│    │ Indexer   │  │ Searcher │               │
│    └────┬─────┘  └────┬─────┘               │
│         │              │                     │
│    ┌────▼──────────────▼─────┐               │
│    │      index.json         │               │
│    └─────────────────────────┘               │
├─────────────────────────────────────────────┤
│  ~/.claude/skills/  │ ~/.claude/agents/      │ ← File system
│  ~/.agents/skills/  │ plugins/cache/         │   (unchanged)
│  ~/.codex/skills/   │ ~/.cursor/skills/      │
└─────────────────────────────────────────────┘

Design Principles

Zero Invasion — Never modifies existing SKILL.md or agent files
Additive Only — Existing skill/agent loading mechanisms work unchanged
Lazy Loading — Content loaded only when explicitly requested
Multi-Source — Scans all known skill/agent directories
Auto-Categorize — Intelligent keyword-based categorization
Deduplication — Same skill from multiple sources appears once

Scanned Directories

Skills

~/.claude/skills/ — Primary skills (OMC, Superpowers, etc.)
~/.claude/.agents/skills/ — ECC agent skills
~/.claude/.cursor/skills/ — Cursor-specific skills
~/.cursor/skills-cursor/ — Cursor skills (alternate location)
~/.codex/skills/ — Codex skills
~/.agents/skills/ — Agent skills (Lark, etc.)
~/.claude/plugins/cache/ — Plugin cache (all frameworks)

Agents

~/.claude/agents/ — Agent definitions

Configuration

Edit config.json to customize scanned directories:

{
  "skill_dirs": ["~/.claude/skills", "~/custom/skills"],
  "agent_dirs": ["~/.claude/agents"],
  "plugin_dirs": ["~/.claude/plugins/cache"],
  "skip_agent_names": ["README", "MIGRATION_SUMMARY"]
}

Standalone Indexer

python indexer.py              # Build index with stats
python indexer.py --json       # Output raw JSON
python indexer.py --validate   # Validate existing index
python indexer.py --stats      # Build with detailed breakdown

Requirements

Python 3.11+
MCP Python SDK (mcp>=1.0.0)
python-dotenv

License

MIT

Skill Agent Gateway