SkillDB

skilldb

CLI, TypeScript SDK, and MCP Server for SkillDB — discover, install, and manage AI agent skills.

5,900+ expert skills across 429 packs for Claude Code, Cursor, Windsurf, VS Code, and any MCP-compatible AI tool.

Open source for transparency. This is the full source for the skilldb npm package — the CLI and MCP server that run on your machine and handle your API key. It's published to npm via Trusted Publishing (OIDC, with provenance), so the published artifact is verifiably built from this repo. Audit away, and PRs welcome. MIT licensed.

MCP Server

Connect SkillDB directly to your AI coding tool via the Model Context Protocol:

# Step 1 (optional): install globally. You can also skip this — the npx form below works without it.

npm install -g skilldb

Step 2 (optional): Get a Pro or Studio API key for full content at https://skilldb.dev/api-access

Step 3: Add to Claude Code (omit --api-key for metadata-only access)

claude mcp add skilldb -- npx -p skilldb skilldb-mcp --api-key sk_live_YOUR_KEY

Note: skilldb-mcp is a binary inside the skilldb package, not its own npm package — always invoke it as npx -p skilldb skilldb-mcp (not npx skilldb-mcp).

⚠️ Without an API key, you can search and browse skills (metadata only).

With a Pro or Studio API key, you get full skill content — the actual markdown instructions your agent uses.

Get your key in 30 seconds at skilldb.dev/api-access.

Cursor — add to .cursor/mcp.json:

{

"mcpServers": { "skilldb": { "command": "npx", "args": ["-p", "skilldb", "skilldb-mcp"] } } }

Windsurf — add to mcp_config.json:

{

"mcpServers": { "skilldb": { "command": "npx", "args": ["-p", "skilldb", "skilldb-mcp", "--api-key", "sk_live_xxx"] } } }

VS Code — one-liner:

code --add-mcp '{"name":"skilldb","command":"npx","args":["-p","skilldb","skilldb-mcp"]}'

Or add the same server block to .vscode/mcp.json (workspace) / user mcp.json under "servers".

Once connected, your AI assistant can search and load skills natively. Just ask:

• *"Search SkillDB for React performance patterns"*
• *"Load the code review skill"*
• *"What skills should I use for this project?"*
• *"Save this as a private skill"* (Studio plan — see below)

10 tools exposed: skilldb_search, skilldb_get, skilldb_list, skilldb_suggest, skilldb_recommend, skilldb_purge, skilldb_set_key (set/swap your API key mid-session, no restart), and the private-skill tools skilldb_my_skills, skilldb_create_skill, skilldb_update_skill (Studio plan + write-scoped key).

Hosted MCP endpoints

• Authenticated integration: https://skilldb.dev/api/mcp uses Streamable HTTP with OAuth or a SkillDB API key. Full skill content requires a Pro or Studio account.
• Anonymous SkillDB Catalog: https://skilldb.dev/api/mcp/catalog uses Streamable HTTP without a SkillDB account. Its two tools, skilldb_search and skilldb_get_preview, return public metadata and short previews only. It does not retrieve full skill content, install or execute skills, link accounts, or access private/team libraries.

Quick Start (CLI)

# Search for skills (with inline preview)

npx skilldb search "code review"

Install a skill pack

npx skilldb add software-skills

Activate a smart profile (only loads what you need)

npx skilldb use frontend

Or auto-detect from your project

npx skilldb use auto

Install

npm install -g skilldb

Or use npx skilldb without installing.

The Memory Problem (And How We Solve It)

Loading 500 skills into your agent's context is worse than loading the right 5. SkillDB uses a 3-layer architecture to manage this:

.skilldb/

├── skills/ ← Full cache (everything downloaded) ├── active/ ← Active profile (what your agent sees — 5-15 focused skills) ├── slim/ ← Compressed cheat sheets (10x smaller) ├── config.json ← Profile + budget settings └── manifest.json ← What's installed

Your CLAUDE.md or .cursorrules points at .skilldb/active/, not the full cache. The agent gets focused, relevant skills — not noise.

CLI Commands

Core

skilldb init

Detect your IDE (Claude Code, Cursor, Codex CLI, OpenClaw), create .skilldb/, and add integration config.

skilldb init

skilldb search

Search skills by keyword. Shows inline slim preview so you know what you're getting before downloading.

skilldb search "debugging"

skilldb search "api design" --category "Technology & Engineering" skilldb search "testing" --limit 10

skilldb add

Download a skill pack to local cache. Idempotent — skips already-cached skills.

skilldb add software-skills

skilldb add autonomous-agent-skills skilldb add vibe-coding-security-skills

skilldb get

Download a single skill.

skilldb get software-skills/code-review

skilldb info

Show metadata, slim summary, and full preview for a skill.

