#npx skilldb: The npm Package Your Agent Didn't Know It Needed

Day 1 with the CLI. 2:14 PM. The cursor blinks in a fresh terminal.

I've been staring at browser tabs for months. Scrolling through the SkillDB marketplace, copying skill IDs, editing CLAUDE.md files by hand like some kind of digital scribe transcribing manuscripts. It worked. It always worked. But it felt like ordering food by walking into the kitchen and reading the recipe to the chef.

Today that changes. The skilldb npm package just dropped, and the workflow I've been waiting for is exactly four keystrokes away.

npx skilldb search "code review"

That's it. No browser. No API key. No curl commands with seventeen flags. Just a query and a table of results, right there in your terminal.

#The Five-Minute Setup

Here's what the full onboarding looks like now. I timed it.

Minute 1: Init your project.

npx skilldb init

The CLI sniffs your project directory. Got a CLAUDE.md? It knows you're running Claude Code. Got a .cursor/ folder? Cursor. codex.md? Codex CLI. It writes the integration snippet automatically, creates a .skilldb/ cache directory, and updates your .gitignore. You didn't have to tell it anything.

Minute 2: Browse the catalog.

npx skilldb list --category "Technology & Engineering"
npx skilldb search "debugging" npx skilldb info software-skills/code-review

Three commands. You now know what's available, what matches your use case, and exactly how many lines of expert methodology are packed into that code review skill (219, if you're curious).

Minute 3: Install a pack or grab individual skills.

npx skilldb add software-skills

Seventeen skills downloaded to .skilldb/skills/software-skills/.

Or grab a single skill without pulling the whole pack:

npx skilldb get software-skills/code-review

The get command downloads one skill file to your local cache. Perfect for keeping your agent lean. Code review, debugging, architecture, security audit, test generation, refactoring, DevOps, performance — the whole toolkit. Cached locally. Zero-latency reads for your agent. Run it again and it skips everything already cached, because idempotency isn't a feature, it's table stakes.

Minutes 4-5: Add more packs.

npx skilldb add autonomous-agent-skills

122 more skills. Task decomposition, self-correction, API integration, checkpoint strategy, browser verification — everything an autonomous agent needs to not crash and burn.

You now have 139 expert-level skills cached locally, ready for your agent to consume. Total time: under five minutes. Total configuration files edited by hand: zero.

#The TypeScript SDK

The CLI is the fast path. The SDK is the programmable path.

import { createClient } from 'skilldb';
const db = createClient(); const results = await db.search('code review'); console.log(results.skills.length); // 3
const skill = await db.get('software-skills/code-review.md'); console.log(skill.title);   // "Code Reviewer" console.log(skill.lines);   // 219

Three lines to search. Two lines to fetch. The client auto-loads your API key from the environment, from a project-level .skilldbrc, or from your home directory config. You don't configure it — it configures itself.

For CI/CD pipelines, set the SKILLDB_API_KEY environment variable. For local development, run skilldb login once and forget about it.

#What Changed Under the Hood

This release also opened up the API. Previously, every request to /api/v1/skills required a Bearer token. Now, metadata browsing — searching, listing, viewing skill info — works without authentication. Full skill content still requires a Pro or Enterprise key, but you can discover and evaluate skills without signing up for anything.

This matters because the first thing any developer does with a new tool is kick the tires. Nobody wants to create an account just to see if the product has what they need. Now they don't have to.

#The Local Cache: Why It Matters

When your agent runs skilldb add software-skills, the skills land in .skilldb/skills/software-skills/. Plain markdown files on disk. Your agent reads them with zero network latency, zero API calls, zero rate limit concerns.

The cache has a manifest (.skilldb/manifest.json) tracking what's installed and when. The whole thing is gitignored by default — your skills cache is local state, not committed code.

.skilldb/
  manifest.json   skills/     software-skills/       code-review.md       debugging.md       architecture.md       ...     autonomous-agent-skills/       task-decomposition.md       self-correction.md       ...

This is the pattern that makes agent-first tooling work. The agent doesn't fetch skills at runtime from an API. It reads them from disk, instantly, like loading a config file. The network call happened once, during setup. After that, it's all local.

#The Numbers

Metric	Value
Package size	17.5 KB
Dependencies	2 (commander + picocolors)
Node requirement	>= 18
Skills available	4,500+
Packs available	290+
Categories	31
Auth required for browsing	No

17.5 KB. That's the entire CLI and SDK, packed and gzipped. Two dependencies. No bundled skill data — everything is fetched on demand from the API and cached locally. This is what happens when you refuse to ship a kitchen sink.

#Get Started

npx skilldb search "your problem here"

That's the whole pitch. One command. See what comes back. If it's useful, run skilldb add for a full pack or skilldb get for a single skill and let your agent eat. If it's not, you spent four seconds finding out.

The package is live on npm: npmjs.com/package/skilldb. The docs are at skilldb.dev/docs. The full CLI reference, TypeScript SDK, and auth guide are all there.

Stop copy-pasting curl commands. Let your terminal do the work: npx skilldb init and give your agent the skills it deserves. Browse the full catalog at skilldb.dev/skills.