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.

[Add SkillDB to Cursor] [Install in VS Code] [npm]

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 packnpx skilldb add software-skills
# Activate a smart profile (only loads what you need)npx skilldb use frontend
# Or auto-detect from your projectnpx 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 <query>

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

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

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

skilldb get <id>

Download a single skill.

skilldb get software-skills/code-review

skilldb info <id>

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 listskilldb 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 <profile>

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

skilldb use frontend          # React, testing, web-polish, accessibilityskilldb use backend           # API design, databases, security, performanceskilldb use devops            # Kubernetes, Docker, CI/CD, monitoringskilldb use security          # Trust audit, input validation, credentialsskilldb use data              # SQL, pipelines, analytics, visualizationskilldb use fullstack         # Frontend + backend combinedskilldb use mobile            # Mobile / React Native / app developmentskilldb use ai-agent          # Autonomous agent meta-skillsskilldb use auto              # Auto-detect from your project filesskilldb use --list            # Show available profilesskilldb use --current         # Show active profileskilldb 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 usageskilldb budget set 5000       # Max 5,000 linesskilldb budget set 50k        # Max 50,000 tokensskilldb 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 skillsskilldb slim software-skills  # Slim a specific packskilldb slim --ratio 0.3      # Keep 30% of content

Management

skilldb update

Check for newer versions of installed skills and update them.

skilldb update                # Update everythingskilldb update software-skills  # Update one pack

skilldb remove

Uninstall skills from local cache.

skilldb remove software-skills/code-review    # Remove single skillskilldb remove software-skills                # Remove entire packskilldb 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 <id>

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

skilldb diff software-skills/code-reviewskilldb diff                  # Diff all installed

skilldb purge

Remove cached skills to free disk space.

skilldb purge --inactive      # Remove skills not in the active profileskilldb purge --all           # Remove ALL cached skills (including active)skilldb purge --slim          # Also drop slim summariesskilldb 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 <file.md>

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,perfskilldb push ./my-react-patterns.md --update           # update the skill with the same name/pack

Options: -p, --pack, -n, --name, -t, --title, -d, --description, --tags <comma,list>, -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 referencesskilldb export cursor         # .cursorrules blockskilldb export profile        # Shareable .skilldb-profile.jsonskilldb export inject <id>    # Print skill to stdout (for piping)

skilldb recommend

Scan your project and get personalized skill recommendations.

skilldb recommend             # Analyze project and suggestskilldb recommend --install   # Auto-install recommendations

SDK Usage

import { createClient } from 'skilldb';
const db = createClient(); // auto-loads key from env/config
// Search with slim previewsconst 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 filtersconst 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 (project-specific)
3. ~/.skilldbrc in home directory (user-wide)

Access tiers:

• No key — browse and search (metadata only).
• Pro or Studio key — full skill content (the actual markdown instructions).
• Studio key with write scope — private skills (skilldb push / my-skills, and the create/update MCP tools). Read-only keys are rejected with a write-scope error. Create a write-scoped key at skilldb.dev/account#api-keys.

Profiles

Built-in profiles map to curated skill sets:

Requirements

• Node.js >= 18

License

MIT