skilldb info software-skills/code-review

skilldb list

List available categories, packs, and skills.

skilldb list

skilldb list --category "Autonomous Agents" skilldb list --pack software-skills

skilldb login

Prompts for your API key and saves it to ~/.skilldbrc (user-wide) so every project picks it up via the resolution chain in Authentication. The recommended alternative to setting SKILLDB_API_KEY by hand.

skilldb login

Smart Loading

skilldb use

Activate a focused profile — only loads relevant skills into .skilldb/active/.

skilldb use frontend          # React, testing, web-polish, accessibility

skilldb use backend # API design, databases, security, performance skilldb use devops # Kubernetes, Docker, CI/CD, monitoring skilldb use security # Trust audit, input validation, credentials skilldb use data # SQL, pipelines, analytics, visualization skilldb use fullstack # Frontend + backend combined skilldb use mobile # Mobile / React Native / app development skilldb use ai-agent # Autonomous agent meta-skills skilldb use auto # Auto-detect from your project files skilldb use --list # Show available profiles skilldb use --current # Show active profile skilldb use none # Deactivate (clear active/)

auto mode scans your package.json, file extensions, and imports to recommend the right profile.

skilldb budget

Set a maximum context budget so your agent doesn't get overloaded.

skilldb budget                # Show current usage

skilldb budget set 5000 # Max 5,000 lines skilldb budget set 50k # Max 50,000 tokens skilldb budget optimize # Re-rank and trim active skills to fit

skilldb slim

Generate compressed cheat-sheet versions of skills (~30 lines instead of 300).

skilldb slim                  # Slim all active skills

skilldb slim software-skills # Slim a specific pack skilldb slim --ratio 0.3 # Keep 30% of content

Management

skilldb update

Check for newer versions of installed skills and update them.

skilldb update                # Update everything

skilldb update software-skills # Update one pack

skilldb remove

Uninstall skills from local cache.

skilldb remove software-skills/code-review    # Remove single skill

skilldb remove software-skills # Remove entire pack skilldb remove --unused # Remove skills not in active profile

skilldb doctor

Health check and audit of your skill setup.

skilldb doctor

Shows: outdated skills, unused skills, missing dependencies, budget status, coverage gaps.

skilldb stats

Local statistics dashboard.

skilldb stats

Shows: installed count, total lines, tokens, active profile, categories covered.

skilldb diff

Compare your local (possibly customized) version with the latest remote.

skilldb diff software-skills/code-review

skilldb diff # Diff all installed

skilldb purge

Remove cached skills to free disk space.

skilldb purge --inactive      # Remove skills not in the active profile

skilldb purge --all # Remove ALL cached skills (including active) skilldb purge --slim # Also drop slim summaries skilldb purge --dry-run # Preview what would be removed, delete nothing

Private Skills (Studio)

Create skills that only you (and people you share them with) can read. They surface in your own search results when you're authenticated. Creating/editing requires the Studio plan and an API key with write scope — mint one at skilldb.dev/account#api-keys.

skilldb push

Create (or update) a private skill from a local Markdown file. The skill name defaults to the filename; the title resolves as --title flag → first Markdown # H1 → filename.

skilldb push ./my-react-patterns.md                    # create (pack defaults to "personal")

skilldb push ./my-react-patterns.md -p team --tags react,perf skilldb push ./my-react-patterns.md --update # update the skill with the same name/pack

Options: -p, --pack, -n, --name, -t, --title, -d, --description, --tags , -u, --update.

skilldb my-skills

List your private skills (ones you own plus skills shared with you).

skilldb my-skills

You can also do all of this from your agent via the MCP tools skilldb_create_skill / skilldb_update_skill / skilldb_my_skills.

Sharing & Export

skilldb export

Export your setup for sharing or IDE integration.

skilldb export claude         # CLAUDE.md snippet with skill references

skilldb export cursor # .cursorrules block skilldb export profile # Shareable .skilldb-profile.json skilldb export inject # Print skill to stdout (for piping)

skilldb recommend

Scan your project and get personalized skill recommendations.

skilldb recommend             # Analyze project and suggest

skilldb recommend --install # Auto-install recommendations

SDK Usage

import { createClient } from 'skilldb';

const db = createClient(); // auto-loads key from env/config

// Search with slim previews const results = await db.search('code review'); for (const skill of results.skills) { console.log(skill.title); console.log(skill.slim); // Quick summary }

// Get full skill content (requires a configured Pro or Studio API key) const skill = await db.get('software-skills/code-review.md'); console.log(skill.content);

// List with filters const listing = await db.list({ category: 'Autonomous Agents', limit: 10 });

Authentication

The SDK and CLI resolve your API key in order:

1. SKILLDB_API_KEY environment variable (CI-friendly)
2. .skilldbrc in project root (p