@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