SkillLoader

Keep every skill. Load only the one you need.

SkillLoader is a Go MCP server prototype that keeps a large skill catalog outside an AI agent's steady-state context. The agent searches the catalog and loads the smallest matching skill only when a task needs it.

Status: local prototype. Core, parity, subprocess MCP, synthetic benchmark, and one live Codex routing fixture are verified. Large-catalog product benefit, task-completion quality, release packaging, and public multi-client compatibility are not complete.

Registering many skills directly with an AI client can make their names and descriptions part of the always-available context. SkillLoader is designed to decouple catalog size from that steady-state prompt cost.

AI client
  |  small bootstrap + MCP tool schemas
  v
SkillLoader MCP server
  |-- search compact metadata
  |-- load one selected skill
  |-- validate trusted catalog roots
  `-- cache indexes and parsed documents

The complete catalog stays on the server. A normal task should expose only:

1. the small SkillLoader tool definitions;
2. a bounded set of search matches; and
3. the body of the selected skill.

Every load reads and hashes the current file bytes before consulting the document cache. The cache avoids re-validating unchanged frontmatter; its core latency effect is measured only on synthetic fixtures. It does not remove the tokens of a returned skill body.

Catalog inspection and diagnostics remain direct CLI commands so their schemas do not consume model context:

skillloader list --json
skillloader doctor --json

The implemented request and response shapes are defined in docs/MCP_CONTRACT.md.

Install with one command:

go install github.com/voodoosim/skillloader@latest

Node.js users can install the published npm launcher:

npx skillloader-mcp@0.1.4

Package page: skillloader-mcp on npm

Unix users can use the user-local installer, and Codex users can register the stdio MCP server in the same command. Client-specific instructions and pinned release assets are documented in INSTALL.md.

• Required Go toolchain: 1.26.5 or newer
• One Go binary named skillloader
• MCP over stdio for local clients
• Two model-visible MCP tools
• Stable JSON output for direct CLI diagnostics

Live Codex CLI 0.144.6 and Claude Code CLI 2.1.212 both completed the same isolated 12-task, 10-skill Gate-6 routing fixture (docs/BENCHMARK.md). Neither shows a positive token or cost saving at this small catalog size; see the benchmark doc for the exact numbers and the Claude-Code-specific ToolSearch deferred-tool overhead. OpenCode 1.18.4 has also completed a live local search/load and warm-cache check. See docs/CLIENT_BOOTSTRAP.md for registration and isolated verification commands.

SKILLLOADER_ROOTS may override the default roots with a comma-separated list of literal paths. It performs whitespace trimming only; relative paths resolve against the process working directory, and quoting, tilde expansion, and glob expansion are not supported. Search tokenization currently supports English letters, digits, Hangul, and hyphens.

Streamable HTTP, Docker, and additional client integrations are post-MVP work. They start only after the local token and routing claims are measured.

The MCP specification defines tools as schema-described interfaces whose calls return structured or unstructured content. SkillLoader uses typed output schemas, structured content, and a JSON TextContent compatibility copy: MCP tools specification.

No positive token-reduction percentage is proven. In the recorded live Codex 10-skill fixture, SkillLoader reduced the offline initial static estimate by 12.94%, but client-reported total input increased 242.84% because search and load add model turns. This small synthetic result does not establish a large-catalog break-even point; see docs/BENCHMARK.md and docs/PRODUCT_EVIDENCE.md.

• docs/ARCHITECTURE.md — components and trust boundaries
• docs/MCP_CONTRACT.md — current prototype interface
• docs/DEPENDENCY_REVIEW.md — transitive module paths and security checks
• docs/BENCHMARK.md — token, routing, and latency evaluation
• CONTRIBUTING.md — contribution and verification rules

• Claiming that caching alone reduces model tokens
• Treating arbitrary downloaded skill documents as trusted instructions
• Sending local filesystem paths as portable skill identifiers
• Claiming compatibility with a client before its integration is tested

MIT. See LICENSE.