@skill-hub/sdk

TypeScript SDK for the SkillHub API. Discover, evaluate, and install AI agent skills across Codex, Claude Code, Gemini CLI, OpenCode, and OpenClaw.

Installation

npm install @skill-hub/sdk
# or
yarn add @skill-hub/sdk
# or
pnpm add @skill-hub/sdk

Quick Start

import { createClient } from '@skill-hub/sdk';

const client = createClient();

// Search for skills
const skills = await client.search('pdf processing');
console.log(skills);

// Get skill details
const detail = await client.getSkill('pdf-processor', { includeContent: true });
console.log(detail.skill.name, detail.evaluation?.summary);

// Inspect the install decision without downloading content
const preflight = await client.getInstallPreflight('pdf-processor');
console.log(preflight.security.decision);

API Reference

Creating a Client

import { createClient } from '@skill-hub/sdk';

// Basic usage
const client = createClient();

// With options
const client = createClient({
  baseUrl: 'https://www.skillhub.club/api/v1', // Custom API URL
  token: 'sk_...', // Authentication token
  timeout: 30000, // Request timeout in ms
  headers: {}, // Custom headers
});

Search Skills

// Simple search
const results = await client.search('code review');

// With options
const results = await client.search('code review', {
  limit: 10,
  method: 'hybrid', // 'embedding' | 'fulltext' | 'hybrid'
  category: 'Development',
  min_score: 70,
  mmr: true, // Enable diversity
  mmr_lambda: 0.7,
});

// Full response with metadata
const response = await client.searchWithMeta({
  query: 'code review',
  limit: 10,
});
console.log(response.meta.search_latency_ms);

Distribution Registries

RedSkill is modeled as a content distribution registry, not an AgentId:

const matches = await client.searchRegistry('redskill', {
  q: 'presentation',
  limit: 10,
  page: 1,
});

const resolved = await client.resolveRegistrySkill(
  'redskill',
  'bigw-skill-2',
);

// Authenticated preview; this does not install files.
const preview = await client.importRegistrySkill({
  provider: 'redskill',
  identifier_or_url: resolved.distribution.identifier,
  mode: 'fork',
  confirm: false,
});

// Confirm only after presenting the preview to the user.
const imported = await client.importRegistrySkill({
  provider: 'redskill',
  identifier_or_url: resolved.distribution.identifier,
  mode: 'fork',
  confirm: true,
  expected_sha256: preview.distribution?.sha256,
});

Confirmed imports are still subject to SkillHub normalization, artifact verification, and the standard install security gate.

Browse Catalog

// Get catalog with filters
const { skills, pagination } = await client.getCatalog({
  category: 'Development',
  sort: 'composite', // 'score' | 'stars' | 'recent' | 'composite'
  limit: 20,
  offset: 0,
});

// Shortcuts
const popular = await client.getPopular(10);
const recent = await client.getRecent(10);
const categories = await client.getCategories();

Skill Details

// Get by slug or ID
const detail = await client.getSkill('pdf-processor');

// Include full SKILL.md content
const detail = await client.getSkill('pdf-processor', {
  includeContent: true,
});

// Access evaluation
console.log(detail.evaluation?.pros);
console.log(detail.evaluation?.cons);
console.log(detail.token_stats.total_tokens);

Installation

const preflight = await client.getInstallPreflight('pdf-processor');

// Legacy S0 reviews require an explicit acknowledgement. Pending and blocked
// decisions cannot be overridden.
const install = await client.getInstallInfo('pdf-processor', ['claude'], {
  acknowledgeRisk: preflight.security.decision === 'caution',
});
console.log(install.install.files);

User API (Authenticated)

const client = createClient({ token: 'sk_...' });

// Get current user
const user = await client.getCurrentUser();

// Favorites
const favorites = await client.getFavorites();
await client.addFavorite('skill-id');
await client.removeFavorite('skill-id');

Types

All types are exported and can be imported separately:

import type {
  Skill,
  SkillDetail,
  SkillEvaluation,
  SearchResult,
  SearchResponse,
  CatalogResponse,
  InstallInfo,
  Category,
  AgentId,
  User,
} from '@skill-hub/sdk';

// Or import just types
import type { Skill } from '@skill-hub/sdk/types';

Supported Agents

import { SUPPORTED_AGENTS } from '@skill-hub/sdk';

// Available agents: claude, codex, gemini, opencode
console.log(SUPPORTED_AGENTS.claude.installPath); // ~/.claude/skills/

Error Handling

import { SkillHubError } from '@skill-hub/sdk';

try {
  const skill = await client.getSkill('non-existent');
} catch (error) {
  if (error instanceof SkillHubError) {
    console.log(error.status);  // 404
    console.log(error.code);    // 'NOT_FOUND'
    console.log(error.message); // 'Skill not found'
  }
}

Advanced Usage

Request Cancellation

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const skills = await client.search('test', {
    signal: controller.signal,
  });
} catch (error) {
  if (error instanceof SkillHubError && error.code === 'TIMEOUT') {
    console.log('Request was cancelled');
  }
}

Custom Fetch

import { createClient } from '@skill-hub/sdk';

// Use custom fetch (e.g., for testing)
const client = createClient({
  fetch: myCustomFetch,
});

License

MIT