# 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](https://github.com/bzsasson/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

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

```json
{
  "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`)

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

1. **Zero Invasion** — Never modifies existing SKILL.md or agent files
2. **Additive Only** — Existing skill/agent loading mechanisms work unchanged
3. **Lazy Loading** — Content loaded only when explicitly requested
4. **Multi-Source** — Scans all known skill/agent directories
5. **Auto-Categorize** — Intelligent keyword-based categorization
6. **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

## Categories

| Category | Label | Description |
|----------|-------|-------------|
| development | 开发工具 | Coding standards, build tools |
| architecture | 架构设计 | System design, patterns, frameworks |
| testing | 测试 | TDD, unit/integration/E2E testing |
| review | 代码审查 | Code review, refactoring |
| security | 安全 | Security audit, vulnerability detection |
| research | 研究 | Web search, deep research |
| communication | 沟通写作 | Docs, articles, social media |
| devops | 运维部署 | CI/CD, Docker, Git workflows |
| orchestration | 编排调度 | Multi-agent, parallel execution |
| lark | 飞书 | Lark/Feishu integrations |
| language | 编程语言 | Language-specific patterns |
| platform | 平台工具 | Obsidian, GitHub, X, MCP |
| planning | 规划管理 | Task planning, requirements |
| learning | 学习教育 | Tutorials, mentoring |
| business | 商业领域 | Supply chain, logistics, energy |

## Configuration

Edit `config.json` to customize scanned directories:

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

## Standalone Indexer

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