API Reference

Build integrations with Skillsmith using our TypeScript API. Access skill search, installation, and management programmatically.

Installation

npm install @skillsmith/core

Quick Start

import { SkillRegistry, SkillInstaller } from '@skillsmith/core';

// Initialize the registry
const registry = new SkillRegistry();

// Search for skills
const results = await registry.search({
  query: 'testing',
  trustTier: 'verified',
  limit: 10
});

// Install a skill
const installer = new SkillInstaller();
await installer.install('community/jest-helper');

SkillRegistry

The main interface for discovering and querying skills.

Constructor

const registry = new SkillRegistry(options?: RegistryOptions);

RegistryOptions

search()

Search for skills matching the given criteria.

async search(options: SearchOptions): Promise<SearchResult[]>

SearchOptions

Example

const results = await registry.search({
  query: 'git',
  trustTier: 'verified',
  category: 'devops',
  minScore: 80,
  limit: 5
});

for (const skill of results) {
  console.log(`${skill.id}: ${skill.name}`);
}

getSkill()

Get detailed information about a specific skill.

async getSkill(id: string): Promise<Skill | null>

Example

const skill = await registry.getSkill('community/jest-helper');

if (skill) {
  console.log(skill.name);
  console.log(skill.description);
  console.log(skill.trustTier);
  console.log(skill.qualityScore);
}

compare()

Compare multiple skills side-by-side.

async compare(ids: string[]): Promise<ComparisonResult>

Example

const comparison = await registry.compare([
  'community/jest-helper',
  'community/vitest-helper'
]);

console.log(comparison.skills);
console.log(comparison.differences);
console.log(comparison.recommendation);

SkillInstaller

Handle skill installation and removal.

Constructor

const installer = new SkillInstaller(options?: InstallerOptions);

InstallerOptions

install()

Install a skill to the local environment.

async install(id: string, options?: InstallOptions): Promise<InstallResult>

InstallOptions

Example

const result = await installer.install('community/jest-helper', {
  path: '~/.claude/skills',
  force: true
});

if (result.success) {
  console.log(`Installed to ${result.installPath}`);
} else {
  console.error(result.error);
}

uninstall()

Remove an installed skill.

async uninstall(id: string): Promise<UninstallResult>

list()

List all installed skills.

async list(): Promise<InstalledSkill[]>

Enterprise Tools

The following tools are available on the Enterprise tier via the MCP server. They are currently in preview — availability pending production migration (tracked in SMI-4135). Backing tables are restored in staging (SMI-4123).

webhook_configure

Configure HMAC-SHA256 signed webhooks for skill events (install, uninstall, update, audit). Enables integration with external systems such as SIEM, incident response, or internal notification pipelines.

async webhookConfigure(options: WebhookConfigureOptions): Promise<WebhookEndpoint>

WebhookConfigureOptions

Requires the Enterprise tier. Availability is gated on the production migration tracked in SMI-4135; calls will return a feature-unavailable response until then.

api_key_manage

Manage API keys for programmatic access — list, create, rotate, and revoke keys scoped to your workspace.

async apiKeyManage(options: ApiKeyManageOptions): Promise<ApiKeyResult>

ApiKeyManageOptions

Requires the Enterprise tier. Availability is gated on the production migration tracked in SMI-4135; calls will return a feature-unavailable response until then.

Types

Skill

interface Skill {
  id: string;              // "author/name" format
  name: string;            // Display name
  description: string;     // Full description
  author: string;          // Author identifier
  version: string;         // Semantic version
  trustTier: TrustTier;    // Trust level
  qualityScore: number;    // 0-100 score
  category: Category;      // Primary category
  tags: string[];          // Searchable tags
  dependencies: string[];  // Required dependencies
  createdAt: Date;         // Creation timestamp
  updatedAt: Date;         // Last update timestamp
}

TrustTier

type TrustTier = 'official' | 'verified' | 'community' | 'unverified';

Category

type Category =
  | 'development'
  | 'testing'
  | 'devops'
  | 'documentation'
  | 'security'
  | 'productivity'
  | 'data'
  | 'ai'
  | 'other';

SearchResult

interface SearchResult {
  skill: Skill;
  score: number;        // Relevance score
  highlights: string[]; // Matching text highlights
}

Error Handling

import { SkillsmithError, NotFoundError, ValidationError } from '@skillsmith/core';

try {
  await registry.getSkill('invalid/skill');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Skill not found');
  } else if (error instanceof ValidationError) {
    console.log('Invalid skill ID format');
  } else {
    throw error;
  }
}

Error Types

Rate Limiting

API requests are rate-limited based on your plan: