@skillsmith/core

@skillsmith/core

Core library for Skillsmith — database operations, search, caching, security, analytics, and multi-language codebase analysis for agent skill management.

Part of Skillsmith: a registry for sharing, scanning, and tracking agent skills across teams.

Contents

• What's New
• Installation
• Quick Start
• Features
• Exports

What's New in v0.14.0

• Fail-closed install gates (behaviour change): SkillInstallationService.install() now requires confirmed: true for any registry skill whose trust tier is not official, verified, curated, community or local, and refuses skipScan for those tiers (SKIP_SCAN_FORBIDDEN). Before, only experimental and unknown were gated, so an unverified, empty or unrecognised tier passed both checks. A missing or unrecognised tier is now scanned with the strictest options. Callers that never pass confirmed get CONFIRMATION_REQUIRED for these skills.
• New executable_frontmatter finding: the scanner flags any scanned file that opens with an executable ---js or ---javascript frontmatter block (critical, flag-only: it doesn't change riskScore). Current clients refuse to install a skill whose SKILL.md carries it, unless the scan is skipped (allowed only for reviewed tiers).
• RiskScoreBreakdown gains a required executableFrontmatter field. Code that builds a RiskScoreBreakdown by hand must add it.

See CHANGELOG.md for previous releases.

Installation

npm install @skillsmith/core

@huggingface/transformers is an optionalDependency — when it cannot be installed (no prebuilt ONNX binary, --no-optional flag, restricted hosts) @skillsmith/core falls back to mock embeddings per ADR-009. To force the mock fallback explicitly, set SKILLSMITH_USE_MOCK_EMBEDDINGS=true. The @skillsmith/mcp-server boot logs a structured stderr warning when the fallback is engaged (SMI-5009).

Quick Start

import {
  openDatabase,
  SkillRepository,
  SearchService,
  TieredCache,
} from '@skillsmith/core'

// Open database
const db = openDatabase('~/.skillsmith/skills.db')

// Create repository and search service
const skillRepo = new SkillRepository(db)
const cache = new TieredCache()
const searchService = new SearchService(skillRepo, cache)

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

Live API

As of v0.2.0, Skillsmith uses a live API at api.skillsmith.app to serve skills.

Configuration

# Use default API (recommended)
# No configuration needed

# Custom API URL
export SKILLSMITH_API_URL=https://your-api.example.com

# Offline mode (use local database)
export SKILLSMITH_OFFLINE_MODE=true

Telemetry

Skillsmith collects anonymous usage data to improve the product. To opt out:

export SKILLSMITH_TELEMETRY=false

See PRIVACY.md for details on what data is collected.

Features

Database Operations

SQLite-based storage with migrations and type-safe queries.

import { openDatabase, createDatabase, runMigrations } from '@skillsmith/core'

const db = openDatabase('./skills.db')
await runMigrations(db)

Repositories

• SkillRepository - CRUD operations for skills
• CacheRepository - Persistent cache storage
• IndexerRepository - Batch indexing operations
• SkillDependencyRepository - Skill dependency graph queries

import { SkillRepository } from '@skillsmith/core'

const repo = new SkillRepository(db)
const skill = await repo.findById('author/skill-name')
const skills = await repo.search({ query: 'testing', limit: 10 })

Search Services

Hybrid search combining full-text and semantic search.

import { HybridSearch, SearchService } from '@skillsmith/core'

const search = new HybridSearch(db)
const results = await search.search({
  query: 'git commit helper',
  filters: { trustTier: 'verified' },
})

Caching

Multi-tier caching with L1 (memory) and L2 (SQLite) layers.

import { TieredCache, L1Cache, L2Cache } from '@skillsmith/core'

const cache = new TieredCache({
  l1: new L1Cache({ maxSize: 1000, ttlMs: 60000 }),
  l2: new L2Cache(db),
})

await cache.set('key', { data: 'value' })
const cached = await cache.get('key')

Security

Rate limiting, path validation, security scanning, and audit logging.

import {
  RateLimiter,
  SecurityScanner,
  AuditLogger,
  validateDbPath,
} from '@skillsmith/core'

// Rate limiting
const limiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 })
const allowed = await limiter.checkLimit('user-123')

// Path validation (prevent traversal attacks)
const result = validateDbPath('/path/to/db.sqlite')
if (!result.valid) throw new Error(result.error)

// Security scanning
const scanner = new SecurityScanner()
const report = await scanner.scan(skillContent)

// Audit logging
const logger = new AuditLogger(db)
await logger.log({
  eventType: 'skill.install',
  actor: { type: 'user', id: 'user-123' },
  resource: { type: 'skill', id: 'author/skill' },
})

