{
  "markdown": "<!-- mcp-name: io.github.devchad-cmd/skilldb -->\n\n# skilldb\n\nCLI, TypeScript SDK, and **MCP Server** for [SkillDB](https://skilldb.dev) — discover, install, and manage AI agent skills.\n\n5,900+ expert skills across 429 packs for Claude Code, Cursor, Windsurf, VS Code, and any MCP-compatible AI tool.\n\n[![Add SkillDB to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=skilldb&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyItcCIsInNraWxsZGIiLCJza2lsbGRiLW1jcCJdfQ==)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_SkillDB-0098FF?logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22skilldb%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-p%22%2C%22skilldb%22%2C%22skilldb-mcp%22%5D%7D)\n[![npm](https://img.shields.io/npm/v/skilldb?logo=npm&label=skilldb)](https://www.npmjs.com/package/skilldb)\n\n> **Open source for transparency.** This is the full source for the [`skilldb`](https://www.npmjs.com/package/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](https://docs.npmjs.com/trusted-publishers) (OIDC, with provenance), so the published artifact is verifiably built from this repo. Audit away, and PRs welcome. MIT licensed.\n\n## MCP Server\n\nConnect SkillDB directly to your AI coding tool via the Model Context Protocol:\n\n```bash\n# Step 1 (optional): install globally. You can also skip this — the npx form below works without it.\nnpm install -g skilldb\n\n# Step 2: Get your free API key at https://skilldb.dev/api-access\n\n# Step 3: Add to Claude Code (with API key for full content)\nclaude mcp add skilldb -- npx -p skilldb skilldb-mcp --api-key sk_live_YOUR_KEY\n```\n\n> **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`).\n\n> **⚠️ Without an API key**, you can search and browse skills (metadata only).\n> **With a free API key**, you get full skill content — the actual markdown instructions your agent uses.\n> Get your key in 30 seconds at [skilldb.dev/api-access](https://skilldb.dev/api-access).\n\n**Cursor** — add to `.cursor/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"skilldb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-p\", \"skilldb\", \"skilldb-mcp\"]\n    }\n  }\n}\n```\n\n**Windsurf** — add to `mcp_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"skilldb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-p\", \"skilldb\", \"skilldb-mcp\", \"--api-key\", \"sk_live_xxx\"]\n    }\n  }\n}\n```\n\n**VS Code** — one-liner:\n```bash\ncode --add-mcp '{\"name\":\"skilldb\",\"command\":\"npx\",\"args\":[\"-p\",\"skilldb\",\"skilldb-mcp\"]}'\n```\nOr add the same server block to `.vscode/mcp.json` (workspace) / user `mcp.json` under `\"servers\"`.\n\nOnce connected, your AI assistant can search and load skills natively. Just ask:\n- *\"Search SkillDB for React performance patterns\"*\n- *\"Load the code review skill\"*\n- *\"What skills should I use for this project?\"*\n- *\"Save this as a private skill\"* (Studio plan — see below)\n\n**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).\n\n## Quick Start (CLI)\n\n```bash\n# Search for skills (with inline preview)\nnpx skilldb search \"code review\"\n\n# Install a skill pack\nnpx skilldb add software-skills\n\n# Activate a smart profile (only loads what you need)\nnpx skilldb use frontend\n\n# Or auto-detect from your project\nnpx skilldb use auto\n```\n\n## Install\n\n```bash\nnpm install -g skilldb\n```\n\nOr use `npx skilldb` without installing.\n\n## The Memory Problem (And How We Solve It)\n\nLoading 500 skills into your agent's context is worse than loading the right 5. SkillDB uses a **3-layer architecture** to manage this:\n\n```\n.skilldb/\n├── skills/          ← Full cache (everything downloaded)\n├── active/          ← Active profile (what your agent sees — 5-15 focused skills)\n├── slim/            ← Compressed cheat sheets (10x smaller)\n├── config.json      ← Profile + budget settings\n└── manifest.json    ← What's installed\n```\n\nYour CLAUDE.md or .cursorrules points at `.skilldb/active/`, not the full cache. The agent gets focused, relevant skills — not noise.\n\n## CLI Commands\n\n### Core\n\n#### `skilldb init`\n\nDetect your IDE (Claude Code, Cursor, Codex CLI, OpenClaw), create `.skilldb/`, and add integration config.\n\n```bash\nskilldb init\n```\n\n#### `skilldb search <query>`\n\nSearch skills by keyword. Shows inline slim preview so you know what you're getting before downloading.\n\n```bash\nskilldb search \"debugging\"\nskilldb search \"api design\" --category \"Technology & Engineering\"\nskilldb search \"testing\" --limit 10\n```\n\n#### `skilldb add <pack>`\n\nDownload a skill pack to local cache. Idempotent — skips already-cached skills.\n\n```bash\nskilldb add software-skills\nskilldb add autonomous-agent-skills\nskilldb add vibe-coding-security-skills\n```\n\n#### `skilldb get <id>`\n\nDownload a single skill.\n\n```bash\nskilldb get software-skills/code-review\n```\n\n#### `skilldb info <id>`\n\nShow metadata, slim summary, and full preview for a skill.\n\n```bash\nskilldb info software-skills/code-review\n```\n\n#### `skilldb list`\n\nList available categories, packs, and skills.\n\n```bash\nskilldb list\nskilldb list --category \"Autonomous Agents\"\nskilldb list --pack software-skills\n```\n\n#### `skilldb login`\n\nPrompts for your API key and saves it to `~/.skilldbrc` (user-wide) so every project picks it up via the resolution chain in [Authentication](#authentication). The recommended alternative to setting `SKILLDB_API_KEY` by hand.\n\n```bash\nskilldb login\n```\n\n### Smart Loading\n\n#### `skilldb use <profile>`\n\nActivate a focused profile — only loads relevant skills into `.skilldb/active/`.\n\n```bash\nskilldb use frontend          # React, testing, web-polish, accessibility\nskilldb use backend           # API design, databases, security, performance\nskilldb use devops            # Kubernetes, Docker, CI/CD, monitoring\nskilldb use security          # Trust audit, input validation, credentials\nskilldb use data              # SQL, pipelines, analytics, visualization\nskilldb use fullstack         # Frontend + backend combined\nskilldb use mobile            # Mobile / React Native / app development\nskilldb use ai-agent          # Autonomous agent meta-skills\nskilldb use auto              # Auto-detect from your project files\nskilldb use --list            # Show available profiles\nskilldb use --current         # Show active profile\nskilldb use none              # Deactivate (clear active/)\n```\n\n`auto` mode scans your `package.json`, file extensions, and imports to recommend the right profile.\n\n#### `skilldb budget`\n\nSet a maximum context budget so your agent doesn't get overloaded.\n\n```bash\nskilldb budget                # Show current usage\nskilldb budget set 5000       # Max 5,000 lines\nskilldb budget set 50k        # Max 50,000 tokens\nskilldb budget optimize       # Re-rank and trim active skills to fit\n```\n\n#### `skilldb slim`\n\nGenerate compressed cheat-sheet versions of skills (~30 lines instead of 300).\n\n```bash\nskilldb slim                  # Slim all active skills\nskilldb slim software-skills  # Slim a specific pack\nskilldb slim --ratio 0.3      # Keep 30% of content\n```\n\n### Management\n\n#### `skilldb update`\n\nCheck for newer versions of installed skills and update them.\n\n```bash\nskilldb update                # Update everything\nskilldb update software-skills  # Update one pack\n```\n\n#### `skilldb remove`\n\nUninstall skills from local cache.\n\n```bash\nskilldb remove software-skills/code-review    # Remove single skill\nskilldb remove software-skills                # Remove entire pack\nskilldb remove --unused                       # Remove skills not in active profile\n```\n\n#### `skilldb doctor`\n\nHealth check and audit of your skill setup.\n\n```bash\nskilldb doctor\n```\n\nShows: outdated skills, unused skills, missing dependencies, budget status, coverage gaps.\n\n#### `skilldb stats`\n\nLocal statistics dashboard.\n\n```bash\nskilldb stats\n```\n\nShows: installed count, total lines, tokens, active profile, categories covered.\n\n#### `skilldb diff <id>`\n\nCompare your local (possibly customized) version with the latest remote.\n\n```bash\nskilldb diff software-skills/code-review\nskilldb diff                  # Diff all installed\n```\n\n#### `skilldb purge`\n\nRemove cached skills to free disk space.\n\n```bash\nskilldb purge --inactive      # Remove skills not in the active profile\nskilldb purge --all           # Remove ALL cached skills (including active)\nskilldb purge --slim          # Also drop slim summaries\nskilldb purge --dry-run       # Preview what would be removed, delete nothing\n```\n\n### Private Skills (Studio)\n\nCreate 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](https://skilldb.dev/account#api-keys).\n\n#### `skilldb push <file.md>`\n\nCreate (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.\n\n```bash\nskilldb push ./my-react-patterns.md                    # create (pack defaults to \"personal\")\nskilldb push ./my-react-patterns.md -p team --tags react,perf\nskilldb push ./my-react-patterns.md --update           # update the skill with the same name/pack\n```\n\nOptions: `-p, --pack`, `-n, --name`, `-t, --title`, `-d, --description`, `--tags <comma,list>`, `-u, --update`.\n\n#### `skilldb my-skills`\n\nList your private skills (ones you own plus skills shared with you).\n\n```bash\nskilldb my-skills\n```\n\nYou can also do all of this from your agent via the MCP tools `skilldb_create_skill` / `skilldb_update_skill` / `skilldb_my_skills`.\n\n### Sharing & Export\n\n#### `skilldb export`\n\nExport your setup for sharing or IDE integration.\n\n```bash\nskilldb export claude         # CLAUDE.md snippet with skill references\nskilldb export cursor         # .cursorrules block\nskilldb export profile        # Shareable .skilldb-profile.json\nskilldb export inject <id>    # Print skill to stdout (for piping)\n```\n\n#### `skilldb recommend`\n\nScan your project and get personalized skill recommendations.\n\n```bash\nskilldb recommend             # Analyze project and suggest\nskilldb recommend --install   # Auto-install recommendations\n```\n\n## SDK Usage\n\n```typescript\nimport { createClient } from 'skilldb';\n\nconst db = createClient(); // auto-loads key from env/config\n\n// Search with slim previews\nconst results = await db.search('code review');\nfor (const skill of results.skills) {\n  console.log(skill.title);\n  console.log(skill.slim); // Quick summary\n}\n\n// Get full skill content\nconst skill = await db.get('software-skills/code-review.md');\nconsole.log(skill.content);\n\n// List with filters\nconst listing = await db.list({ category: 'Autonomous Agents', limit: 10 });\n```\n\n## Authentication\n\nThe SDK and CLI resolve your API key in order:\n\n1. `SKILLDB_API_KEY` environment variable (CI-friendly)\n2. `.skilldbrc` in project root (project-specific)\n3. `~/.skilldbrc` in home directory (user-wide)\n\nAccess tiers:\n\n- **No key** — browse and search (metadata only).\n- **Pro or Studio key** — full skill content (the actual markdown instructions).\n- **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](https://skilldb.dev/account#api-keys).\n\n## Profiles\n\nBuilt-in profiles map to curated skill sets:\n\n| Profile | Skills loaded | Best for |\n|---------|--------------|----------|\n| `frontend` | react-patterns, web-polish, testing, accessibility | React/Vue/Angular apps |\n| `backend` | api-design, databases, security, performance | Node/Python/Go services |\n| `devops` | kubernetes, docker, ci-cd, monitoring, cloud | Infrastructure & deployment |\n| `security` | trust-audit, input-validation, credentials, hardening | Security review & hardening |\n| `data` | sql, pipelines, analytics, visualization | Data engineering & analysis |\n| `fullstack` | frontend + backend combined | Full-stack applications |\n| `mobile` | mobile patterns, app architecture, UI | Mobile / React Native apps |\n| `ai-agent` | autonomous-agent-skills, task-decomposition, planning | Building AI agents |\n| `auto` | Detected from project | Any project |\n\n## Requirements\n\n- Node.js >= 18\n\n## License\n\nMIT\n",
  "bytes": 12786,
  "sha": "41bfcc40221e3f272c3c3ebb1625df10ac574416acefefad324a9d215fb0718d",
  "repo_slug": "devchad-cmd/skilldb-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_devchad_cmd_skilldb_602e4dee/readme"
}