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[]>

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 = 'verified' | 'community' | 'experimental' | 'unknown';

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: