Skill Depot

1# skill-depot
2 
3> RAG-based skill retrieval system for AI agents. Scalable long-term storage with semantic search via MCP.
4 
5**skill-depot** replaces the "dump all skill frontmatter into context" approach with selective, semantic retrieval. Agent skills are stored as Markdown files and indexed with vector embeddings — only the relevant skills are loaded when needed, keeping context lean.
6 
7## ✨ Features
8 
9- **🔍 Semantic Search** — Find skills by meaning, not just keywords, using embedded vector search
10- **🏠 Fully Local** — No API keys, no cloud. Uses SQLite + sqlite-vec for storage and a local transformer model for embeddings
11- **🤖 Agent-Agnostic** — Works with Claude Code, Codex, OpenClaw, Gemini, and any MCP-compatible agent
12- **📂 Two-Scope Storage** — Global skills (`~/.skill-depot/`) available everywhere, project skills (`.skill-depot/`) synced via git
13- **⚡ Auto-Discovery** — Finds existing skills from your AI agents during setup
14- **🔌 MCP Protocol** — Integrates seamlessly as an MCP server with 7 tools for skill management
15 
16## 🚀 Quick Start
17 
18### 1. Initialize
19 
20```bash
21npx skill-depot init
22```
23 
24This will:
25- Create the `~/.skill-depot/` global directory
26- Scan for existing skills in Claude Code, Codex, OpenClaw directories
27- Let you select which skills to import via an interactive checklist
28- Download the embedding model (~80MB, one-time)
29- Index all imported skills
30 
31### 2. Configure Your Agent
32 
33Add skill-depot to your agent's MCP configuration:
34 
35**Claude Code** (`~/.claude/mcp.json`):
36```json
37{
38  "mcpServers": {
39    "skill-depot": {
40      "command": "npx",
41      "args": ["skill-depot", "serve"]
42    }
43  }
44}
45```
46 
47**Codex / OpenClaw / Cursor**: Add the same MCP server config in your agent's settings.
48 
49### 3. Use
50 
51Your agent now has access to these tools:
52 
53| Tool | Description |
54|------|-------------|
55| `skill_search` | Semantic search — returns metadata + snippets |
56| `skill_read` | Load the full content of a skill |
57| `skill_save` | Save a new skill and index it |
58| `skill_update` | Update an existing skill |
59| `skill_delete` | Remove a skill |
60| `skill_reindex` | Rebuild the search index |
61| `skill_list` | List all indexed skills |
62 
63## 📖 How It Works
64 
65### The Problem
66 
67Traditional agent skill systems load **all** skill file frontmatter into the agent's context window every session. With a large skill library, this wastes precious context on irrelevant information.
68 
69### The Solution
70 
71skill-depot acts as a **RAG layer** for agent skills:
72 
731. Skills are stored as Markdown files with YAML frontmatter
742. Each skill is embedded into a 384-dimensional vector using a local transformer model
753. When an agent needs a skill, it searches by meaning — only the most relevant skills are returned
764. The agent can then load the full content of selected skills via a second tool call
77 
78```
79Agent → skill_search("deploy nextjs to vercel")
80     ← [{ name: "deploy-vercel", score: 0.92, snippet: "..." }, ...]
81 
82Agent → skill_read("deploy-vercel")
83     ← Full markdown content of the skill
84```
85 
86### Storage Architecture
87 
88```
89~/.skill-depot/               # Global (all projects)
90├── config.json
91├── models/                    # Embedding model cache
92├── skills/                    # Global skill files
93└── index.db                   # SQLite + vector index
94 
95<project>/.skill-depot/        # Project-level (git-synced)
96├── skills/                    # Project-specific skills
97└── index.db                   # Project vector index (gitignored)
98```
99 
100## 🛠️ CLI Reference
101 
102```bash
103# Setup
104skill-depot init               # Interactive setup + agent discovery
105skill-depot init --auto         # Non-interactive, import everything
106 
107# Server
108skill-depot serve --project .   # Start MCP server (foreground/stdio)
109skill-depot start --project .   # Start as background daemon
110skill-depot stop                # Stop daemon
111skill-depot status              # Check daemon status
112skill-depot restart             # Restart daemon
113 
114# Skill Management
115skill-depot add <file>          # Add a skill file (project scope)
116skill-depot add <file> --global # Add as global skill
117skill-depot remove <name>       # Remove a skill
118skill-depot list                # List all skills
119skill-depot list --global       # List global skills only
120skill-depot search <query>      # Search skills from CLI
121 
122# Maintenance
123skill-depot reindex             # Rebuild all indexes
124skill-depot doctor              # Health check
125```
126 
127## 📝 Skill Format
128 
129Skills use standard YAML frontmatter + Markdown — the same format used by Claude Code, Codex, and other agents:
130 
131```markdown
132---
133name: deploy-to-vercel
134description: How to deploy a Next.js application to Vercel
135tags: [deployment, vercel, nextjs]
136keywords: [vercel cli, production build, environment variables]
137---
138 
139## Steps
140 
1411. Install the Vercel CLI: `npm i -g vercel`
1422. Run `vercel` in the project root
1433. Follow the prompts to link your project
144...
145```
146 
147## 🏗️ Tech Stack
148 
149| Component | Technology |
150|-----------|-----------|
151| Language | TypeScript (ESM) |
152| Database | SQLite via `better-sqlite3` |
153| Vector Search | `sqlite-vec` extension |
154| Embeddings | `@xenova/transformers` (`all-MiniLM-L6-v2`) |
155| Fallback | BM25 term-frequency hashing |
156| Protocol | MCP via `@modelcontextprotocol/sdk` |
157| CLI | `commander` + `inquirer` + `chalk` + `ora` |
158 
159## 🤝 Contributing
160 
161Contributions are welcome! This is an open-source project.
162 
163```bash
164# Clone and install
165git clone https://github.com/your-username/skill-depot.git
166cd skill-depot
167pnpm install
168 
169# Development
170pnpm dev       # Watch mode build
171pnpm test      # Run tests
172pnpm lint      # Type check
173pnpm build     # Production build
174```
175 
176## 📄 License
177 
178MIT
179