@skillsmith/core

@skillsmith/core

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

Contents

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

What's New in v0.4.16

• Skill Dependency Intelligence: New SkillDependencyRepository for querying skill dependency graphs, extractMcpReferences() for inferring MCP server dependencies from SKILL.md content, mergeDependencies() for combining declared + inferred dependencies.
• DependencyDeclaration type: Replaces string[] in SkillFrontmatter.dependencies — structured dependency declarations with type, source, and confidence.
• Database migration v10: skill_dependencies table (SCHEMA_VERSION 10).

See CHANGELOG.md for previous releases.

Installation

npm install @skillsmith/core

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'

Requirements

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

License

Elastic License 2.0

Links

• GitHub
• Issues