Indexing

Index skills from GitHub repositories.

import { GitHubIndexer, SkillParser } from '@skillsmith/core'

const indexer = new GitHubIndexer({
  token: process.env.GITHUB_TOKEN,
})

const result = await indexer.indexRepository('owner/repo')

Quality Scoring

Score skills based on documentation, security, and community signals.

import { QualityScorer, quickScore } from '@skillsmith/core'

const scorer = new QualityScorer()
const score = await scorer.score(skill)
// { overall: 85, breakdown: { documentation: 90, security: 80, ... } }

// Quick scoring without full analysis
const quick = quickScore(skillMetadata)

Dependency Intelligence

Infer and manage skill dependencies from SKILL.md content.

import {
  extractMcpReferences,
  mergeDependencies,
  SkillDependencyRepository,
} from '@skillsmith/core'

// Extract MCP server references from SKILL.md content
const refs = extractMcpReferences(skillMdContent)
// [{ server: 'github', tool: 'create_issue', confidence: 0.9 }, ...]

// Merge declared frontmatter deps with inferred MCP refs
const merged = mergeDependencies(declaredDeps, refs)
// [{ depType: 'mcp_server', target: 'github', source: 'inferred_static', confidence: 0.9 }]

// Persist to database
const depRepo = new SkillDependencyRepository(db)
await depRepo.upsert('author/skill', merged)

// Query dependency graph
const deps = depRepo.findBySkillId('author/skill')

Analytics

Track skill usage and generate insights.

import { UsageTracker, UsageAnalyticsService } from '@skillsmith/core'

const tracker = new UsageTracker(db)
await tracker.trackUsage({
  skillId: 'author/skill',
  eventType: 'install',
})

const analytics = new UsageAnalyticsService(db)
const summary = await analytics.getSummary({ days: 30 })

Telemetry

OpenTelemetry-based tracing and metrics.

import {
  initializeTelemetry,
  getTracer,
  getMetrics,
  traced,
} from '@skillsmith/core'

await initializeTelemetry({ serviceName: 'skillsmith' })

// Manual tracing
const tracer = getTracer()
const span = tracer.startSpan('operation')
// ... do work
span.end()

// Decorator-based tracing
class MyService {
  @traced('search')
  async search(query: string) {
    // automatically traced
  }
}

Multi-Language Codebase Analysis (v2.0.0)

Analyze codebases in TypeScript, JavaScript, Python, Go, Rust, and Java.

import { CodebaseAnalyzer } from '@skillsmith/core'

const analyzer = new CodebaseAnalyzer()
const context = await analyzer.analyze('/path/to/project')

// Languages detected
console.log(context.metadata.languages)
// ['typescript', 'python', 'go']

// Files by language
console.log(context.stats.filesByLanguage)
// { typescript: 45, python: 23, go: 12 }

// Detected frameworks across all languages
console.log(context.frameworks)
// [{ name: 'React', confidence: 0.95 }, { name: 'Django', confidence: 0.9 }]

analyzer.dispose()

Language Router

Route files to appropriate language adapters:

import {
  LanguageRouter,
  TypeScriptAdapter,
  PythonAdapter,
  GoAdapter,
  RustAdapter,
  JavaAdapter,
} from '@skillsmith/core'

const router = new LanguageRouter()
router.registerAdapter(new TypeScriptAdapter())
router.registerAdapter(new PythonAdapter())
router.registerAdapter(new GoAdapter())
router.registerAdapter(new RustAdapter())
router.registerAdapter(new JavaAdapter())

// Check if file is supported
router.canHandle('main.py') // true
router.getLanguage('main.go') // 'go'

// Parse a file
const result = router.parseFile(content, 'main.py')
console.log(result.imports, result.exports, result.functions)

router.dispose()

Parse Caching

Cache parse results for improved performance:

import { ParseCache } from '@skillsmith/core'

const cache = new ParseCache({ maxMemoryMB: 100 })

// Check cache before parsing
const cached = cache.get('src/main.ts', content)
if (cached) {
  return cached
}

// Parse and cache
const result = adapter.parseFile(content, 'src/main.ts')
cache.set('src/main.ts', content, result)

// View cache statistics
console.log(cache.getStats())
// { size: 1048576, entries: 50, maxSize: 104857600, hitRate: 0.85 }

Incremental Parsing

Efficiently parse changes:

import { IncrementalParser, TypeScriptAdapter } from '@skillsmith/core'

