skilldb 0.2.0 → 0.3.0

package/README.md

@@ -1,280 +1,280 @@
-# skilldb
-
-CLI and TypeScript SDK for [SkillDB](https://skilldb.dev) — discover, install, and manage AI agent skills from the terminal.
-
-5,000+ expert skills for Claude Code, Cursor, OpenClaw, and Codex. Search, install, and activate exactly what your agent needs.
-
-## Quick Start
-
-```bash
-# 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
-
-```bash
-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.
-
-```bash
-skilldb init
-```
-
-#### `skilldb search <query>`
-
-Search skills by keyword. Shows inline slim preview so you know what you're getting before downloading.
-
-```bash
-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.
-
-```bash
-skilldb add software-skills
-skilldb add autonomous-agent-skills
-skilldb add vibe-coding-security-skills
-```
-
-#### `skilldb get <id>`
-
-Download a single skill.
-
-```bash
-skilldb get software-skills/code-review
-```
-
-#### `skilldb info <id>`
-
-Show metadata, slim summary, and full preview for a skill.
-
-```bash
-skilldb info software-skills/code-review
-```
-
-#### `skilldb list`
-
-List available categories, packs, and skills.
-
-```bash
-skilldb list
-skilldb list --category "Autonomous Agents"
-skilldb list --pack software-skills
-```
-
-#### `skilldb login`
-
-Save your API key for authenticated access.
-
-```bash
-skilldb login
-```
-
-### Smart Loading
-
-#### `skilldb use <profile>`
-
-Activate a focused profile — only loads relevant skills into `.skilldb/active/`.
-
-```bash
-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 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.
-
-```bash
-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).
-
-```bash
-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.
-
-```bash
-skilldb update                # Update everything
-skilldb update software-skills  # Update one pack
-```
-
-#### `skilldb remove`
-
-Uninstall skills from local cache.
-
-```bash
-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.
-
-```bash
-skilldb doctor
-```
-
-Shows: outdated skills, unused skills, missing dependencies, budget status, coverage gaps.
-
-#### `skilldb stats`
-
-Local statistics dashboard.
-
-```bash
-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.
-
-```bash
-skilldb diff software-skills/code-review
-skilldb diff                  # Diff all installed
-```
-
-### Sharing & Export
-
-#### `skilldb export`
-
-Export your setup for sharing or IDE integration.
-
-```bash
-skilldb export claude         # CLAUDE.md snippet with skill references
-skilldb export cursor         # .cursorrules block
-skilldb export profile        # Shareable .skilldb-profile.json
-skilldb export inject <id>    # Print skill to stdout (for piping)
-```
-
-#### `skilldb recommend`
-
-Scan your project and get personalized skill recommendations.
-
-```bash
-skilldb recommend             # Analyze project and suggest
-skilldb recommend --install   # Auto-install recommendations
-```
-
-## SDK Usage
-
-```typescript
-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
-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 (project-specific)
-3. `~/.skilldbrc` in home directory (user-wide)
-
-Browsing and searching works without authentication. Full skill content requires a Pro or Studio key.
-
-## Profiles
-
-Built-in profiles map to curated skill sets:
-
-| Profile | Skills loaded | Best for |
-|---------|--------------|----------|
-| `frontend` | react-patterns, web-polish, testing, accessibility | React/Vue/Angular apps |
-| `backend` | api-design, databases, security, performance | Node/Python/Go services |
-| `devops` | kubernetes, docker, ci-cd, monitoring, cloud | Infrastructure & deployment |
-| `security` | trust-audit, input-validation, credentials, hardening | Security review & hardening |
-| `data` | sql, pipelines, analytics, visualization | Data engineering & analysis |
-| `fullstack` | frontend + backend combined | Full-stack applications |
-| `ai-agent` | autonomous-agent-skills, task-decomposition, planning | Building AI agents |
-| `auto` | Detected from project | Any project |
-
-## Requirements
-
-- Node.js >= 18
-
-## License
-
-MIT
+# skilldb
+
+CLI and TypeScript SDK for [SkillDB](https://skilldb.dev) — discover, install, and manage AI agent skills from the terminal.
+
+5,000+ expert skills for Claude Code, Cursor, OpenClaw, and Codex. Search, install, and activate exactly what your agent needs.
+
+## Quick Start
+
+```bash
+# 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
+
+```bash
+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.
+
+```bash
+skilldb init
+```
+
+#### `skilldb search <query>`
+
+Search skills by keyword. Shows inline slim preview so you know what you're getting before downloading.
+
+```bash
+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.
+
+```bash
+skilldb add software-skills
+skilldb add autonomous-agent-skills
+skilldb add vibe-coding-security-skills
+```
+
+#### `skilldb get <id>`
+
+Download a single skill.
+
+```bash
+skilldb get software-skills/code-review
+```
+
+#### `skilldb info <id>`
+
+Show metadata, slim summary, and full preview for a skill.
+
+```bash
+skilldb info software-skills/code-review
+```
+
+#### `skilldb list`
+
+List available categories, packs, and skills.
+
+```bash
+skilldb list
+skilldb list --category "Autonomous Agents"
+skilldb list --pack software-skills
+```
+
+#### `skilldb login`
+
+Save your API key for authenticated access.
+
+```bash
+skilldb login
+```
+
+### Smart Loading
+
+#### `skilldb use <profile>`
+
+Activate a focused profile — only loads relevant skills into `.skilldb/active/`.
+
+```bash
+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 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.
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+skilldb update                # Update everything
+skilldb update software-skills  # Update one pack
+```
+
+#### `skilldb remove`
+
+Uninstall skills from local cache.
+
+```bash
+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.
+
+```bash
+skilldb doctor
+```
+
+Shows: outdated skills, unused skills, missing dependencies, budget status, coverage gaps.
+
+#### `skilldb stats`
+
+Local statistics dashboard.
+
+```bash
+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.
+
+```bash
+skilldb diff software-skills/code-review
+skilldb diff                  # Diff all installed
+```
+
+### Sharing & Export
+
+#### `skilldb export`
+
+Export your setup for sharing or IDE integration.
+
+```bash
+skilldb export claude         # CLAUDE.md snippet with skill references
+skilldb export cursor         # .cursorrules block
+skilldb export profile        # Shareable .skilldb-profile.json
+skilldb export inject <id>    # Print skill to stdout (for piping)
+```
+
+#### `skilldb recommend`
+
+Scan your project and get personalized skill recommendations.
+
+```bash
+skilldb recommend             # Analyze project and suggest
+skilldb recommend --install   # Auto-install recommendations
+```
+
+## SDK Usage
+
+```typescript
+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
+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 (project-specific)
+3. `~/.skilldbrc` in home directory (user-wide)
+
+Browsing and searching works without authentication. Full skill content requires a Pro or Studio key.
+
+## Profiles
+
+Built-in profiles map to curated skill sets:
+
+| Profile | Skills loaded | Best for |
+|---------|--------------|----------|
+| `frontend` | react-patterns, web-polish, testing, accessibility | React/Vue/Angular apps |
+| `backend` | api-design, databases, security, performance | Node/Python/Go services |
+| `devops` | kubernetes, docker, ci-cd, monitoring, cloud | Infrastructure & deployment |
+| `security` | trust-audit, input-validation, credentials, hardening | Security review & hardening |
+| `data` | sql, pipelines, analytics, visualization | Data engineering & analysis |
+| `fullstack` | frontend + backend combined | Full-stack applications |
+| `ai-agent` | autonomous-agent-skills, task-decomposition, planning | Building AI agents |
+| `auto` | Detected from project | Any project |
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/dist/cli.js

@@ -78,17 +78,19 @@ var SkillDBClient = class {
       search: query,
       category: options?.category ?? "",
       pack: options?.pack ?? "",
+      sort: options?.sort ?? "",
       limit: String(options?.limit ?? 20),
       offset: String(options?.offset ?? 0),
       include_content: options?.includeContent ? "true" : ""
     });
   }
-  /** List skills with optional filters. */
+  /** List skills with optional filters and sorting. */
   async list(options) {
     return this.request("/skills", {
       category: options?.category ?? "",
       pack: options?.pack ?? "",
       search: options?.search ?? "",
+      sort: options?.sort ?? "",
       limit: String(options?.limit ?? 50),
       offset: String(options?.offset ?? 0),
       include_content: options?.includeContent ? "true" : ""
@@ -102,6 +104,17 @@ var SkillDBClient = class {
     });
     return "skill" in res ? res.skill : res;
   }
+  /** Batch retrieve multiple skills by IDs (max 50). */
+  async batch(ids) {
+    return this.request("/skills", {
+      ids: ids.slice(0, 50).join(","),
+      include_content: "true"
+    });
+  }
+  /** Get search autocomplete suggestions. */
+  async suggest(query) {
+    return this.request("/skills/suggest", { q: query });
+  }
   /** Validate that the configured API key works. */
   async validate() {
     try {
@@ -1618,7 +1631,7 @@ ${pc17.green(`${upToDate} up to date`)}` + (changed > 0 ? pc17.yellow(`, ${chang
 
 // src/cli.ts
 var program = new Command();
-program.name("skilldb").description("SkillDB CLI \u2014 discover, install, and manage AI agent skills").version("0.1.5");
+program.name("skilldb").description("SkillDB CLI \u2014 discover, install, and manage AI agent skills").version("0.3.0");
 program.command("init").description("Initialize SkillDB in this project (detect IDE, create .skilldb/)").action(initCommand);
 program.command("login").description("Save your SkillDB API key").action(loginCommand);
 program.command("search <query...>").description("Search skills by keyword(s)").option("-c, --category <name>", "Filter by category").option("-l, --limit <n>", "Max results", "20").action((queryParts, options) => {