mcp-skillbox

An MCP (Model Context Protocol) server that aggregates agent skills from skills.sh and compatible GitHub skill repositories and exposes exactly three tools — list_skills, search_skills, load_skill — so agents can discover and load skills without bloating their context window: metadata-first browsing (compact summaries, no descriptions by default), and full skill content fetched only on demand, with byte caps and size reporting.

Features

• Context-budget design: list_skills and search_skills return compact metadata only (no descriptions by default); full skill content is fetched only via load_skill, on demand.

• Description truncation at 300 chars when descriptions are requested (include_description).

• size_bytes reporting on every loaded file, plus max_bytes caps — both per-call (load_skill) and registry-level (SKILL_MAX_BYTES).

• TTL caching (list/search 60s, details 5 min, GitHub trees 10 min) to cut API calls.

• Resilient HTTP: retries with exponential backoff + jitter, timeouts, and Retry-After handling for 429s.

• Registry abstraction with two adapters: skills.sh (OIDC token mode, richer data incl. install counts) and GitHub (unauthenticated mode that works out of the box).

• Optional skills.sh OIDC token mode for install counts and leaderboard data.

Related MCP server: suggest-skills

Tools

load_skill is the only context-heavy call; list_skills/search_skills are intentionally cheap.

How it works / architecture

src/server.ts registers the 3 tools; factory.createRegistry() picks the adapter (auto: token → skills.sh, else GitHub); each adapter implements the SkillRegistry interface (listSkills/searchSkills/loadSkill); both use TTL caches and retry/backoff. GitHub mode reads repo trees via the GitHub API and fetches SKILL.md files from raw.githubusercontent.com.

┌─────────────┐   stdio JSON-RPC   ┌───────────────────────────────┐
│  Agent /    │ ◄────────────────► │  mcp-skillbox  (src/server.ts) │
│ MCP client  │                    │  list_skills / search_skills  │
└─────────────┘                    │  / load_skill   (3 tools)     │
                                   └───────────────┬───────────────┘
                                                   │  SkillRegistry
                                   ┌───────────────▼───────────────┐
                                   │ factory.createRegistry(config)│
                                   │  auto: token ? skills.sh      │
                                   │        : github               │
                        └──────┬──────────────────────────────────┬────────┘
                               │                                  │
                              ┌▼───────────────────────┐   ┌──────▼─────────────────┐
                              │ skills.sh API          │   │ GitHub API (trees)     │
                              │ /api/v1/*              │   │ + raw.githubusercontent│
                              │ Bearer OIDC            │   │ (unauthenticated)      │
                              └────────────────────────┘   └────────────────────────┘
                         TTL caches + retry/backoff live in both adapters

Requirements

• Node.js >= 18

• npm

Install & run

npm install
npm run build
npm run smoke:mcp   # optional end-to-end check over a real stdio MCP session

MCP client configuration

mcp-skillbox speaks MCP over stdio; register it in any MCP-capable client. All configs below assume a local checkout; swap in npx -y github:beremaran/mcp-skillbox (works today; once published, npx -y mcp-skillbox).

Claude Code

Add to .mcp.json (project) or ~/.claude.json (user):

{
  "mcpServers": {
    "skillbox": {
      "command": "npx",
      "args": ["-y", "mcp-skillbox"],
      "env": {
        "SKILLS_SH_TOKEN": "your-vercel-oidc-token"
      }
    }
  }
}

For local development use the built artifact directly:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": ["/absolute/path/to/agent-skillbox/dist/index.js"],
      "env": {}
    }
  }
}

Equivalent CLI form:

claude mcp add skillbox -- npx -y mcp-skillbox
claude mcp add skillbox -- node /absolute/path/to/agent-skillbox/dist/index.js

opencode

Add to opencode.json under the mcp key. Verified schema (opencode 1.18.x): a local stdio server uses "type": "local" and command is an ARRAY of strings (executable + args together — there is no separate args key):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "skillbox": {
      "type": "local",
      "command": ["node", "/absolute/path/to/agent-skillbox/dist/index.js"],
      "enabled": true,
      "environment": {
        "SKILLS_SH_TOKEN": "your-vercel-oidc-token"
      }
    }
  }
}

Cursor / VS Code / any stdio MCP client

Generic mcpServers shape:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": ["/absolute/path/to/agent-skillbox/dist/index.js"]
    }
  }
}

Published package

From the public GitHub repo (works today): npx -y github:beremaran/mcp-skillbox (command npx, args ["-y", "github:beremaran/mcp-skillbox"]). Once published to npm, any client can also use npx -y mcp-skillbox (command npx, args ["-y", "mcp-skillbox"]).

Environment variables

How registry selection works

In auto mode: if SKILLS_SH_TOKEN is set → skills.sh registry (its API requires Authorization: Bearer <VERCEL_OIDC_TOKEN>; requests without it get 401, rate limit ~600 req/min). Otherwise → GitHub registry using the public GitHub API + raw.githubusercontent.com, which works immediately with no credentials. SKILL_REGISTRY=github or =skills-sh forces a specific adapter (skills-sh without a token throws a clear RegistryAuthError).

Example agent conversation (context-budget behavior)

Agent:  I need to add tests for a React component. Let me find a skill.

Agent → search_skills({ query: "react testing", include_description: true })

mcp-skillbox → { count: 3, results: [
  { id: "vercel-labs/agent-skills/react-testing",  name: "React Testing",       source: "vercel-labs/agent-skills", description: "Setup and patterns for testing React components with Vitest..." },
  { id: "mattpocock/skills/react-hooks-testing",   name: "React Hooks Testing", source: "mattpocock/skills",        description: "Best practices for testing custom React hooks in isolation..." },
  { id: "prisma/skills/e2e-testing",               name: "E2E Testing",         source: "prisma/skills",             description: "End-to-end testing setup for web apps..." }
] }

Agent:  "react-testing" is the best fit.

Agent → load_skill({ id: "vercel-labs/agent-skills/react-testing" })

mcp-skillbox → { id: "vercel-labs/agent-skills/react-testing", name: "React Testing", files: [
  { path: "SKILL.md", size_bytes: 8421, contents: "# React Testing\n..." }
] }

Agent:  Uses the full SKILL.md instructions to write the tests.

The agent only ever paid for the full content of the skill it actually used — the two losing skills cost nothing beyond their ~300-char previews.

Development

• npm test — vitest unit/integration tests (8 files)

• npm run typecheck — tsc --noEmit

• npm run build — emit dist/

• npm run dev — watch build

• npm run smoke — real-network GitHub registry smoke (tsx src/smoke.ts)

• npm run smoke:mcp — full end-to-end MCP smoke over stdio (node scripts/mcp-smoke.mjs; spawns dist/index.js, lists 3 tools, calls list_skills + load_skill for real)

• Tests live in tests/ (cache, factory, frontmatter, github, http, index, server, skills-sh).

IMPORTANT: The @modelcontextprotocol/sdk root import is broken in v1.30.0 — always import from subpaths (@modelcontextprotocol/sdk/server/mcp.js, /server/stdio.js, /client/index.js, /inMemory.js). The registerTool(name, config, callback) form is the tool-registration API.

Limitations & roadmap

• skills.sh install counts/leaderboard require the OIDC token; GitHub mode has no install counts.

• GitHub unauthenticated API rate limits (~60 req/hr for contents/trees) — mitigated by tree caching (10 min TTL) and fetching file contents from raw.githubusercontent.com (which is not rate-limited the same way).

• No write/install tools yet. Roadmap: install skills to a target directory, packs support, multi-registry federation, HTTP/SSE transport, resource endpoints for installed skills.

License

MIT — see LICENSE.