const parser = new IncrementalParser({ maxTrees: 50 })
const adapter = new TypeScriptAdapter()

// First parse (full)
const result1 = parser.parse('src/main.ts', content1, adapter)
console.log(result1.wasIncremental) // false

// Second parse with small change (incremental, <100ms)
const result2 = parser.parse('src/main.ts', content2, adapter)
console.log(result2.wasIncremental) // true

parser.dispose()

Parallel Parsing

Parse large codebases in parallel:

import { ParserWorkerPool } from '@skillsmith/core'

const pool = new ParserWorkerPool({ poolSize: 4 })

const tasks = files.map(f => ({
  filePath: f.path,
  content: f.content,
  language: 'typescript'
}))

const results = await pool.parseFiles(tasks)
console.log(`Parsed ${results.length} files`)

pool.dispose()

Dependency Parsers

Parse language-specific dependency files:

import {
  parseGoMod,
  parseCargoToml,
  parsePomXml,
  parseBuildGradle,
} from '@skillsmith/core'

// Go dependencies
const goMod = parseGoMod(goModContent)
console.log(goMod.module)  // "github.com/user/project"
console.log(goMod.require) // [{ path: "...", version: "..." }]

// Rust dependencies
const cargo = parseCargoToml(cargoTomlContent)
// [{ name: "serde", version: "1.0", isDev: false }]

// Java Maven dependencies
const maven = parsePomXml(pomXmlContent)
// [{ name: "org.springframework:spring-core", version: "5.3.0", isDev: false }]

// Java Gradle dependencies
const gradle = parseBuildGradle(buildGradleContent)
// [{ name: "org.springframework:spring-core", version: "5.3.0", isDev: false }]

Supported Languages & Frameworks

Language	Extensions	Frameworks Detected
TypeScript/JS	.ts, .tsx, .js, .jsx, .mjs, .cjs	React, Vue, Angular, Next.js, Express, Nest.js, Jest, Vitest
Python	.py, .pyi, .pyw	Django, FastAPI, Flask, pytest, pandas, numpy
Go	.go	Gin, Echo, Fiber, GORM, Cobra, gRPC, testify
Rust	.rs	Actix, Rocket, Axum, Tokio, Serde, Diesel, SQLx
Java	.java	Spring Boot, Quarkus, Micronaut, JUnit, Hibernate, Lombok

Performance

Metric	Target
10k file analysis	<5 seconds
Incremental parse	<100ms
Cache hit rate	>80%
Memory efficiency	LRU eviction

Exports

The package provides multiple entry points:

// Main exports
import { SkillRepository, SearchService } from '@skillsmith/core'

// Error handling
import { SkillsmithError, ValidationError } from '@skillsmith/core/errors'

// Embeddings (lazy-loaded to avoid startup overhead)
import { EmbeddingService } from '@skillsmith/core/embeddings'

// Analysis module (v2.0.0)
import {
  CodebaseAnalyzer,
  LanguageRouter,
  ParseCache,
  TreeCache,
  IncrementalParser,
  ParserWorkerPool,
  MemoryMonitor,
  // Adapters
  TypeScriptAdapter,
  PythonAdapter,
  GoAdapter,
  RustAdapter,
  JavaAdapter,
  // Dependency parsers
  parseGoMod,
  parseCargoToml,
  parsePomXml,
  parseBuildGradle,
  // Types
  type SupportedLanguage,
  type ParseResult,
  type ImportInfo,
  type ExportInfo,
  type FunctionInfo,
  type CodebaseContext,
} from '@skillsmith/core'

// Dependency intelligence (v0.4.16)
import {
  extractMcpReferences,
  mergeDependencies,
  SkillDependencyRepository,
  // Types
  type DependencyDeclaration,
  type SkillDependencyRow,
  type DepType,
  type DepSource,
  type McpReference,
  type McpExtractionResult,
  type MergedDependency,
} from '@skillsmith/core'

Billing module — relocated in 0.7.0 (BREAKING)

SMI-5006 moved Stripe billing (StripeClient, BillingService, StripeWebhookHandler, GDPRComplianceService, StripeReconciliationJob) to @smith-horn/enterprise. Update imports:

// Before (core ≤ 0.6.x)
import { StripeWebhookHandler } from '@skillsmith/core/billing'

// After (core ≥ 0.7.0)
import { StripeWebhookHandler } from '@smith-horn/enterprise/billing'

No back-compat shim is shipped — the ./billing subpath export was removed.

Requirements

• Node.js >= 22.0.0
• SQLite (via better-sqlite3)

License

Elastic License 2.0

Links

• GitHub
• Issues