Compare commits

..
9 Commits
Author SHA1 Message Date
Rohit Ghumare b432400b5a chore: release v1.12.0 2026-02-04 00:29:39 +00:00
Rohit Ghumare e5f0d6d450 feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42)
* feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42)

Add runtime skill discovery capabilities enabling agents to autonomously
search and retrieve skills on demand, inspired by skyll.app's approach
of making skills queryable by intent rather than requiring pre-installation.

Core infrastructure:
- Pluggable cache backend with LRU + TTL (MemoryCache)
- Multi-signal relevance ranker (content 40pts, query 30pts, popularity 15pts, refs 15pts)
- Enhanced SKILL.md parser with frontmatter extraction and reference discovery
- Runtime skill injector fetching SKILL.md from GitHub with caching

REST API server (@skillkit/api):
- Hono-based HTTP server on port 3737
- GET/POST /search with ranked results and filters
- GET /skills/:source/:id, /trending, /categories, /health, /cache/stats
- Sliding-window rate limiting (60 req/min/IP)

MCP server (@skillkit/mcp):
- 4 tools: search_skills, get_skill, recommend_skills, list_categories
- 2 resources: skills://trending, skills://categories
- Compatible with Claude Desktop, Cursor, any MCP client

CLI serve command:
- `skillkit serve` starts the API server
- Options: --port, --host, --cors, --cache-ttl

Community registry:
- registry/SKILLS.md with 26 curated skills across 12 categories
- CommunityRegistry class integrated into FederatedSearch

Python client (skillkit-client):
- Async httpx + pydantic client for the REST API
- search, get_skill, trending, categories, cache_stats, health

All 856+ tests pass across 24 workspace tasks.

* fix: resolve TypeScript errors in API package

Add explicit return type to rate limiter middleware and remove stale
CategoryCount type annotation in categories route.

* fix: address CodeRabbit review findings and version-check CI

- Fix version-check: bump docs packages to 1.11.0
- Parse first IP from X-Forwarded-For header in rate limiter
- Add try/catch for malformed JSON in POST /search
- Use exact source match in skill routes (owner/repo/id pattern)
- Fix NaN fallback for invalid limit params in trending/search
- Filter empty strings from query words in relevance ranker
- Use Map lookups instead of O(n^2) find in MCP resources/tools
- URL-encode path params in Python client
- Fix -h flag conflict with Clipanion help in serve command
- Fix typo: remoti-dev -> remotion-dev in registry SKILLS.md

* fix: address Devin review — composite key lookups and Python URL path

- Use source+name composite key Map lookups in search GET/POST routes
- Use source+name composite key Map lookup in trending route
- Fix Python client get_skill to use /skills/:owner/:repo/:id URL pattern
- Update Python test to match new 3-segment skill URL
2026-02-04 00:27:25 +00:00
Rohit Ghumare e569046776 chore: release v1.11.0 2026-02-03 14:38:15 +00:00
Rohit Ghumare 5bd7ebf607 feat: viral growth features — quick setup, badges, matrix, SKILL.md, federated search (#41)
* feat: add viral growth features (quick setup, badges, matrix, SKILL.md, federated search)

Tier 2: skillkit quick zero-friction entry, shareable badge generator,
agent compatibility matrix on website.

Tier 3: reposition as npm for agent skills, SKILL.md validate/init/check
commands, federated GitHub skill search with --federated flag on find.

* fix: matrix filtering, path traversal, cross-platform paths, fetch timeout

- CompatibilityMatrix: query matching agents now shows all categories
  (and vice versa) instead of hiding both dimensions independently
- quick.ts: sanitize skill names and validate targetInstallPath stays
  inside installDir before rmSync/cpSync/symlinkSync
- skillmd.ts: use path.relative() instead of string replace for
  cross-platform path display
- registry: add AbortController timeout (10s default) and distinct
  RateLimitError on 403 instead of silent empty return
- find.ts: handle RateLimitError with user-facing message
- Add quick-security.test.ts regression tests for path traversal

* fix: harden isPathInside with path.resolve, propagate RateLimitError

- isPathInside now uses path.resolve() + path.sep comparison instead of
  naive string replacement, fixing detection of paths completely outside
  the parent directory (both packages/core and src/core copies)
- FederatedSearch.search re-throws RateLimitError from rejected
  Promise.allSettled results so callers (find.ts) can handle 403s
- Updated security test to use the corrected isPathInside logic

* fix: use GITHUB_TOKEN/GH_TOKEN for authenticated GitHub API requests

GitHubSkillRegistry now reads GITHUB_TOKEN or GH_TOKEN from env and
sends Bearer auth header, raising the rate limit from 10 to 30 req/min
for code search. Matches the guidance shown to users on 403 errors.
2026-02-03 13:48:35 +00:00
Rohit Ghumare 549a21ad84 chore: release v1.10.0 2026-02-02 23:33:12 +00:00
Rohit Ghumare 109f00cd95 feat(core): add QMD-inspired hybrid search pipeline (#40)
* feat(core): add QMD-inspired hybrid search pipeline

Implement a hybrid search system combining vector embeddings with keyword search:

- Vector embeddings using node-llama-cpp with GGUF models (nomic-embed-text)
- RRF (Reciprocal Rank Fusion) for combining multiple rankers
- Query expansion with LLM and synonym fallback
- Position-aware score blending (different weights for top3, top10, rest)
- SQLite storage with sqlite-vec extension (falls back to in-memory)
- Auto-download of local GGUF models (~2GB)

New search module:
- embeddings.ts: Vector embedding generation service
- vector-store.ts: SQLite-based vector storage
- rrf.ts: RRF fusion algorithm
- expansion.ts: Query expansion with caching
- hybrid.ts: Main hybrid search pipeline
- local-models.ts: GGUF model management

CLI integration:
- skillkit recommend --hybrid: Enable hybrid search
- skillkit recommend --expand: Enable query expansion
- skillkit recommend --rerank: Enable LLM re-ranking
- skillkit recommend --build-index: Build embedding index

Tests: 56 new tests for search module (all passing)

* fix(search): address CodeRabbit review findings

- Add missing beforeEach import in embeddings.test.ts
- Update optional dependencies to current versions
- Fix weights/variations length mismatch in expansion.ts
- Avoid mutating input arrays in rrf.ts mergeRankings
- Delete orphaned chunk vectors in vector-store.ts delete() and clear()
- Add comment for empty catch block in vector-store.ts
- Make hybridSearch helper use buildIndex for true hybrid search
- Handle graceful degradation when embeddings unavailable
- Add node-llama-cpp mock in hybrid.test.ts

* fix(search): address CodeRabbit review round 2

- Fix gemma GGUF URL to point to valid community repo (bartowski)
- Add SQL injection protection for table names in vector-store.ts
- Fix resource leak with try/finally in hybridSearch helper
- Add backpressure handling for large model downloads
- Clamp startLine to non-negative in chunk calculation
- Add runtime validation warning for --expand/--rerank without --hybrid
- Update node-llama-cpp API usage (createEmbeddingContext, createContext)
- Update pnpm-lock.yaml for new optional dependency versions

* fix(search): use @ts-ignore for optional node-llama-cpp imports

CI doesn't install optional dependencies, so @ts-ignore is needed
instead of @ts-expect-error to suppress module not found errors.
2026-02-02 23:28:08 +00:00
Rohit Ghumare e3d7e0e28f feat(marketplace): add beautiful-mermaid skill
Add beautiful-mermaid to the skills marketplace:
- Render Mermaid diagrams as beautiful SVGs or ASCII art
- 5 diagram types: flowchart, sequence, class, ER, state
- 15 built-in themes + Shiki/VS Code theme integration
- Zero DOM dependencies, works in Node.js/Bun/Deno/browsers

Source: rohitg00/beautiful-mermaid
2026-02-02 17:42:09 +00:00
Rohit Ghumare 6cbbdabf59 feat(website): add dynamic stats from npm and GitHub APIs (#39)
* feat(website): add dynamic stats from npm and GitHub APIs

- Create useStats hook to fetch real-time version, downloads, and stars
- Replace hardcoded values in App.tsx stats bar with dynamic data
- Replace hardcoded version in Hero.tsx badge with dynamic data
- Add 5-minute cache to reduce API calls
- Fallback to default values if APIs fail

* fix: address CodeRabbit and Devin review comments

- Fix duplicate API calls: remove useStats from Hero, pass version as prop from App
- Fix falsy checks: use typeof checks for downloads and stargazers_count
  to correctly handle zero values instead of showing defaults
2026-02-02 17:38:48 +00:00
Rohit Ghumare c1c179217d fix(website): update version to 1.9.0 2026-02-02 17:09:24 +00:00
96 changed files with 9259 additions and 40 deletions
+5 -2
View File
@@ -14,10 +14,13 @@
[![Website](https://img.shields.io/badge/Website-agenstskills.com-black)](https://agenstskills.com)
[![Docs](https://img.shields.io/badge/Docs-agenstskills.com/docs-blue)](https://agenstskills.com/docs)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![SKILL.md](https://img.shields.io/badge/SKILL.md-compatible-black?style=flat-square)](https://agenstskills.com)
## Supercharge Every AI Coding Agent
## One Skill. Every Agent.
**Give your AI agents new abilities with portable, reusable skills.** Install from a curated marketplace, create your own, and use them across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 27 more agents (32 total).
**The package manager for AI agent skills. Install, translate, and share skills across 32 coding agents.**
> Think npm, but for AI agent skills. Write once, deploy to Claude Code, Cursor, Codex, Windsurf, Copilot, and 27 more.
> **What are AI Agent Skills?** Skills are instruction files that teach AI coding agents how to handle specific tasks - like processing PDFs, following React best practices, or enforcing security patterns. Think of them as plugins for your AI assistant.
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit",
"version": "1.9.0",
"version": "1.12.0",
"description": "Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 13 more",
"type": "module",
"bin": {
@@ -53,6 +53,7 @@
"node": ">=18.0.0"
},
"dependencies": {
"@skillkit/api": "workspace:*",
"@skillkit/core": "workspace:*",
"@skillkit/agents": "workspace:*",
"@skillkit/cli": "workspace:*",
+12
View File
@@ -98,6 +98,11 @@ import {
GuidelineCreateCommand,
GuidelineRemoveCommand,
TreeCommand,
QuickCommand,
SkillMdValidateCommand,
SkillMdInitCommand,
SkillMdCheckCommand,
ServeCommand,
} from '@skillkit/cli';
const __filename = fileURLToPath(import.meta.url);
@@ -220,4 +225,11 @@ cli.register(GuidelineRemoveCommand);
cli.register(TreeCommand);
cli.register(QuickCommand);
cli.register(SkillMdValidateCommand);
cli.register(SkillMdInitCommand);
cli.register(SkillMdCheckCommand);
cli.register(ServeCommand);
cli.runExit(process.argv.slice(2));
+42
View File
@@ -0,0 +1,42 @@
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "skillkit-client"
version = "0.1.0"
description = "Python client for the SkillKit REST API"
readme = "README.md"
license = "Apache-2.0"
requires-python = ">=3.9"
authors = [
{ name = "Rohit Ghumare", email = "ghumare64@gmail.com" },
]
keywords = ["skillkit", "ai", "agents", "skills", "discovery"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Topic :: Software Development :: Libraries",
]
dependencies = [
"httpx>=0.27",
"pydantic>=2.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0",
"pytest-asyncio>=0.23",
"respx>=0.21",
]
[project.urls]
Homepage = "https://github.com/rohitg00/skillkit"
Documentation = "https://agenstskills.com"
Repository = "https://github.com/rohitg00/skillkit"
+12
View File
@@ -0,0 +1,12 @@
from skillkit.client import SkillKitClient
from skillkit.models import Skill, SearchResponse, HealthResponse, CacheStats, Category
__all__ = [
"SkillKitClient",
"Skill",
"SearchResponse",
"HealthResponse",
"CacheStats",
"Category",
]
__version__ = "0.1.0"
+140
View File
@@ -0,0 +1,140 @@
from __future__ import annotations
from typing import Optional
from urllib.parse import quote
import httpx
from skillkit.models import (
CacheStats,
CategoriesResponse,
Category,
HealthResponse,
SearchResponse,
Skill,
TrendingResponse,
)
class SkillKitClient:
def __init__(self, base_url: str = "http://localhost:3737", timeout: float = 30.0):
self.base_url = base_url.rstrip("/")
self.timeout = timeout
self._client: Optional[httpx.AsyncClient] = None
async def __aenter__(self) -> "SkillKitClient":
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
return self
async def __aexit__(self, *args: object) -> None:
if self._client:
await self._client.aclose()
self._client = None
def _get_client(self) -> httpx.AsyncClient:
if self._client is None:
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
return self._client
async def health(self) -> HealthResponse:
client = self._get_client()
response = await client.get("/health")
response.raise_for_status()
data = response.json()
return HealthResponse(
status=data["status"],
version=data["version"],
skill_count=data.get("skillCount", 0),
uptime=data.get("uptime", 0),
)
async def search(
self,
query: str,
limit: int = 20,
include_content: bool = False,
) -> SearchResponse:
client = self._get_client()
params = {"q": query, "limit": str(limit)}
if include_content:
params["include_content"] = "true"
response = await client.get("/search", params=params)
response.raise_for_status()
data = response.json()
return SearchResponse(
skills=[Skill(**s) for s in data["skills"]],
total=data["total"],
query=data["query"],
limit=data["limit"],
)
async def search_with_filters(
self,
query: str,
limit: int = 20,
include_content: bool = False,
tags: Optional[list[str]] = None,
category: Optional[str] = None,
source: Optional[str] = None,
) -> SearchResponse:
client = self._get_client()
body: dict = {"query": query, "limit": limit, "include_content": include_content}
filters: dict = {}
if tags:
filters["tags"] = tags
if category:
filters["category"] = category
if source:
filters["source"] = source
if filters:
body["filters"] = filters
response = await client.post("/search", json=body)
response.raise_for_status()
data = response.json()
return SearchResponse(
skills=[Skill(**s) for s in data["skills"]],
total=data["total"],
query=data["query"],
limit=data["limit"],
)
async def get_skill(self, source: str, skill_id: str) -> Skill:
client = self._get_client()
parts = source.split("/", 1)
owner = quote(parts[0], safe="")
repo = quote(parts[1], safe="") if len(parts) > 1 else owner
response = await client.get(f"/skills/{owner}/{repo}/{quote(skill_id, safe='')}")
response.raise_for_status()
return Skill(**response.json())
async def trending(self, limit: int = 20) -> list[Skill]:
client = self._get_client()
response = await client.get("/trending", params={"limit": str(limit)})
response.raise_for_status()
data = response.json()
return [Skill(**s) for s in data["skills"]]
async def categories(self) -> list[Category]:
client = self._get_client()
response = await client.get("/categories")
response.raise_for_status()
data = response.json()
return [Category(**c) for c in data["categories"]]
async def cache_stats(self) -> CacheStats:
client = self._get_client()
response = await client.get("/cache/stats")
response.raise_for_status()
data = response.json()
return CacheStats(
hits=data["hits"],
misses=data["misses"],
size=data["size"],
max_size=data.get("maxSize", 0),
hit_rate=data.get("hitRate", 0.0),
)
async def close(self) -> None:
if self._client:
await self._client.aclose()
self._client = None
+51
View File
@@ -0,0 +1,51 @@
from typing import Optional
from pydantic import BaseModel
class Skill(BaseModel):
name: str
description: Optional[str] = None
source: str
repo: Optional[str] = None
tags: Optional[list[str]] = None
category: Optional[str] = None
content: Optional[str] = None
stars: Optional[int] = None
installs: Optional[int] = None
class SearchResponse(BaseModel):
skills: list[Skill]
total: int
query: str
limit: int
class HealthResponse(BaseModel):
status: str
version: str
skill_count: int = 0
uptime: int = 0
class CacheStats(BaseModel):
hits: int
misses: int
size: int
max_size: int = 0
hit_rate: float = 0.0
class Category(BaseModel):
name: str
count: int
class CategoriesResponse(BaseModel):
categories: list[Category]
total: int
class TrendingResponse(BaseModel):
skills: list[Skill]
limit: int
View File
+99
View File
@@ -0,0 +1,99 @@
import pytest
import httpx
import respx
from skillkit import SkillKitClient
BASE_URL = "http://localhost:3737"
@pytest.fixture
def mock_api():
with respx.mock(base_url=BASE_URL) as respx_mock:
yield respx_mock
@pytest.mark.asyncio
async def test_health(mock_api):
mock_api.get("/health").respond(
json={"status": "ok", "version": "1.11.0", "skillCount": 100, "uptime": 60}
)
async with SkillKitClient(BASE_URL) as client:
health = await client.health()
assert health.status == "ok"
assert health.version == "1.11.0"
assert health.skill_count == 100
@pytest.mark.asyncio
async def test_search(mock_api):
mock_api.get("/search").respond(
json={
"skills": [{"name": "react-perf", "source": "owner/repo"}],
"total": 1,
"query": "react",
"limit": 20,
}
)
async with SkillKitClient(BASE_URL) as client:
result = await client.search("react")
assert result.total == 1
assert result.skills[0].name == "react-perf"
@pytest.mark.asyncio
async def test_search_with_filters(mock_api):
mock_api.post("/search").respond(
json={
"skills": [{"name": "nextjs-auth", "source": "other/repo"}],
"total": 1,
"query": "auth",
"limit": 20,
}
)
async with SkillKitClient(BASE_URL) as client:
result = await client.search_with_filters("auth", tags=["nextjs"])
assert result.total == 1
@pytest.mark.asyncio
async def test_get_skill(mock_api):
mock_api.get("/skills/owner/repo/react-perf").respond(
json={"name": "react-perf", "description": "React performance", "source": "owner/repo"}
)
async with SkillKitClient(BASE_URL) as client:
skill = await client.get_skill("owner/repo", "react-perf")
assert skill.name == "react-perf"
@pytest.mark.asyncio
async def test_trending(mock_api):
mock_api.get("/trending").respond(
json={"skills": [{"name": "a", "source": "x/y"}], "limit": 20}
)
async with SkillKitClient(BASE_URL) as client:
trending = await client.trending()
assert len(trending) == 1
@pytest.mark.asyncio
async def test_categories(mock_api):
mock_api.get("/categories").respond(
json={"categories": [{"name": "react", "count": 5}], "total": 1}
)
async with SkillKitClient(BASE_URL) as client:
cats = await client.categories()
assert len(cats) == 1
assert cats[0].name == "react"
@pytest.mark.asyncio
async def test_cache_stats(mock_api):
mock_api.get("/cache/stats").respond(
json={"hits": 10, "misses": 5, "size": 8, "maxSize": 500, "hitRate": 0.667}
)
async with SkillKitClient(BASE_URL) as client:
stats = await client.cache_stats()
assert stats.hits == 10
assert stats.size == 8
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit-docs",
"version": "1.9.0",
"version": "1.12.0",
"private": true,
"scripts": {
"build": "next build",
+33 -4
View File
@@ -12,6 +12,9 @@ import { Attribution } from './components/Attribution';
import { AdvancedFeatures } from './components/AdvancedFeatures';
import { UseCases } from './components/UseCases';
import { TeamEnterprise } from './components/TeamEnterprise';
import { BadgeGenerator } from './components/BadgeGenerator';
import { CompatibilityMatrix } from './components/CompatibilityMatrix';
import { useStats } from './hooks/useStats';
const GITHUB_ICON = (
<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
@@ -34,6 +37,8 @@ function scrollToSection(e: React.MouseEvent, sectionId: string): void {
}
export default function App(): React.ReactElement {
const stats = useStats();
return (
<div className="min-h-screen text-zinc-100 font-sans selection:bg-white selection:text-black" style={{ backgroundColor: '#000000' }}>
<nav className="fixed top-0 left-0 right-0 z-50 border-b border-zinc-800 backdrop-blur-md" style={{ backgroundColor: 'rgba(0,0,0,0.9)' }}>
@@ -58,6 +63,20 @@ export default function App(): React.ReactElement {
>
Stack
</a>
<a
href="#matrix"
onClick={(e) => scrollToSection(e, 'matrix')}
className="text-zinc-500 hover:text-white transition-colors"
>
Matrix
</a>
<a
href="#badge"
onClick={(e) => scrollToSection(e, 'badge')}
className="text-zinc-500 hover:text-white transition-colors"
>
Badge
</a>
<a
href="#advanced"
onClick={(e) => scrollToSection(e, 'advanced')}
@@ -102,7 +121,7 @@ export default function App(): React.ReactElement {
</nav>
<main className="pt-14">
<Hero />
<Hero version={stats.version} />
<div className="border-b border-zinc-800/50 py-2.5" style={{ background: 'linear-gradient(to bottom, rgba(9,9,11,0.95), rgba(0,0,0,1))' }}>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
@@ -114,7 +133,7 @@ export default function App(): React.ReactElement {
className="flex items-center gap-1.5 text-zinc-500 hover:text-white transition-colors group"
>
<span className="text-zinc-600 group-hover:text-zinc-400">v</span>
<span className="text-white font-medium">1.8.0</span>
<span className="text-white font-medium">{stats.version}</span>
</a>
<span className="text-zinc-800">·</span>
<a
@@ -126,7 +145,7 @@ export default function App(): React.ReactElement {
<svg className="w-3 h-3 text-zinc-600 group-hover:text-zinc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
</svg>
<span className="text-white font-medium">2.4k</span>
<span className="text-white font-medium">{stats.downloads}</span>
</a>
<span className="text-zinc-800">·</span>
<a
@@ -138,7 +157,7 @@ export default function App(): React.ReactElement {
<svg className="w-3 h-3 text-zinc-600 group-hover:text-yellow-500" fill="currentColor" viewBox="0 0 24 24">
<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" />
</svg>
<span className="text-white font-medium">66</span>
<span className="text-white font-medium">{stats.stars}</span>
</a>
<span className="text-zinc-800 hidden sm:inline">·</span>
<a
@@ -169,6 +188,16 @@ export default function App(): React.ReactElement {
<StackBuilder />
</section>
{/* Compatibility Matrix */}
<section id="matrix" style={{ scrollMarginTop: '4rem' }}>
<CompatibilityMatrix />
</section>
{/* Badge Generator */}
<section id="badge" style={{ scrollMarginTop: '4rem' }}>
<BadgeGenerator />
</section>
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
<AdvancedFeatures />
+201
View File
@@ -0,0 +1,201 @@
import React, { useState, useMemo } from 'react';
const SKILLKIT_LOGO_SVG_BASE64 =
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
const SUGGESTED_SKILLS = [
'react', 'typescript', 'nextjs', 'python', 'docker',
'kubernetes', 'tailwind', 'graphql', 'prisma', 'langchain',
'openai', 'rust', 'go', 'vue', 'svelte',
'security', 'testing', 'cicd', 'aws', 'terraform',
];
function encodeBadgeSegment(text: string): string {
return encodeURIComponent(text).replace(/-/g, '--');
}
function buildBadgeUrl(skills: string[]): string {
if (skills.length === 0) {
return `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
}
const maxDisplay = 5;
const displayNames = skills.slice(0, maxDisplay);
const suffix = skills.length > maxDisplay ? ` +${skills.length - maxDisplay} more` : '';
const label = `SkillKit ${skills.length} skills`;
const message = displayNames.join(' | ') + suffix;
return `https://img.shields.io/badge/${encodeBadgeSegment(label)}-${encodeBadgeSegment(message)}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
}
export function BadgeGenerator(): React.ReactElement {
const [skills, setSkills] = useState<string[]>(['react', 'typescript', 'nextjs']);
const [inputValue, setInputValue] = useState('');
const [copiedType, setCopiedType] = useState<string | null>(null);
const badgeUrl = useMemo(() => buildBadgeUrl(skills), [skills]);
const markdown = `[![SkillKit Stack](${badgeUrl})](https://agenstskills.com)`;
const html = `<a href="https://agenstskills.com"><img src="${badgeUrl}" alt="SkillKit Stack" /></a>`;
function addSkill(skill: string): void {
const trimmed = skill.trim().toLowerCase();
if (trimmed && !skills.includes(trimmed)) {
setSkills([...skills, trimmed]);
}
setInputValue('');
}
function removeSkill(skill: string): void {
setSkills(skills.filter(s => s !== skill));
}
function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>): void {
if (e.key === 'Enter' && inputValue.trim()) {
e.preventDefault();
addSkill(inputValue);
}
}
async function copyToClipboard(text: string, type: string): Promise<void> {
try {
await navigator.clipboard.writeText(text);
setCopiedType(type);
setTimeout(() => setCopiedType(null), 2000);
} catch {
// silently ignore
}
}
const availableSuggestions = SUGGESTED_SKILLS.filter(s => !skills.includes(s));
return (
<section className="py-12 border-b border-zinc-800">
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="mb-6">
<h2 className="text-xl font-bold text-white mb-1 font-mono">Badge Generator</h2>
<p className="text-zinc-500 font-mono text-xs">
Create a shareable badge for your skill stack. Add it to your README.
</p>
</div>
<div className="flex flex-col lg:flex-row gap-6">
<div className="flex-1 space-y-4">
<div className="relative">
<input
type="text"
value={inputValue}
onChange={(e) => setInputValue(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Type a skill name and press Enter..."
className="w-full bg-zinc-900 border border-zinc-700 text-white px-4 py-3 focus:ring-2 focus:ring-white focus:border-transparent outline-none font-mono text-sm placeholder-zinc-600"
/>
</div>
<div className="space-y-2">
<span className="text-zinc-500 text-xs font-mono block">Quick add:</span>
<div className="flex flex-wrap gap-1.5">
{availableSuggestions.slice(0, 12).map(skill => (
<button
key={skill}
onClick={() => addSkill(skill)}
className="text-[10px] sm:text-xs bg-zinc-900 text-zinc-400 px-2 sm:px-3 py-1 sm:py-1.5 border border-zinc-700 hover:border-zinc-500 hover:text-white transition-colors font-mono"
>
+ {skill}
</button>
))}
</div>
</div>
{skills.length > 0 && (
<div className="space-y-2">
<div className="flex items-center justify-between">
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">
Skills in Badge ({skills.length})
</div>
<button
onClick={() => setSkills([])}
className="text-zinc-500 hover:text-red-400 font-mono text-xs transition-colors"
>
Clear All
</button>
</div>
<div className="flex flex-wrap gap-2">
{skills.map(skill => (
<div
key={skill}
className="flex items-center gap-1.5 bg-zinc-900/50 border border-zinc-800 px-3 py-1.5 group"
>
<span className="font-mono text-sm text-white">{skill}</span>
<button
onClick={() => removeSkill(skill)}
aria-label={`Remove ${skill}`}
className="text-zinc-600 hover:text-red-400 transition-colors opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
>
<svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
</svg>
</button>
</div>
))}
</div>
</div>
)}
</div>
<div className="lg:w-80 lg:flex-shrink-0">
<div className="lg:sticky lg:top-20 bg-zinc-900/30 border border-zinc-800 p-4 space-y-4">
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">Preview</div>
<div className="flex justify-center py-3 bg-black/50 border border-zinc-800">
{skills.length > 0 ? (
<img
src={badgeUrl}
alt="SkillKit Stack Badge"
className="h-5"
/>
) : (
<span className="text-zinc-600 text-xs font-mono">Add skills to preview</span>
)}
</div>
<div className="space-y-2">
<div className="text-xs font-mono text-zinc-500">Markdown</div>
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
{markdown}
</code>
</pre>
<button
onClick={() => copyToClipboard(markdown, 'markdown')}
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
>
{copiedType === 'markdown' ? 'Copied!' : 'Copy Markdown'}
</button>
</div>
<div className="space-y-2">
<div className="text-xs font-mono text-zinc-500">HTML</div>
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
{html}
</code>
</pre>
<button
onClick={() => copyToClipboard(html, 'html')}
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
>
{copiedType === 'html' ? 'Copied!' : 'Copy HTML'}
</button>
</div>
<div className="text-[10px] font-mono text-zinc-600 text-center pt-2 border-t border-zinc-800">
Powered by shields.io
</div>
</div>
</div>
</div>
</div>
</section>
);
}
@@ -0,0 +1,351 @@
import React, { useState, useMemo } from 'react';
type Support = 'full' | 'partial' | 'none';
interface AgentDef {
id: string;
name: string;
icon: string;
group: string;
}
interface CategoryDef {
id: string;
name: string;
icon: string;
}
const AGENTS: AgentDef[] = [
{ id: 'claude-code', name: 'Claude Code', icon: '\u27C1', group: 'Tier 1' },
{ id: 'cursor', name: 'Cursor', icon: '\u25EB', group: 'Tier 1' },
{ id: 'codex', name: 'Codex', icon: '\u25CE', group: 'Tier 1' },
{ id: 'gemini-cli', name: 'Gemini CLI', icon: '\u2726', group: 'Tier 1' },
{ id: 'opencode', name: 'OpenCode', icon: '\u2B21', group: 'Tier 1' },
{ id: 'windsurf', name: 'Windsurf', icon: '\u25C7', group: 'Tier 1' },
{ id: 'github-copilot', name: 'Copilot', icon: '\u2318', group: 'Tier 1' },
{ id: 'goose', name: 'Goose', icon: '\u25CA', group: 'Tier 2' },
{ id: 'kilo', name: 'Kilo', icon: '\u25B3', group: 'Tier 2' },
{ id: 'kiro-cli', name: 'Kiro CLI', icon: '\u25BD', group: 'Tier 2' },
{ id: 'roo', name: 'Roo', icon: '\u25C6', group: 'Tier 2' },
{ id: 'trae', name: 'Trae', icon: '\u25A0', group: 'Tier 2' },
{ id: 'amp', name: 'AMP', icon: '\u26A1', group: 'Tier 2' },
{ id: 'cline', name: 'Cline', icon: '\u25CF', group: 'Tier 3' },
{ id: 'continue', name: 'Continue', icon: '\u25B6', group: 'Tier 3' },
{ id: 'antigravity', name: 'Antigravity', icon: '\u2191', group: 'Tier 3' },
];
const CATEGORIES: CategoryDef[] = [
{ id: 'security', name: 'Security', icon: '\u25D0' },
{ id: 'testing', name: 'Testing', icon: '\u25D2' },
{ id: 'react-frontend', name: 'React/Frontend', icon: '\u269B' },
{ id: 'backend', name: 'Backend', icon: '\u2393' },
{ id: 'devops', name: 'DevOps', icon: '\u25D1' },
{ id: 'python', name: 'Python', icon: '\u25C9' },
{ id: 'go', name: 'Go', icon: '\u25C8' },
{ id: 'typescript', name: 'TypeScript', icon: '\u25C8' },
{ id: 'database', name: 'Database', icon: '\u25A3' },
{ id: 'performance', name: 'Performance', icon: '\u25CE' },
{ id: 'documentation', name: 'Documentation', icon: '\u25A1' },
{ id: 'ai-ml', name: 'AI/ML', icon: '\u25CE' },
];
const MATRIX: Record<string, Record<string, Support>> = {
'security': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'partial', 'antigravity': 'partial',
},
'testing': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'react-frontend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'none',
},
'backend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'devops': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'full', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'python': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'go': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'typescript': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'database': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'performance': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'documentation': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'ai-ml': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
};
const SUPPORT_CONFIG: Record<Support, { color: string; bg: string; label: string }> = {
full: { color: 'text-green-400', bg: 'bg-green-400/10', label: 'Full' },
partial: { color: 'text-yellow-400', bg: 'bg-yellow-400/10', label: 'Partial' },
none: { color: 'text-red-400', bg: 'bg-red-400/10', label: 'None' },
};
const SUPPORT_SCORE: Record<Support, number> = { full: 2, partial: 1, none: 0 };
function SupportCell({ support }: { support: Support }): React.ReactElement {
const config = SUPPORT_CONFIG[support];
return (
<td className="px-1 py-2 text-center">
<div className={`inline-flex items-center justify-center w-5 h-5 rounded-full ${config.bg}`}>
<span className={`text-[10px] font-bold ${config.color}`}>
{support === 'full' ? '\u2713' : support === 'partial' ? '\u25CB' : '\u2715'}
</span>
</div>
</td>
);
}
function getAgentScore(agentId: string): number {
return Object.values(MATRIX).reduce((sum, row) => sum + SUPPORT_SCORE[row[agentId] || 'none'], 0);
}
function getMaxScore(): number {
return CATEGORIES.length * 2;
}
export function CompatibilityMatrix(): React.ReactElement {
const [filter, setFilter] = useState('');
const [groupFilter, setGroupFilter] = useState<string | null>(null);
const groups = useMemo(() => {
const seen = new Set<string>();
return AGENTS.reduce<string[]>((acc, a) => {
if (!seen.has(a.group)) {
seen.add(a.group);
acc.push(a.group);
}
return acc;
}, []);
}, []);
const { filteredAgents, filteredCategories } = useMemo(() => {
let agents = AGENTS;
if (groupFilter) {
agents = agents.filter(a => a.group === groupFilter);
}
if (!filter.trim()) {
return { filteredAgents: agents, filteredCategories: CATEGORIES };
}
const q = filter.toLowerCase();
const matchedAgents = agents.filter(a =>
a.name.toLowerCase().includes(q) || a.id.toLowerCase().includes(q)
);
const matchedCategories = CATEGORIES.filter(c =>
c.name.toLowerCase().includes(q) || c.id.toLowerCase().includes(q)
);
return {
filteredAgents: matchedAgents.length > 0 ? matchedAgents : (matchedCategories.length > 0 ? agents : []),
filteredCategories: matchedCategories.length > 0 ? matchedCategories : (matchedAgents.length > 0 ? CATEGORIES : []),
};
}, [filter, groupFilter]);
const maxScore = getMaxScore();
return (
<section className="py-12 border-b border-zinc-800" style={{ backgroundColor: '#09090b' }}>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="flex flex-col sm:flex-row sm:items-center justify-between gap-2 mb-6">
<div>
<h2 className="text-lg sm:text-xl font-bold text-white mb-1 font-mono">Compatibility Matrix</h2>
<p className="text-zinc-500 font-mono text-[10px] sm:text-xs">
Skill support across 16 agents and 12 categories.
</p>
</div>
<div className="flex items-center gap-2">
<span className="w-2 h-2 bg-green-500 rounded-full"></span>
<span className="text-[10px] sm:text-xs font-mono text-zinc-500">Updated Feb 2026</span>
</div>
</div>
<div className="flex flex-col sm:flex-row gap-2 sm:gap-3 mb-6">
<div className="relative flex-1">
<svg className="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-zinc-600" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
</svg>
<input
type="text"
value={filter}
onChange={(e) => setFilter(e.target.value)}
placeholder="Filter agents or categories..."
className="w-full bg-black border border-zinc-800 text-zinc-300 placeholder-zinc-700 font-mono text-xs px-8 py-2 focus:outline-none focus:border-zinc-600 transition-colors"
/>
{filter && (
<button
onClick={() => setFilter('')}
className="absolute right-2.5 top-1/2 -translate-y-1/2 text-zinc-600 hover:text-zinc-400 transition-colors"
>
<svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
</svg>
</button>
)}
</div>
<div className="flex gap-1.5">
<button
onClick={() => setGroupFilter(null)}
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
groupFilter === null
? 'bg-white text-black'
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
}`}
>
All
</button>
{groups.map(g => (
<button
key={g}
onClick={() => setGroupFilter(groupFilter === g ? null : g)}
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
groupFilter === g
? 'bg-white text-black'
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
}`}
>
{g}
</button>
))}
</div>
</div>
<div className="flex items-center gap-4 mb-4">
{Object.entries(SUPPORT_CONFIG).map(([key, config]) => (
<div key={key} className="flex items-center gap-1.5">
<div className={`w-3 h-3 rounded-full ${config.bg} flex items-center justify-center`}>
<span className={`text-[8px] font-bold ${config.color}`}>
{key === 'full' ? '\u2713' : key === 'partial' ? '\u25CB' : '\u2715'}
</span>
</div>
<span className="text-[10px] font-mono text-zinc-500">{config.label}</span>
</div>
))}
</div>
<div className="overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0">
<div className="min-w-[700px]">
<table className="w-full border-collapse font-mono text-[10px]">
<thead>
<tr className="border-b border-zinc-800">
<th className="text-left text-zinc-500 uppercase tracking-wider py-2 pr-3 sticky left-0 bg-[#09090b] z-10 min-w-[120px]">
Category
</th>
{filteredAgents.map(agent => (
<th key={agent.id} className="px-1 py-2 text-center">
<div className="flex flex-col items-center gap-0.5">
<span className="text-sm">{agent.icon}</span>
<span className="text-zinc-400 whitespace-nowrap max-w-[50px] truncate" title={agent.name}>
{agent.name.length > 7 ? agent.name.slice(0, 7) : agent.name}
</span>
</div>
</th>
))}
</tr>
</thead>
<tbody>
{filteredCategories.map(category => (
<tr key={category.id} className="border-b border-zinc-800/50 hover:bg-zinc-900/50 transition-colors">
<td className="py-2 pr-3 sticky left-0 bg-[#09090b] z-10">
<div className="flex items-center gap-1.5">
<span className="text-zinc-600">{category.icon}</span>
<span className="text-zinc-300 whitespace-nowrap">{category.name}</span>
</div>
</td>
{filteredAgents.map(agent => (
<SupportCell
key={agent.id}
support={MATRIX[category.id]?.[agent.id] || 'none'}
/>
))}
</tr>
))}
</tbody>
<tfoot>
<tr className="border-t border-zinc-700">
<td className="py-3 pr-3 sticky left-0 bg-[#09090b] z-10">
<span className="text-zinc-400 font-bold uppercase tracking-wider">Score</span>
</td>
{filteredAgents.map(agent => {
const score = getAgentScore(agent.id);
const pct = Math.round((score / maxScore) * 100);
const color = pct >= 80 ? 'text-green-400' : pct >= 50 ? 'text-yellow-400' : 'text-red-400';
return (
<td key={agent.id} className="px-1 py-3 text-center">
<div className={`font-bold text-xs ${color}`}>{pct}%</div>
<div className="text-zinc-600 text-[9px]">{score}/{maxScore}</div>
</td>
);
})}
</tr>
</tfoot>
</table>
</div>
</div>
{filteredAgents.length === 0 && (
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
No agents match your filter.
</div>
)}
{filteredCategories.length === 0 && filteredAgents.length > 0 && (
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
No categories match your filter.
</div>
)}
</div>
</section>
);
}
+2 -2
View File
@@ -9,7 +9,7 @@ interface Feature {
const FEATURES: Feature[] = [
{
title: 'Smart Recommendations',
description: 'AI analyzes your codebase and suggests perfect skills.',
description: 'AI analyzes your codebase and recommends from 15,000+ skills.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
@@ -18,7 +18,7 @@ const FEATURES: Feature[] = [
},
{
title: 'Auto Translation',
description: 'Write once, deploy to 32 agents. Zero manual conversion.',
description: 'The npm for agent skills. Write once, auto-translate to 32 formats.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
+11 -7
View File
@@ -1,6 +1,10 @@
import React, { useState, useEffect } from 'react';
import { Button } from './Button';
interface HeroProps {
version: string;
}
const ASCII_LOGO = `
███████╗██╗ ██╗██╗██╗ ██╗ ██╗ ██╗██╗████████╗
██╔════╝██║ ██╔╝██║██║ ██║ ██║ ██╔╝██║╚══██╔══╝
@@ -55,7 +59,7 @@ const COPY_ICON = (
</svg>
);
export function Hero(): React.ReactElement {
export function Hero({ version }: HeroProps): React.ReactElement {
const [copied, setCopied] = useState(false);
const [visibleLines, setVisibleLines] = useState(0);
const [typingIndex, setTypingIndex] = useState(0);
@@ -126,18 +130,18 @@ export function Hero(): React.ReactElement {
<div className="animate-fade-in">
<div className="inline-flex items-center space-x-2 border border-zinc-800 bg-zinc-900/50 px-2 py-0.5 mb-3 backdrop-blur-sm">
<span className="flex h-1.5 w-1.5 bg-white rounded-full"></span>
<span className="text-xs font-mono text-zinc-400">v1.8.0</span>
<span className="text-xs font-mono text-zinc-400">v{version}</span>
</div>
<h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold tracking-tight text-white mb-3 font-mono">
Write Once.<br />
<span className="text-zinc-500">Deploy to 32 Agents.</span>
One Skill.<br />
<span className="text-zinc-500">32 Agents. Zero Rewrites.</span>
</h1>
<p className="text-sm text-zinc-400 mb-5 max-w-lg font-mono leading-relaxed">
The universal skill platform for AI coding agents. Auto-generate instructions
with Primer, persist learnings with Memory, distribute across Mesh networks.
One CLI for Claude, Cursor, Windsurf, Copilot, and 28 more.
The package manager for AI agent skills. Install from 15,000+ skills,
auto-translate between formats, persist learnings with Memory.
Works with Claude, Cursor, Windsurf, Copilot, and 28 more.
</p>
<div className="flex flex-wrap items-center gap-3 mb-4">
+119
View File
@@ -0,0 +1,119 @@
import { useState, useEffect } from 'react';
interface Stats {
version: string;
downloads: string;
stars: number;
loading: boolean;
}
const CACHE_KEY = 'skillkit_stats_cache';
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
interface CachedStats {
data: Omit<Stats, 'loading'>;
timestamp: number;
}
function formatDownloads(count: number): string {
if (count >= 1000000) {
return `${(count / 1000000).toFixed(1)}M`;
}
if (count >= 1000) {
return `${(count / 1000).toFixed(1)}k`;
}
return count.toString();
}
function getCachedStats(): CachedStats | null {
try {
const cached = localStorage.getItem(CACHE_KEY);
if (cached) {
const parsed: CachedStats = JSON.parse(cached);
if (Date.now() - parsed.timestamp < CACHE_TTL) {
return parsed;
}
}
} catch {
// Ignore localStorage errors
}
return null;
}
function setCachedStats(data: Omit<Stats, 'loading'>): void {
try {
const cached: CachedStats = {
data,
timestamp: Date.now(),
};
localStorage.setItem(CACHE_KEY, JSON.stringify(cached));
} catch {
// Ignore localStorage errors
}
}
export function useStats(): Stats {
const [stats, setStats] = useState<Stats>({
version: '1.9.0',
downloads: '2.4k',
stars: 66,
loading: true,
});
useEffect(() => {
const cached = getCachedStats();
if (cached) {
setStats({ ...cached.data, loading: false });
return;
}
async function fetchStats(): Promise<void> {
try {
const [npmResponse, githubResponse] = await Promise.allSettled([
fetch('https://api.npmjs.org/downloads/point/last-month/skillkit'),
fetch('https://api.github.com/repos/rohitg00/skillkit'),
]);
let downloads = '2.4k';
let stars = 66;
let version = '1.9.0';
if (npmResponse.status === 'fulfilled' && npmResponse.value.ok) {
const npmData = await npmResponse.value.json();
if (typeof npmData.downloads === 'number' && Number.isFinite(npmData.downloads)) {
downloads = formatDownloads(npmData.downloads);
}
}
if (githubResponse.status === 'fulfilled' && githubResponse.value.ok) {
const githubData = await githubResponse.value.json();
if (typeof githubData.stargazers_count === 'number' && Number.isFinite(githubData.stargazers_count)) {
stars = githubData.stargazers_count;
}
}
try {
const registryResponse = await fetch('https://registry.npmjs.org/skillkit/latest');
if (registryResponse.ok) {
const registryData = await registryResponse.json();
if (registryData.version) {
version = registryData.version;
}
}
} catch {
// Use default version
}
const newStats = { version, downloads, stars };
setCachedStats(newStats);
setStats({ ...newStats, loading: false });
} catch {
setStats((prev) => ({ ...prev, loading: false }));
}
}
fetchStats();
}, []);
return stats;
}
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "skillkit",
"private": true,
"version": "1.9.0",
"version": "1.12.0",
"type": "module",
"scripts": {
"dev": "vite",
+19 -2
View File
@@ -1,8 +1,8 @@
{
"$schema": "./schema.json",
"version": 1,
"updatedAt": "2026-01-26",
"totalSkills": 15064,
"updatedAt": "2026-02-02",
"totalSkills": 15065,
"curatedCollections": 31,
"skills": [
{
@@ -33112,6 +33112,23 @@
"k8s"
]
},
{
"id": "rohitg00/beautiful-mermaid/beautiful-mermaid",
"name": "Beautiful Mermaid",
"description": "Render Mermaid diagrams as beautiful SVGs or ASCII art. 5 diagram types, 15 themes, Shiki integration, zero DOM dependencies.",
"source": "rohitg00/beautiful-mermaid",
"tags": [
"mermaid",
"diagrams",
"visualization",
"flowchart",
"sequence",
"uml",
"ascii",
"svg",
"themes"
]
},
{
"id": "itsmostafa/aws-agent-skills/cognito",
"name": "Cognito",
+9 -3
View File
@@ -1,8 +1,8 @@
{
"name": "skillkit-monorepo",
"version": "1.9.0",
"version": "1.12.0",
"private": true,
"description": "Universal skills loader for AI coding agents - Monorepo",
"description": "The package manager for AI agent skills — install, translate, share across 32 coding agents",
"type": "module",
"scripts": {
"build": "turbo run build",
@@ -31,7 +31,13 @@
"coding-assistant",
"skill-loader",
"cli",
"monorepo"
"monorepo",
"skill-md",
"package-manager",
"plugin",
"workflow",
"automation",
"SKILL.md"
],
"author": "Rohit Ghumare",
"license": "Apache-2.0",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/agents",
"version": "1.9.0",
"version": "1.12.0",
"description": "Agent adapters for SkillKit - supports 32 AI coding agents",
"type": "module",
"main": "./dist/index.js",
+52
View File
@@ -0,0 +1,52 @@
{
"name": "@skillkit/api",
"version": "1.12.0",
"description": "REST API server for SkillKit skill discovery",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"bin": {
"skillkit-api": "./dist/index.js"
},
"exports": {
".": {
"import": "./dist/index.js",
"types": "./dist/index.d.ts"
}
},
"files": [
"dist"
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"start": "node dist/index.js"
},
"dependencies": {
"hono": "^4.0.0",
"@hono/node-server": "^1.0.0",
"@skillkit/core": "workspace:*",
"zod": "^3.24.0"
},
"devDependencies": {
"@types/node": "^22.10.5",
"tsup": "^8.3.5",
"typescript": "^5.7.2",
"vitest": "^2.1.8"
},
"engines": {
"node": ">=18.0.0"
},
"license": "Apache-2.0",
"keywords": [
"skillkit",
"api",
"rest",
"skills",
"discovery",
"ai",
"agents"
]
}
+27
View File
@@ -0,0 +1,27 @@
import { describe, it, expect } from 'vitest';
import { createApp } from '../server.js';
describe('Health Routes', () => {
const { app } = createApp({ skills: [{ name: 'test', source: 'a/b' }], rateLimitMax: 1000 });
it('GET /health returns status ok', async () => {
const res = await app.request('/health');
expect(res.status).toBe(200);
const body = await res.json();
expect(body.status).toBe('ok');
expect(body.skillCount).toBe(1);
expect(typeof body.uptime).toBe('number');
expect(body.version).toBeDefined();
});
it('GET /cache/stats returns cache statistics', async () => {
const res = await app.request('/cache/stats');
expect(res.status).toBe(200);
const body = await res.json();
expect(typeof body.hits).toBe('number');
expect(typeof body.misses).toBe('number');
expect(typeof body.size).toBe('number');
expect(typeof body.maxSize).toBe('number');
expect(typeof body.hitRate).toBe('number');
});
});
+56
View File
@@ -0,0 +1,56 @@
import { describe, it, expect } from 'vitest';
import { createApp } from '../server.js';
const testSkills = [
{ name: 'react-perf', description: 'React performance tips', source: 'owner/repo', tags: ['react', 'performance'] },
{ name: 'testing-guide', description: 'Unit testing guide', source: 'owner/repo2', tags: ['testing'] },
{ name: 'nextjs-auth', description: 'Next.js authentication', source: 'other/repo', tags: ['nextjs', 'auth'], category: 'framework' },
];
describe('Search Routes', () => {
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
it('GET /search returns results for query', async () => {
const res = await app.request('/search?q=react');
expect(res.status).toBe(200);
const body = await res.json();
expect(body.query).toBe('react');
expect(body.skills.length).toBeGreaterThan(0);
expect(body.total).toBeGreaterThan(0);
});
it('GET /search returns 400 without query', async () => {
const res = await app.request('/search');
expect(res.status).toBe(400);
});
it('GET /search respects limit parameter', async () => {
const res = await app.request('/search?q=test&limit=1');
const body = await res.json();
expect(body.skills.length).toBeLessThanOrEqual(1);
expect(body.limit).toBe(1);
});
it('POST /search with filters', async () => {
const res = await app.request('/search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'auth',
filters: { tags: ['nextjs'] },
}),
});
expect(res.status).toBe(200);
const body = await res.json();
expect(body.skills.length).toBeGreaterThan(0);
});
it('POST /search returns 400 without query', async () => {
const res = await app.request('/search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
expect(res.status).toBe(400);
});
});
+53
View File
@@ -0,0 +1,53 @@
import { describe, it, expect } from 'vitest';
import { createApp } from '../server.js';
const testSkills = [
{ name: 'my-skill', description: 'A test skill', source: 'owner/repo' },
];
describe('Skill Routes', () => {
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
it('GET /skills/:source/:id returns a skill', async () => {
const res = await app.request('/skills/owner/repo/my-skill');
expect(res.status).toBe(200);
const body = await res.json();
expect(body.name).toBe('my-skill');
expect(body.source).toBe('owner/repo');
});
it('GET /skills/:owner/:repo/:id returns 404 for missing skill', async () => {
const res = await app.request('/skills/owner/repo/nonexistent');
expect(res.status).toBe(404);
});
});
describe('Trending Routes', () => {
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
it('GET /trending returns skills', async () => {
const res = await app.request('/trending');
expect(res.status).toBe(200);
const body = await res.json();
expect(body.skills).toBeInstanceOf(Array);
expect(body.limit).toBeDefined();
});
});
describe('Category Routes', () => {
const skills = [
{ name: 'a', source: 'x/y', tags: ['react', 'ui'] },
{ name: 'b', source: 'x/z', tags: ['react'], category: 'framework' },
];
const { app } = createApp({ skills, rateLimitMax: 1000 });
it('GET /categories returns tag counts', async () => {
const res = await app.request('/categories');
expect(res.status).toBe(200);
const body = await res.json();
expect(body.categories).toBeInstanceOf(Array);
expect(body.total).toBeGreaterThan(0);
const react = body.categories.find((c: { name: string }) => c.name === 'react');
expect(react?.count).toBe(2);
});
});
+11
View File
@@ -0,0 +1,11 @@
export { createApp, startServer } from './server.js';
export type { ServerOptions } from './server.js';
export type {
ApiSkill,
SearchResponse,
HealthResponse,
CacheStatsResponse,
TrendingResponse,
CategoriesResponse,
CategoryCount,
} from './types.js';
+43
View File
@@ -0,0 +1,43 @@
import type { Context, Next } from 'hono';
interface RateLimitEntry {
count: number;
resetAt: number;
}
export function rateLimiter(maxRequests = 60, windowMs = 60_000) {
const windows = new Map<string, RateLimitEntry>();
setInterval(() => {
const now = Date.now();
for (const [key, entry] of windows) {
if (now > entry.resetAt) {
windows.delete(key);
}
}
}, windowMs).unref();
return async (c: Context, next: Next): Promise<Response | void> => {
const forwardedFor = c.req.header('x-forwarded-for');
const ip = (forwardedFor?.split(',')[0]?.trim()) || c.req.header('x-real-ip') || 'unknown';
const now = Date.now();
let entry = windows.get(ip);
if (!entry || now > entry.resetAt) {
entry = { count: 0, resetAt: now + windowMs };
windows.set(ip, entry);
}
entry.count++;
c.header('X-RateLimit-Limit', String(maxRequests));
c.header('X-RateLimit-Remaining', String(Math.max(0, maxRequests - entry.count)));
c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
if (entry.count > maxRequests) {
return c.json({ error: 'Too many requests', retryAfter: Math.ceil((entry.resetAt - now) / 1000) }, 429);
}
await next();
};
}
+34
View File
@@ -0,0 +1,34 @@
import { Hono } from 'hono';
import type { ApiSkill, CategoriesResponse } from '../types.js';
export function categoryRoutes(skills: ApiSkill[]) {
const app = new Hono();
app.get('/categories', (c) => {
const tagCounts = new Map<string, number>();
for (const skill of skills) {
if (skill.tags) {
for (const tag of skill.tags) {
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
}
}
if (skill.category) {
const key = `category:${skill.category}`;
tagCounts.set(key, (tagCounts.get(key) || 0) + 1);
}
}
const categories = Array.from(tagCounts.entries())
.map(([name, count]) => ({ name, count }))
.sort((a, b) => b.count - a.count);
const response: CategoriesResponse = {
categories,
total: categories.length,
};
return c.json(response);
});
return app;
}
+33
View File
@@ -0,0 +1,33 @@
import { Hono } from 'hono';
import type { HealthResponse, CacheStatsResponse } from '../types.js';
import type { CacheBackend } from '@skillkit/core';
const startTime = Date.now();
export function healthRoutes(skillCount: number, cache: CacheBackend) {
const app = new Hono();
app.get('/health', (c) => {
const response: HealthResponse = {
status: 'ok',
version: '1.11.0',
skillCount,
uptime: Math.floor((Date.now() - startTime) / 1000),
};
return c.json(response);
});
app.get('/cache/stats', (c) => {
const stats = cache.stats();
const response: CacheStatsResponse = {
hits: stats.hits,
misses: stats.misses,
size: stats.size,
maxSize: stats.maxSize,
hitRate: stats.hitRate,
};
return c.json(response);
});
return app;
}
+128
View File
@@ -0,0 +1,128 @@
import { Hono } from 'hono';
import type { ApiSkill, SearchResponse } from '../types.js';
import { RelevanceRanker } from '@skillkit/core';
import type { MemoryCache } from '@skillkit/core';
export function searchRoutes(skills: ApiSkill[], cache: MemoryCache<SearchResponse>) {
const app = new Hono();
const ranker = new RelevanceRanker();
app.get('/search', (c) => {
const query = c.req.query('q') || '';
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
const includeContent = c.req.query('include_content') === 'true';
if (!query) {
return c.json({ error: 'Query parameter "q" is required' }, 400);
}
const cacheKey = `search:${query}:${limit}:${includeContent}`;
const cached = cache.get(cacheKey);
if (cached) return c.json(cached);
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
const ranked = ranker.rank(
skills.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
stars: s.stars,
installs: s.installs,
source: s.source,
})),
query,
);
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
if (!includeContent) {
const { content: _, ...rest } = original;
return rest;
}
return original;
});
const response: SearchResponse = {
skills: results,
total: ranked.length,
query,
limit,
};
cache.set(cacheKey, response);
return c.json(response);
});
app.post('/search', async (c) => {
let body: {
query: string;
limit?: number;
include_content?: boolean;
filters?: { tags?: string[]; category?: string; source?: string };
};
try {
body = await c.req.json();
} catch {
return c.json({ error: 'Invalid JSON body' }, 400);
}
if (!body.query) {
return c.json({ error: 'Field "query" is required' }, 400);
}
const limit = Math.min(body.limit ?? 20, 100);
let filtered = skills;
if (body.filters) {
if (body.filters.tags?.length) {
filtered = filtered.filter((s) =>
body.filters!.tags!.some((t) => s.tags?.includes(t)),
);
}
if (body.filters.category) {
filtered = filtered.filter((s) => s.category === body.filters!.category);
}
if (body.filters.source) {
filtered = filtered.filter((s) => s.source.includes(body.filters!.source!));
}
}
const filteredMap = new Map(filtered.map((s) => [`${s.source}:${s.name}`, s]));
const ranked = ranker.rank(
filtered.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
stars: s.stars,
installs: s.installs,
source: s.source,
})),
body.query,
);
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
const original = filteredMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!;
if (!body.include_content) {
const { content: _, ...rest } = original;
return rest;
}
return original;
});
const response: SearchResponse = {
skills: results,
total: ranked.length,
query: body.query,
limit,
};
return c.json(response);
});
return app;
}
+23
View File
@@ -0,0 +1,23 @@
import { Hono } from 'hono';
import type { ApiSkill } from '../types.js';
export function skillRoutes(skills: ApiSkill[]) {
const app = new Hono();
app.get('/skills/:owner/:repo/:id', (c) => {
const source = `${c.req.param('owner')}/${c.req.param('repo')}`;
const id = c.req.param('id');
const skill = skills.find(
(s) => s.source === source && s.name === id,
);
if (!skill) {
return c.json({ error: `Skill not found: ${source}/${id}` }, 404);
}
return c.json(skill);
});
return app;
}
+39
View File
@@ -0,0 +1,39 @@
import { Hono } from 'hono';
import type { ApiSkill, TrendingResponse } from '../types.js';
import { RelevanceRanker } from '@skillkit/core';
export function trendingRoutes(skills: ApiSkill[]) {
const app = new Hono();
const ranker = new RelevanceRanker();
app.get('/trending', (c) => {
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
const ranked = ranker.rank(
skills.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
stars: s.stars,
installs: s.installs,
references: [],
source: s.source,
})),
);
const results = ranked.slice(0, limit).map((r) => {
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
const { content: _, ...rest } = original;
return rest;
});
const response: TrendingResponse = { skills: results, limit };
return c.json(response);
});
return app;
}
+55
View File
@@ -0,0 +1,55 @@
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { MemoryCache } from '@skillkit/core';
import { rateLimiter } from './middleware/rate-limit.js';
import { healthRoutes } from './routes/health.js';
import { searchRoutes } from './routes/search.js';
import { skillRoutes } from './routes/skills.js';
import { trendingRoutes } from './routes/trending.js';
import { categoryRoutes } from './routes/categories.js';
import type { ApiSkill, SearchResponse } from './types.js';
export interface ServerOptions {
port?: number;
host?: string;
corsOrigin?: string;
cacheTtlMs?: number;
skills?: ApiSkill[];
rateLimitMax?: number;
}
export function createApp(options: ServerOptions = {}) {
const skills = options.skills || [];
const cache = new MemoryCache<SearchResponse>({
maxSize: 500,
ttlMs: options.cacheTtlMs ?? 86_400_000,
});
const app = new Hono();
app.use('*', cors({ origin: options.corsOrigin || '*' }));
app.use('*', rateLimiter(options.rateLimitMax ?? 60));
app.route('/', healthRoutes(skills.length, cache));
app.route('/', searchRoutes(skills, cache));
app.route('/', skillRoutes(skills));
app.route('/', trendingRoutes(skills));
app.route('/', categoryRoutes(skills));
return { app, cache };
}
export async function startServer(options: ServerOptions = {}) {
const port = options.port ?? 3737;
const host = options.host ?? '0.0.0.0';
const { app, cache } = createApp(options);
const { serve } = await import('@hono/node-server');
const server = serve({ fetch: app.fetch, port, hostname: host }, () => {
console.log(`SkillKit API server running at http://${host}:${port}`);
console.log(`Skills loaded: ${options.skills?.length ?? 0}`);
});
return { server, app, cache };
}
+48
View File
@@ -0,0 +1,48 @@
export interface ApiSkill {
name: string;
description?: string;
source: string;
repo?: string;
tags?: string[];
category?: string;
content?: string;
stars?: number;
installs?: number;
}
export interface SearchResponse {
skills: ApiSkill[];
total: number;
query: string;
limit: number;
}
export interface HealthResponse {
status: 'ok';
version: string;
skillCount: number;
uptime: number;
}
export interface CacheStatsResponse {
hits: number;
misses: number;
size: number;
maxSize: number;
hitRate: number;
}
export interface TrendingResponse {
skills: ApiSkill[];
limit: number;
}
export interface CategoryCount {
name: string;
count: number;
}
export interface CategoriesResponse {
categories: CategoryCount[];
total: number;
}
+10
View File
@@ -0,0 +1,10 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"composite": false
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
+17
View File
@@ -0,0 +1,17 @@
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm'],
target: 'node18',
outDir: 'dist',
clean: true,
dts: true,
sourcemap: true,
splitting: false,
skipNodeModulesBundle: true,
platform: 'node',
banner: {
js: '#!/usr/bin/env node',
},
});
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/cli",
"version": "1.9.0",
"version": "1.12.0",
"description": "CLI commands for SkillKit",
"type": "module",
"main": "./dist/index.js",
@@ -22,6 +22,7 @@
},
"dependencies": {
"@clack/prompts": "^0.11.0",
"@skillkit/api": "workspace:*",
"@skillkit/core": "workspace:*",
"@skillkit/agents": "workspace:*",
"@skillkit/resources": "workspace:*",
@@ -0,0 +1,69 @@
import { describe, it, expect } from 'vitest';
import { join, normalize, resolve, sep } from 'node:path';
function isPathInside(child: string, parent: string): boolean {
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}
function sanitizeName(name: string): string {
return name.split(/[/\\]/).pop() || name;
}
describe('Quick Command Security', () => {
describe('path traversal protection', () => {
const installDir = '/home/user/.claude/skills';
it('should block skill names that escape the install directory', () => {
const maliciousNames = ['../evil', '../../etc/passwd', '../../../tmp/bad', '..\\evil'];
for (const name of maliciousNames) {
const sanitized = sanitizeName(name);
const targetPath = normalize(join(installDir, sanitized));
expect(isPathInside(targetPath, installDir)).toBe(true);
expect(sanitized).not.toContain('..');
expect(sanitized).not.toContain('/');
expect(sanitized).not.toContain('\\');
}
});
it('should sanitize "../evil" to "evil"', () => {
expect(sanitizeName('../evil')).toBe('evil');
});
it('should sanitize "../../etc/passwd" to "passwd"', () => {
expect(sanitizeName('../../etc/passwd')).toBe('passwd');
});
it('should sanitize "..\\evil" to "evil"', () => {
expect(sanitizeName('..\\evil')).toBe('evil');
});
it('should keep valid skill names unchanged', () => {
expect(sanitizeName('my-skill')).toBe('my-skill');
expect(sanitizeName('react-best-practices')).toBe('react-best-practices');
});
it('should produce a path inside installDir after sanitization', () => {
const evilName = '../evil';
const sanitized = sanitizeName(evilName);
const targetPath = normalize(join(installDir, sanitized));
expect(isPathInside(targetPath, installDir)).toBe(true);
expect(targetPath).toBe(join(installDir, 'evil'));
});
it('should detect unsanitized traversal names before normalization', () => {
const rawPath = `${installDir}/../evil`;
expect(isPathInside(rawPath, installDir)).toBe(false);
});
it('should ensure sanitization prevents the traversal entirely', () => {
const evilName = '../evil';
const sanitized = sanitizeName(evilName);
const targetPath = normalize(join(installDir, sanitized));
expect(targetPath).toBe(join(installDir, 'evil'));
expect(targetPath.startsWith(installDir)).toBe(true);
});
});
});
+39
View File
@@ -0,0 +1,39 @@
const SKILLKIT_LOGO_SVG_BASE64 =
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
function encodeBadgeSegment(text: string): string {
return encodeURIComponent(text).replace(/-/g, '--');
}
export function generateBadge(skills: string[]): {
url: string;
markdown: string;
html: string;
} {
const count = skills.length;
if (count === 0) {
const url = `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
const maxDisplay = 5;
const displayNames = skills.slice(0, maxDisplay);
const suffix = count > maxDisplay ? ` +${count - maxDisplay} more` : '';
const label = `SkillKit ${count} skills`;
const message = displayNames.join(' | ') + suffix;
const encodedLabel = encodeBadgeSegment(label);
const encodedMessage = encodeBadgeSegment(message);
const url = `https://img.shields.io/badge/${encodedLabel}-${encodedMessage}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
+41 -2
View File
@@ -8,6 +8,7 @@ import {
select,
header,
} from '../onboarding/index.js';
import { FederatedSearch, GitHubSkillRegistry, RateLimitError } from '@skillkit/core';
interface SkillResult {
name: string;
@@ -54,6 +55,10 @@ export class FindCommand extends Command {
description: 'Minimal output (just list skills)',
});
federated = Option.Boolean('--federated,-f', false, {
description: 'Search external registries (GitHub SKILL.md files)',
});
async execute(): Promise<number> {
const s = spinner();
const limit = parseInt(this.limit, 10) || 10;
@@ -128,12 +133,46 @@ export class FindCommand extends Command {
}
}
if (this.federated && this.query) {
s.start('Searching external registries...');
const fedSearch = new FederatedSearch();
fedSearch.addRegistry(new GitHubSkillRegistry());
try {
const fedResult = await fedSearch.search(this.query, { limit: parseInt(this.limit, 10) || 10 });
s.stop(`Found ${fedResult.total} external skill(s) from ${fedResult.registries.join(', ') || 'none'}`);
if (fedResult.skills.length > 0) {
console.log('');
console.log(colors.bold('External Skills (SKILL.md):'));
for (const skill of fedResult.skills) {
const stars = typeof skill.stars === 'number' ? colors.muted(` ★${skill.stars}`) : '';
const desc = skill.description
? colors.muted(` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? '...' : ''}`)
: '';
console.log(` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${stars}${desc}`);
if (!this.quiet) {
console.log(` ${colors.muted(skill.source)}`);
}
}
console.log('');
}
} catch (err) {
if (err instanceof RateLimitError) {
s.stop(colors.warning('Rate limited by GitHub API'));
console.log(colors.muted('Set GITHUB_TOKEN env var or wait before retrying.'));
} else {
s.stop(colors.warning('Federated search failed'));
}
}
}
if (results.length === 0) {
console.log(colors.muted('No skills found matching your search'));
console.log('');
console.log(colors.muted('Try:'));
console.log(colors.muted(' skillkit find --top # Show featured skills'));
console.log(colors.muted(' skillkit ui # Browse in TUI'));
console.log(colors.muted(' skillkit find --top # Show featured skills'));
console.log(colors.muted(' skillkit find -f <query> # Search external registries'));
console.log(colors.muted(' skillkit ui # Browse in TUI'));
return 0;
}
+9
View File
@@ -108,3 +108,12 @@ export {
// Tree command for hierarchical skill browsing (Phase 21)
export { TreeCommand } from './tree.js';
// Quick setup (zero-friction entry)
export { QuickCommand } from './quick.js';
// SKILL.md ecosystem
export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from './skillmd.js';
// API server
export { ServeCommand } from './serve.js';
+375
View File
@@ -0,0 +1,375 @@
import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync } from 'node:fs';
import { join, resolve, normalize } from 'node:path';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
import { Command } from 'clipanion';
import {
type ProjectProfile,
type SkillMetadata,
type AgentType,
ContextManager,
RecommendationEngine,
loadIndex as loadIndexFromCache,
isIndexStale,
buildSkillIndex,
saveIndex,
KNOWN_SKILL_REPOS,
isPathInside,
isLocalPath,
detectProvider,
} from '@skillkit/core';
import { getAdapter, detectAgent, getAllAdapters } from '@skillkit/agents';
import { getInstallDir, saveSkillMetadata } from '../helpers.js';
import {
welcome,
spinner,
step,
success,
error,
warn,
colors,
symbols,
confirm,
select,
outro,
formatAgent,
getAgentIcon,
isCancel,
cancel,
showProjectSummary,
progressBar,
formatQualityBadge,
saveLastAgents,
} from '../onboarding/index.js';
function truncate(str: string, maxLen: number): string {
if (str.length <= maxLen) return str;
return str.slice(0, maxLen - 3) + '...';
}
export class QuickCommand extends Command {
static override paths = [['quick']];
static override usage = Command.Usage({
description: 'Zero-friction skill setup: detect agents, analyze project, recommend and install',
examples: [
['Quick setup', '$0 quick'],
],
});
async execute(): Promise<number> {
const s = spinner();
try {
welcome();
step(`${colors.bold('Quick Setup')} - zero-friction skill installation`);
console.log('');
s.start('Detecting installed AI agents...');
const allAdapters = getAllAdapters();
const detectedAgents: AgentType[] = [];
for (const adapter of allAdapters) {
try {
const installDir = getInstallDir(false, adapter.type);
const globalDir = getInstallDir(true, adapter.type);
if (existsSync(installDir) || existsSync(globalDir) || existsSync(adapter.configFile)) {
detectedAgents.push(adapter.type);
}
} catch {
// skip
}
}
if (detectedAgents.length === 0) {
const fallback = await detectAgent();
detectedAgents.push(fallback);
}
s.stop(`Detected ${detectedAgents.length} agent${detectedAgents.length !== 1 ? 's' : ''}: ${detectedAgents.map(formatAgent).join(', ')}`);
s.start('Analyzing project...');
const targetPath = resolve(process.cwd());
const manager = new ContextManager(targetPath);
let context = manager.get();
if (!context) {
context = manager.init();
}
s.stop('Project analyzed');
if (!context) {
error('Failed to analyze project');
return 1;
}
const profile: ProjectProfile = {
name: context.project.name,
type: context.project.type,
stack: context.stack,
patterns: context.patterns,
installedSkills: context.skills?.installed || [],
excludedSkills: context.skills?.excluded || [],
};
const languages = profile.stack.languages.map((l: { name: string; version?: string }) => `${l.name}${l.version ? ` ${l.version}` : ''}`);
const frameworks = profile.stack.frameworks.map((f: { name: string; version?: string }) => `${f.name}${f.version ? ` ${f.version}` : ''}`);
showProjectSummary({
name: profile.name,
type: profile.type,
languages,
frameworks,
});
let index = loadIndexFromCache();
if (!index || index.skills.length === 0) {
s.start('Building skill index from known sources...');
try {
const result = await buildSkillIndex(KNOWN_SKILL_REPOS, (message: string) => {
s.message(message);
});
index = result.index;
saveIndex(index);
s.stop(`Indexed ${index.skills.length} skills`);
} catch {
s.stop(colors.error('Failed to build index'));
warn('Could not fetch skill index. Try running: skillkit recommend --update');
return 1;
}
} else if (isIndexStale(index)) {
step(colors.muted('Skill index is stale. Run "skillkit recommend --update" to refresh.'));
}
const engine = new RecommendationEngine();
engine.loadIndex(index);
const result = engine.recommend(profile, {
limit: 5,
minScore: 20,
excludeInstalled: true,
includeReasons: true,
});
const recommendations = result.recommendations;
if (recommendations.length === 0) {
warn('No matching skills found for your project.');
console.log(colors.muted('Try running: skillkit recommend --update'));
return 0;
}
console.log('');
console.log(colors.bold(`Top ${recommendations.length} Recommended Skills:`));
console.log('');
const options: Array<{ value: string; label: string; hint?: string }> = [];
for (let i = 0; i < recommendations.length; i++) {
const rec = recommendations[i];
let scoreColor: (text: string) => string;
if (rec.score >= 70) {
scoreColor = colors.success;
} else if (rec.score >= 50) {
scoreColor = colors.warning;
} else {
scoreColor = colors.muted;
}
const scoreBar = progressBar(rec.score, 100, 10);
const qualityScore = rec.skill.quality ?? null;
const qualityDisplay = typeof qualityScore === 'number' && Number.isFinite(qualityScore)
? ` ${formatQualityBadge(qualityScore)}`
: '';
console.log(` ${colors.bold(`${i + 1}.`)} ${scoreColor(`${rec.score}%`)} ${colors.dim(scoreBar)} ${colors.bold(rec.skill.name)}${qualityDisplay}`);
if (rec.skill.description) {
console.log(` ${colors.muted(truncate(rec.skill.description, 70))}`);
}
options.push({
value: `${i}`,
label: `${rec.skill.name} (${rec.score}% match)`,
hint: rec.skill.source || undefined,
});
}
console.log('');
const skipOption = { value: 'skip', label: 'Skip installation' };
const selectResult = await select({
message: 'Select a skill to install',
options: [...options, skipOption],
});
if (isCancel(selectResult) || selectResult === 'skip') {
cancel('Quick setup complete (no installation)');
return 0;
}
const selectedIndex = parseInt(selectResult as string, 10);
const selectedSkill = recommendations[selectedIndex];
if (!selectedSkill || !selectedSkill.skill.source) {
error('Selected skill has no installable source');
return 1;
}
const agentDisplay = detectedAgents.length <= 3
? detectedAgents.map(formatAgent).join(', ')
: `${detectedAgents.slice(0, 2).map(formatAgent).join(', ')} +${detectedAgents.length - 2} more`;
const confirmResult = await confirm({
message: `Install ${colors.bold(selectedSkill.skill.name)} to ${agentDisplay}?`,
initialValue: true,
});
if (isCancel(confirmResult) || !confirmResult) {
cancel('Installation cancelled');
return 0;
}
saveLastAgents(detectedAgents);
const providerAdapter = detectProvider(selectedSkill.skill.source);
if (!providerAdapter) {
error(`Could not detect provider for: ${selectedSkill.skill.source}`);
return 1;
}
s.start(`Fetching ${selectedSkill.skill.name}...`);
const cloneResult = await providerAdapter.clone(selectedSkill.skill.source, '', { depth: 1 });
if (!cloneResult.success || !cloneResult.path) {
s.stop(colors.error(cloneResult.error || 'Failed to fetch source'));
return 1;
}
const discoveredSkills = cloneResult.discoveredSkills || [];
const matchedSkill = discoveredSkills.find(ds => ds.name === selectedSkill.skill.name) || discoveredSkills[0];
if (!matchedSkill) {
s.stop(colors.error('Skill not found in repository'));
return 1;
}
s.stop(`Found ${selectedSkill.skill.name}`);
let primaryPath: string | null = null;
const installedAgents: string[] = [];
for (const agentType of detectedAgents) {
const adapter = getAdapter(agentType);
const installDir = getInstallDir(false, agentType);
if (!existsSync(installDir)) {
mkdirSync(installDir, { recursive: true });
}
const sanitizedName = matchedSkill.name.split(/[/\\]/).pop() || matchedSkill.name;
const targetInstallPath = normalize(join(installDir, sanitizedName));
if (!isPathInside(targetInstallPath, installDir)) {
error(`Skipping ${matchedSkill.name} for ${adapter.name} (install path escapes target directory)`);
continue;
}
const securityRoot = cloneResult.tempRoot || cloneResult.path;
if (!isPathInside(matchedSkill.path, securityRoot)) {
error(`Skipping ${matchedSkill.name} for ${adapter.name} (path traversal detected)`);
continue;
}
const useSymlink = detectedAgents.length > 1 && primaryPath !== null;
s.start(`Installing to ${adapter.name}${useSymlink ? ' (symlink)' : ''}...`);
try {
if (existsSync(targetInstallPath)) {
rmSync(targetInstallPath, { recursive: true, force: true });
}
if (useSymlink && primaryPath) {
symlinkSync(primaryPath, targetInstallPath, 'dir');
} else {
cpSync(matchedSkill.path, targetInstallPath, { recursive: true, dereference: true });
if (detectedAgents.length > 1 && primaryPath === null) {
primaryPath = targetInstallPath;
}
const packageJsonPath = join(targetInstallPath, 'package.json');
if (existsSync(packageJsonPath)) {
s.stop(`Installed to ${adapter.name}`);
s.start('Installing npm dependencies...');
try {
await execFileAsync('npm', ['install', '--production'], { cwd: targetInstallPath });
s.stop('Dependencies installed');
} catch {
s.stop(colors.warning('Dependencies failed'));
console.log(colors.muted('Run manually: npm install in ' + targetInstallPath));
}
s.start('Finishing installation...');
}
}
const metadata: SkillMetadata = {
name: matchedSkill.name,
description: selectedSkill.skill.description || '',
source: selectedSkill.skill.source,
sourceType: providerAdapter.type,
subpath: matchedSkill.name,
installedAt: new Date().toISOString(),
enabled: true,
};
saveSkillMetadata(targetInstallPath, metadata);
installedAgents.push(agentType);
s.stop(`Installed to ${adapter.name}${useSymlink ? ' (symlink)' : ''}`);
} catch (err) {
s.stop(colors.error(`Failed to install to ${adapter.name}`));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
}
}
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
if (!isLocalPath(selectedSkill.skill.source) && cleanupPath && existsSync(cleanupPath)) {
rmSync(cleanupPath, { recursive: true, force: true });
}
if (installedAgents.length > 0) {
console.log('');
success(`Installed ${colors.bold(matchedSkill.name)} to ${installedAgents.length} agent${installedAgents.length !== 1 ? 's' : ''}`);
for (const a of installedAgents) {
console.log(colors.muted(` ${symbols.success} ${getAgentIcon(a)} ${formatAgent(a)}`));
}
console.log('');
const badgeUrl = `https://img.shields.io/badge/SkillKit-${encodeURIComponent(matchedSkill.name)}-black?style=flat-square`;
console.log(colors.dim('Add to your README:'));
console.log(colors.muted(` [![SkillKit](${badgeUrl})](https://agenstskills.com)`));
outro('Quick setup complete!');
console.log('');
console.log(colors.muted('Next steps:'));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit sync')} to update agent configs`));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit recommend')} for more suggestions`));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit list')} to see installed skills`));
console.log('');
} else {
warn('No agents were installed');
}
return 0;
} catch (err) {
s.stop(colors.error('Quick setup failed'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
return 1;
}
}
}
+162
View File
@@ -52,6 +52,9 @@ export class RecommendCommand extends Command {
['Update skill index', '$0 recommend --update'],
['Search for skills by task', '$0 recommend --task "authentication"'],
['Search for skills (alias)', '$0 recommend --search "testing"'],
['Hybrid search (vector + keyword)', '$0 recommend --search "auth" --hybrid'],
['Hybrid search with query expansion', '$0 recommend --search "auth" --hybrid --expand'],
['Build hybrid search index', '$0 recommend --build-index'],
],
});
@@ -125,6 +128,26 @@ export class RecommendCommand extends Command {
description: 'Show category path for each recommendation',
});
// Hybrid search mode
hybrid = Option.Boolean('--hybrid,-H', false, {
description: 'Use hybrid search (vector + keyword)',
});
// Query expansion
expand = Option.Boolean('--expand,-x', false, {
description: 'Enable query expansion (requires --hybrid)',
});
// Reranking
rerank = Option.Boolean('--rerank', false, {
description: 'Enable LLM reranking (requires --hybrid)',
});
// Build index
buildIndex = Option.Boolean('--build-index', false, {
description: 'Build/rebuild the hybrid search embedding index',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
@@ -133,6 +156,16 @@ export class RecommendCommand extends Command {
return await this.updateIndex();
}
// Handle hybrid index building
if (this.buildIndex) {
return await this.buildHybridIndex();
}
// Validate hybrid-dependent options
if ((this.expand || this.rerank) && !this.hybrid) {
warn('--expand and --rerank require --hybrid flag. These options will be ignored.');
}
if (!this.quiet && !this.json) {
header('Skill Recommendations');
}
@@ -168,6 +201,9 @@ export class RecommendCommand extends Command {
// Handle search mode (--search or --task)
const searchQuery = this.search || this.task;
if (searchQuery) {
if (this.hybrid) {
return await this.handleHybridSearch(engine, searchQuery);
}
return this.handleSearch(engine, searchQuery);
}
@@ -446,6 +482,132 @@ export class RecommendCommand extends Command {
console.log(colors.muted('More details: skillkit recommend --explain --verbose'));
}
private async handleHybridSearch(engine: RecommendationEngine, query: string): Promise<number> {
if (!this.quiet && !this.json) {
header(`Hybrid Search: "${query}"`);
}
const s = !this.quiet && !this.json ? spinner() : null;
s?.start('Initializing hybrid search...');
try {
await engine.initHybridSearch();
s?.message('Searching...');
const results = await engine.hybridSearch({
query,
limit: this.limit ? parseInt(this.limit, 10) : 10,
hybrid: true,
enableExpansion: this.expand,
enableReranking: this.rerank,
filters: {
minScore: this.minScore ? parseInt(this.minScore, 10) : undefined,
},
});
s?.stop(`Found ${results.length} results`);
if (this.json) {
console.log(JSON.stringify(results, null, 2));
return 0;
}
if (results.length === 0) {
warn(`No skills found matching "${query}"`);
return 0;
}
console.log('');
console.log(colors.bold(`Hybrid search results for "${query}" (${results.length} found):`));
if (this.expand && results[0]?.expandedTerms?.length) {
console.log(colors.muted(` Expanded: ${results[0].expandedTerms.join(', ')}`));
}
console.log('');
for (const result of results) {
let relevanceColor: (text: string) => string;
if (result.relevance >= 70) {
relevanceColor = colors.success;
} else if (result.relevance >= 50) {
relevanceColor = colors.warning;
} else {
relevanceColor = colors.muted;
}
const relevanceBar = progressBar(result.relevance, 100, 10);
console.log(` ${relevanceColor(`${result.relevance}%`)} ${colors.dim(relevanceBar)} ${colors.bold(result.skill.name)}`);
if (result.skill.description) {
console.log(` ${colors.muted(truncate(result.skill.description, 70))}`);
}
if (this.verbose) {
const scores: string[] = [];
if (typeof result.vectorSimilarity === 'number') {
scores.push(`vector: ${(result.vectorSimilarity * 100).toFixed(0)}%`);
}
if (typeof result.keywordScore === 'number') {
scores.push(`keyword: ${result.keywordScore.toFixed(0)}%`);
}
if (typeof result.rrfScore === 'number') {
scores.push(`rrf: ${result.rrfScore.toFixed(3)}`);
}
if (scores.length > 0) {
console.log(` ${colors.dim('Scores:')} ${scores.join(' | ')}`);
}
}
if (result.matchedTerms.length > 0) {
console.log(` ${colors.dim('Matched:')} ${result.matchedTerms.join(', ')}`);
}
console.log('');
}
return 0;
} catch (err) {
s?.stop(colors.error('Hybrid search failed'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
console.log(colors.muted('Falling back to standard search...'));
return this.handleSearch(engine, query);
}
}
private async buildHybridIndex(): Promise<number> {
if (!this.quiet) {
header('Build Hybrid Search Index');
}
const index = this.loadIndex();
if (!index || index.skills.length === 0) {
warn('No skill index found. Run --update first.');
return 1;
}
const s = spinner();
s.start('Initializing...');
try {
const engine = new RecommendationEngine();
engine.loadIndex(index);
await engine.buildHybridIndex((progress) => {
const percentage = Math.round((progress.current / progress.total) * 100);
s.message(`${progress.phase}: ${progress.message || ''} (${percentage}%)`);
});
s.stop(colors.success(`${symbols.success} Built hybrid index for ${index.skills.length} skills`));
console.log(colors.muted(' Index stored in: ~/.skillkit/search.db'));
console.log(colors.muted(' Use --hybrid flag for vector+keyword search\n'));
return 0;
} catch (err) {
s.stop(colors.error('Failed to build hybrid index'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
return 1;
}
}
private handleSearch(engine: RecommendationEngine, query: string): number {
if (!this.quiet && !this.json) {
header(`Search: "${query}"`);
+93
View File
@@ -0,0 +1,93 @@
import { Command, Option } from 'clipanion';
import {
colors,
header,
step,
} from '../onboarding/index.js';
import skillsData from '../../../../marketplace/skills.json' with { type: 'json' };
export class ServeCommand extends Command {
static override paths = [['serve'], ['server']];
static override usage = Command.Usage({
description: 'Start the SkillKit REST API server for skill discovery',
details: `
Launches a local HTTP server that exposes the SkillKit skill catalog
via a REST API. Useful for integrating with other tools, building
custom UIs, or enabling agent-native skill discovery.
`,
examples: [
['Start server on default port', '$0 serve'],
['Start on custom port', '$0 serve --port 8080'],
['Start with custom CORS', '$0 serve --cors "http://localhost:3000"'],
],
});
port = Option.String('--port,-p', '3737', {
description: 'Port to listen on',
});
host = Option.String('--host,-H', '0.0.0.0', {
description: 'Host to bind to',
});
corsOrigin = Option.String('--cors', '*', {
description: 'CORS allowed origin',
});
cacheTtl = Option.String('--cache-ttl', '86400000', {
description: 'Cache TTL in milliseconds',
});
async execute(): Promise<number> {
header('SkillKit API Server');
const skills = (skillsData.skills || []).map((skill: Record<string, unknown>) => ({
name: skill.name as string,
description: skill.description as string | undefined,
source: (skill.source as string) || '',
repo: skill.repo as string | undefined,
tags: skill.tags as string[] | undefined,
category: skill.category as string | undefined,
}));
step(`Loading ${skills.length} skills from marketplace`);
const portNum = parseInt(this.port, 10) || 3737;
const cacheTtlMs = parseInt(this.cacheTtl, 10) || 86_400_000;
try {
const { startServer } = await import('@skillkit/api');
await startServer({
port: portNum,
host: this.host,
corsOrigin: this.corsOrigin,
cacheTtlMs,
skills,
});
step(`Server running at ${colors.cyan(`http://${this.host}:${portNum}`)}`);
console.log('');
console.log(colors.muted('Endpoints:'));
console.log(colors.muted(` GET /health - Server health check`));
console.log(colors.muted(` GET /search?q=... - Search skills`));
console.log(colors.muted(` POST /search - Search with filters`));
console.log(colors.muted(` GET /skills/:o/:r/:id - Get specific skill`));
console.log(colors.muted(` GET /trending - Top skills`));
console.log(colors.muted(` GET /categories - Skill categories`));
console.log(colors.muted(` GET /cache/stats - Cache statistics`));
console.log('');
console.log(colors.muted('Press Ctrl+C to stop'));
await new Promise(() => {});
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
console.error(colors.error(`Failed to start server: ${message}`));
return 1;
}
return 0;
}
}
+440
View File
@@ -0,0 +1,440 @@
import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
import { join, resolve, basename, relative } from 'node:path';
import { Command, Option } from 'clipanion';
import {
colors,
symbols,
spinner,
step,
success,
error,
warn,
header,
} from '../onboarding/index.js';
interface SkillMdValidation {
path: string;
exists: boolean;
hasName: boolean;
hasDescription: boolean;
hasTriggers: boolean;
hasCapabilities: boolean;
triggerCount: number;
capabilityCount: number;
score: number;
issues: string[];
}
function validateSkillMd(filePath: string): SkillMdValidation {
const result: SkillMdValidation = {
path: filePath,
exists: false,
hasName: false,
hasDescription: false,
hasTriggers: false,
hasCapabilities: false,
triggerCount: 0,
capabilityCount: 0,
score: 0,
issues: [],
};
if (!existsSync(filePath)) {
result.issues.push('File does not exist');
return result;
}
result.exists = true;
const content = readFileSync(filePath, 'utf-8');
if (!content.trim()) {
result.issues.push('File is empty');
return result;
}
const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
const bodyContent = frontmatterMatch
? content.slice(frontmatterMatch[0].length)
: content;
if (frontmatterMatch) {
const frontmatter = frontmatterMatch[1];
if (/^name:\s*.+$/m.test(frontmatter)) result.hasName = true;
if (/^description:\s*.+$/m.test(frontmatter)) result.hasDescription = true;
}
if (!result.hasName) {
if (/^#\s+.+$/m.test(bodyContent)) result.hasName = true;
}
if (!result.hasDescription) {
if (/^##?\s*(description|about|overview)\b/im.test(bodyContent)) {
result.hasDescription = true;
} else {
const lines = bodyContent.split(/\r?\n/).filter(l => l.trim());
const nonHeaderLines = lines.filter(l => !l.startsWith('#'));
if (nonHeaderLines.length >= 2) result.hasDescription = true;
}
}
const triggerPatterns = [
/triggers?\s*when/i,
/when\s*to\s*use/i,
/use\s*this\s*when/i,
/\*\*triggers?\b/i,
/^[-*]\s+.+(when|if|pattern|trigger)/im,
/glob:/i,
];
for (const pattern of triggerPatterns) {
if (pattern.test(content)) {
result.hasTriggers = true;
break;
}
}
if (result.hasTriggers) {
const triggerSection = content.match(/triggers?\s*when[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
result.triggerCount = triggerSection
? (triggerSection[1].match(/^[-*]\s+/gm) || []).length
: 1;
}
const capabilityPatterns = [
/capabilities?[:\s]/i,
/features?[:\s]/i,
/what\s*(it|this)\s*(does|can)/i,
/^##?\s*capabilities/im,
/^##?\s*features/im,
];
for (const pattern of capabilityPatterns) {
if (pattern.test(content)) {
result.hasCapabilities = true;
break;
}
}
if (result.hasCapabilities) {
const capSection = content.match(/(?:capabilities?|features?)[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
result.capabilityCount = capSection
? (capSection[1].match(/^[-*]\s+/gm) || []).length
: 1;
}
if (!result.hasName) result.issues.push('Missing name field');
if (!result.hasDescription) result.issues.push('Missing description section');
if (!result.hasTriggers) result.issues.push('No trigger patterns found');
if (!result.hasCapabilities) result.issues.push('No capabilities list found');
let score = 0;
if (result.exists) score += 10;
if (result.hasName) score += 20;
if (result.hasDescription) score += 25;
if (result.hasTriggers) score += 20;
if (result.hasCapabilities) score += 15;
if (result.triggerCount >= 3) score += 5;
if (result.capabilityCount >= 3) score += 5;
if (frontmatterMatch) {
const fm = frontmatterMatch[1];
if (/^version:/m.test(fm)) score += 3;
if (/^license:/m.test(fm)) score += 2;
if (/^tags:/m.test(fm)) score += 3;
if (/^metadata:/m.test(fm)) score += 2;
}
result.score = Math.min(100, score);
return result;
}
function printValidation(validation: SkillMdValidation, verbose = false): void {
const scoreColor = validation.score >= 80
? colors.success
: validation.score >= 60
? colors.warning
: colors.error;
console.log(` ${colors.muted('Score:')} ${scoreColor(`${validation.score}`)}/100`);
console.log(` ${validation.hasName ? colors.success(symbols.success) : colors.error(symbols.error)} Name field`);
console.log(` ${validation.hasDescription ? colors.success(symbols.success) : colors.error(symbols.error)} Description section`);
console.log(` ${validation.hasTriggers ? colors.success(symbols.success) : colors.error(symbols.error)} Trigger patterns${validation.triggerCount > 0 ? ` (${validation.triggerCount})` : ''}`);
console.log(` ${validation.hasCapabilities ? colors.success(symbols.success) : colors.error(symbols.error)} Capabilities list${validation.capabilityCount > 0 ? ` (${validation.capabilityCount})` : ''}`);
if (verbose && validation.issues.length > 0) {
console.log('');
console.log(` ${colors.warning('Issues:')}`);
for (const issue of validation.issues) {
console.log(` ${colors.warning(symbols.warning)} ${issue}`);
}
}
}
export class SkillMdValidateCommand extends Command {
static override paths = [['skillmd', 'validate'], ['skill-md', 'validate']];
static override usage = Command.Usage({
description: 'Validate a SKILL.md file against the standard',
examples: [
['Validate SKILL.md in current directory', '$0 skillmd validate'],
['Validate specific file', '$0 skillmd validate ./path/to/SKILL.md'],
],
});
targetPath = Option.String({ required: false, name: 'path' });
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed validation results',
});
json = Option.Boolean('--json', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const targetPath = this.targetPath || join(process.cwd(), 'SKILL.md');
const resolvedPath = resolve(targetPath);
const filePath = resolvedPath.endsWith('SKILL.md') ? resolvedPath : join(resolvedPath, 'SKILL.md');
if (!this.json) {
header('SKILL.md Validation');
step(`Validating: ${colors.cyan(filePath)}`);
console.log('');
}
const validation = validateSkillMd(filePath);
if (this.json) {
console.log(JSON.stringify(validation, null, 2));
return validation.score >= 60 ? 0 : 1;
}
console.log(colors.primary(basename(filePath)));
printValidation(validation, this.verbose);
console.log('');
if (validation.score >= 80) {
success(`SKILL.md is compliant (score: ${validation.score}/100)`);
} else if (validation.score >= 60) {
warn(`SKILL.md needs improvement (score: ${validation.score}/100)`);
} else {
error(`SKILL.md does not meet minimum standard (score: ${validation.score}/100)`);
}
return validation.score >= 60 ? 0 : 1;
}
}
export class SkillMdInitCommand extends Command {
static override paths = [['skillmd', 'init'], ['skill-md', 'init']];
static override usage = Command.Usage({
description: 'Create a template SKILL.md in the current directory',
examples: [
['Create SKILL.md template', '$0 skillmd init'],
['Create with custom name', '$0 skillmd init --name my-skill'],
],
});
name = Option.String('--name,-n', {
description: 'Skill name',
});
force = Option.Boolean('--force,-f', false, {
description: 'Overwrite existing SKILL.md',
});
async execute(): Promise<number> {
const outputPath = join(process.cwd(), 'SKILL.md');
if (existsSync(outputPath) && !this.force) {
warn('SKILL.md already exists');
console.log(colors.muted('Use --force to overwrite'));
return 1;
}
const skillName = this.name || basename(process.cwd());
const formattedName = skillName
.split('-')
.map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
const template = [
'---',
`name: ${skillName}`,
'description: What this skill does and when to use it',
'version: "1.0"',
'license: MIT',
'tags: [general]',
'metadata:',
' author: your-name',
'---',
'',
`# ${formattedName}`,
'',
'Brief description of what this skill provides to AI coding agents.',
'',
'## Triggers when:',
`- User asks about ${skillName} related tasks`,
`- Project contains ${skillName} configuration files`,
`- Code changes involve ${skillName} patterns`,
'',
'## Capabilities:',
`- Provides best practices for ${skillName}`,
'- Generates boilerplate code and configurations',
'- Validates existing implementations',
'- Suggests improvements and optimizations',
'',
'## Steps',
'1. First step the AI agent should take',
'2. Second step with specific instructions',
'3. Third step with expected outcome',
'',
'## Examples',
'',
'```',
'Example code or configuration here',
'```',
'',
].join('\n');
writeFileSync(outputPath, template);
success(`Created SKILL.md for "${skillName}"`);
console.log('');
console.log(colors.muted('Next steps:'));
console.log(` ${colors.cyan('1.')} Edit SKILL.md with your skill instructions`);
console.log(` ${colors.cyan('2.')} Run ${colors.cyan('skillkit skillmd validate')} to check compliance`);
console.log(` ${colors.cyan('3.')} Run ${colors.cyan('skillkit publish submit')} to share with the marketplace`);
return 0;
}
}
export class SkillMdCheckCommand extends Command {
static override paths = [['skillmd', 'check'], ['skill-md', 'check']];
static override usage = Command.Usage({
description: 'Check all SKILL.md files in the project for compliance',
examples: [
['Check current directory', '$0 skillmd check'],
['Check specific directory', '$0 skillmd check ./skills'],
],
});
targetPath = Option.String({ required: false, name: 'path' });
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed validation results',
});
async execute(): Promise<number> {
const targetPath = resolve(this.targetPath || process.cwd());
header('SKILL.md Compliance Check');
const s = spinner();
s.start('Scanning for SKILL.md files...');
const skillMdFiles = this.findSkillMdFiles(targetPath);
s.stop(`Found ${skillMdFiles.length} SKILL.md file(s)`);
if (skillMdFiles.length === 0) {
warn('No SKILL.md files found');
console.log(colors.muted(`Searched: ${targetPath}`));
console.log('');
console.log(colors.muted('Create one with:'));
console.log(` ${colors.cyan('skillkit skillmd init')}`);
return 0;
}
const validations: SkillMdValidation[] = skillMdFiles.map(f => validateSkillMd(f));
validations.sort((a, b) => b.score - a.score);
console.log('');
for (const validation of validations) {
const relativePath = relative(targetPath, validation.path);
const scoreColor = validation.score >= 80 ? colors.success : validation.score >= 60 ? colors.warning : colors.error;
console.log(`${scoreColor(symbols.bullet)} ${colors.primary(relativePath)} ${colors.muted(`(${validation.score}/100)`)}`);
if (this.verbose) {
printValidation(validation, true);
console.log('');
}
}
console.log('');
const passing = validations.filter(v => v.score >= 60).length;
const failing = validations.filter(v => v.score < 60).length;
const avgScore = Math.round(validations.reduce((sum, v) => sum + v.score, 0) / validations.length);
console.log(colors.muted('Summary:'));
console.log(` ${colors.muted('Total:')} ${validations.length}`);
console.log(` ${colors.success(symbols.success)} Passing (60+): ${passing}`);
if (failing > 0) {
console.log(` ${colors.error(symbols.error)} Failing: ${failing}`);
}
console.log(` ${colors.muted('Average score:')} ${avgScore}/100`);
console.log('');
if (failing > 0) {
error(`${failing} SKILL.md file(s) below minimum standard`);
return 1;
}
success('All SKILL.md files are compliant');
return 0;
}
private findSkillMdFiles(dir: string): string[] {
const results: string[] = [];
const directFile = join(dir, 'SKILL.md');
if (existsSync(directFile)) results.push(directFile);
const searchDirs = [
join(dir, 'skills'),
join(dir, '.claude', 'skills'),
join(dir, '.cursor', 'skills'),
join(dir, '.codex', 'skills'),
join(dir, '.github', 'skills'),
];
for (const searchDir of searchDirs) {
if (!existsSync(searchDir)) continue;
this.scanDir(searchDir, results, 0);
}
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
if (!entry.isDirectory()) continue;
if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
const entrySkillMd = join(dir, entry.name, 'SKILL.md');
if (existsSync(entrySkillMd) && !results.includes(entrySkillMd)) {
results.push(entrySkillMd);
}
}
} catch {
// ignore read errors
}
return results;
}
private scanDir(dir: string, results: string[], depth: number): void {
if (depth > 3) return;
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
const entryPath = join(dir, entry.name);
if (entry.isFile() && entry.name === 'SKILL.md') {
if (!results.includes(entryPath)) results.push(entryPath);
}
if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
this.scanDir(entryPath, results, depth + 1);
}
}
} catch {
// ignore read errors
}
}
}
+11 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.9.0",
"version": "1.12.0",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
@@ -37,6 +37,10 @@
"./learning": {
"import": "./dist/learning/index.js",
"types": "./dist/learning/index.d.ts"
},
"./search": {
"import": "./dist/search/index.js",
"types": "./dist/search/index.d.ts"
}
},
"files": [
@@ -53,7 +57,13 @@
"yaml": "^2.6.1",
"zod": "^3.24.1"
},
"optionalDependencies": {
"node-llama-cpp": "^3.15.0",
"better-sqlite3": "^12.0.0",
"sqlite-vec": "^0.1.6"
},
"devDependencies": {
"@types/better-sqlite3": "^7.6.11",
"@types/node": "^22.10.5",
"tsup": "^8.3.5",
"typescript": "^5.7.2",
+91
View File
@@ -0,0 +1,91 @@
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { MemoryCache } from '../memory.js';
describe('MemoryCache', () => {
let cache: MemoryCache<string>;
beforeEach(() => {
cache = new MemoryCache<string>({ maxSize: 3, ttlMs: 1000 });
});
it('stores and retrieves values', () => {
cache.set('a', 'value-a');
expect(cache.get('a')).toBe('value-a');
});
it('returns undefined for missing keys', () => {
expect(cache.get('missing')).toBeUndefined();
});
it('deletes entries', () => {
cache.set('a', 'value-a');
expect(cache.delete('a')).toBe(true);
expect(cache.get('a')).toBeUndefined();
});
it('checks existence with has()', () => {
cache.set('a', 'value-a');
expect(cache.has('a')).toBe(true);
expect(cache.has('b')).toBe(false);
});
it('clears all entries', () => {
cache.set('a', '1');
cache.set('b', '2');
cache.clear();
expect(cache.has('a')).toBe(false);
expect(cache.stats().size).toBe(0);
});
it('evicts LRU when at capacity', () => {
vi.useFakeTimers();
try {
cache.set('a', '1');
vi.advanceTimersByTime(1);
cache.set('b', '2');
vi.advanceTimersByTime(1);
cache.set('c', '3');
vi.advanceTimersByTime(1);
cache.get('a');
vi.advanceTimersByTime(1);
cache.get('b');
vi.advanceTimersByTime(1);
cache.set('d', '4');
expect(cache.has('c')).toBe(false);
expect(cache.has('a')).toBe(true);
expect(cache.has('d')).toBe(true);
} finally {
vi.useRealTimers();
}
});
it('expires entries after TTL', () => {
vi.useFakeTimers();
try {
cache.set('a', 'value');
expect(cache.get('a')).toBe('value');
vi.advanceTimersByTime(1001);
expect(cache.get('a')).toBeUndefined();
} finally {
vi.useRealTimers();
}
});
it('tracks hit/miss stats', () => {
cache.set('a', '1');
cache.get('a');
cache.get('missing');
const stats = cache.stats();
expect(stats.hits).toBe(1);
expect(stats.misses).toBe(1);
expect(stats.hitRate).toBe(0.5);
expect(stats.size).toBe(1);
expect(stats.maxSize).toBe(3);
});
it('uses default options', () => {
const defaultCache = new MemoryCache<string>();
const stats = defaultCache.stats();
expect(stats.maxSize).toBe(1000);
});
});
+2
View File
@@ -0,0 +1,2 @@
export * from './types.js';
export * from './memory.js';
+101
View File
@@ -0,0 +1,101 @@
import type { CacheBackend, CacheOptions, CacheStats } from './types.js';
interface CacheEntry<V> {
value: V;
expiresAt: number;
lastAccessed: number;
}
const DEFAULT_MAX_SIZE = 1000;
const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
export class MemoryCache<V = unknown> implements CacheBackend<V> {
private store = new Map<string, CacheEntry<V>>();
private maxSize: number;
private ttlMs: number;
private hitCount = 0;
private missCount = 0;
constructor(options?: CacheOptions) {
this.maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
}
get(key: string): V | undefined {
const entry = this.store.get(key);
if (!entry) {
this.missCount++;
return undefined;
}
if (Date.now() > entry.expiresAt) {
this.store.delete(key);
this.missCount++;
return undefined;
}
entry.lastAccessed = Date.now();
this.hitCount++;
return entry.value;
}
set(key: string, value: V): void {
if (this.store.size >= this.maxSize && !this.store.has(key)) {
this.evictLRU();
}
const now = Date.now();
this.store.set(key, {
value,
expiresAt: now + this.ttlMs,
lastAccessed: now,
});
}
delete(key: string): boolean {
return this.store.delete(key);
}
has(key: string): boolean {
const entry = this.store.get(key);
if (!entry) return false;
if (Date.now() > entry.expiresAt) {
this.store.delete(key);
return false;
}
return true;
}
clear(): void {
this.store.clear();
this.hitCount = 0;
this.missCount = 0;
}
stats(): CacheStats {
const total = this.hitCount + this.missCount;
return {
hits: this.hitCount,
misses: this.missCount,
size: this.store.size,
maxSize: this.maxSize,
hitRate: total > 0 ? this.hitCount / total : 0,
};
}
private evictLRU(): void {
let oldestKey: string | null = null;
let oldestTime = Infinity;
for (const [key, entry] of this.store) {
if (entry.lastAccessed < oldestTime) {
oldestTime = entry.lastAccessed;
oldestKey = key;
}
}
if (oldestKey) {
this.store.delete(oldestKey);
}
}
}
+21
View File
@@ -0,0 +1,21 @@
export interface CacheStats {
hits: number;
misses: number;
size: number;
maxSize: number;
hitRate: number;
}
export interface CacheOptions {
maxSize?: number;
ttlMs?: number;
}
export interface CacheBackend<V = unknown> {
get(key: string): V | undefined;
set(key: string, value: V): void;
delete(key: string): boolean;
has(key: string): boolean;
clear(): void;
stats(): CacheStats;
}
+19
View File
@@ -101,3 +101,22 @@ export * from './connectors/index.js';
// Execution Flow (Step Tracking & Metrics - Phase 21)
export * from './execution/index.js';
// Hybrid Search (QMD-Inspired Vector + Keyword Search)
export * from './search/index.js';
// Federated Registry (External Skill Sources)
export * from './registry/index.js';
// Pluggable Cache Backend
export * from './cache/index.js';
// Multi-Signal Relevance Ranking
export * from './ranking/index.js';
// Enhanced SKILL.md Parser (References & Frontmatter)
export { discoverReferences, stripFrontmatter, parseSkillMd } from './parser/index.js';
export type { SkillReference, ParsedSkillContent } from './parser/index.js';
// Runtime Skill Injection
export * from './runtime/index.js';
@@ -0,0 +1,94 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { stripFrontmatter, parseSkillMd, discoverReferences } from '../references.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readdirSync: vi.fn(),
statSync: vi.fn(),
readFileSync: vi.fn(),
}));
import { existsSync, readdirSync, statSync } from 'node:fs';
const mockExistsSync = vi.mocked(existsSync);
const mockReaddirSync = vi.mocked(readdirSync);
const mockStatSync = vi.mocked(statSync);
describe('stripFrontmatter', () => {
it('extracts frontmatter and body', () => {
const raw = `---
name: my-skill
version: 1.0
---
# My Skill
Content here.`;
const result = stripFrontmatter(raw);
expect(result.frontmatter.name).toBe('my-skill');
expect(result.frontmatter.version).toBe('1.0');
expect(result.body).toContain('# My Skill');
expect(result.body).toContain('Content here.');
});
it('returns empty frontmatter when no delimiters', () => {
const raw = '# Just content\n\nNo frontmatter.';
const result = stripFrontmatter(raw);
expect(result.frontmatter).toEqual({});
expect(result.body).toBe(raw);
});
it('handles empty frontmatter block', () => {
const raw = '---\n---\nBody text';
const result = stripFrontmatter(raw);
expect(result.frontmatter).toEqual({});
expect(result.body).toBe('Body text');
});
});
describe('parseSkillMd', () => {
it('parses raw content without skill dir', () => {
const raw = `---
name: test
---
Body content`;
const result = parseSkillMd(raw);
expect(result.frontmatter.name).toBe('test');
expect(result.body).toBe('Body content');
expect(result.references).toEqual([]);
expect(result.raw).toBe(raw);
});
});
describe('discoverReferences', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('finds files in reference directories', () => {
mockExistsSync.mockImplementation((p) => {
return String(p).endsWith('/examples');
});
mockStatSync.mockImplementation((p) => {
const path = String(p);
if (path.endsWith('/examples')) {
return { isDirectory: () => true, isFile: () => false } as any;
}
return { isDirectory: () => false, isFile: () => true } as any;
});
mockReaddirSync.mockReturnValue(['demo.ts', 'readme.md'] as any);
const refs = discoverReferences('/fake/skill');
expect(refs).toHaveLength(2);
expect(refs[0]).toEqual({
path: 'examples/demo.ts',
type: 'example',
name: 'demo.ts',
});
});
it('returns empty array when no reference dirs exist', () => {
mockExistsSync.mockReturnValue(false);
const refs = discoverReferences('/fake/skill');
expect(refs).toEqual([]);
});
});
+1
View File
@@ -0,0 +1 @@
export * from './references.js';
+105
View File
@@ -0,0 +1,105 @@
import { readdirSync, statSync, existsSync } from 'node:fs';
import { join } from 'node:path';
export interface SkillReference {
path: string;
type: 'example' | 'doc' | 'resource' | 'asset';
name: string;
}
export interface ParsedSkillContent {
frontmatter: Record<string, unknown>;
body: string;
references: SkillReference[];
raw: string;
}
const REFERENCE_DIRS = ['references', 'resources', 'docs', 'examples', 'assets', 'scripts'];
const DIR_TYPE_MAP: Record<string, SkillReference['type']> = {
references: 'resource',
resources: 'resource',
docs: 'doc',
examples: 'example',
assets: 'asset',
scripts: 'resource',
};
export function discoverReferences(skillDir: string): SkillReference[] {
const refs: SkillReference[] = [];
for (const dir of REFERENCE_DIRS) {
const fullPath = join(skillDir, dir);
if (!existsSync(fullPath)) continue;
try {
const stat = statSync(fullPath);
if (!stat.isDirectory()) continue;
} catch {
continue;
}
const type = DIR_TYPE_MAP[dir] || 'resource';
try {
const entries = readdirSync(fullPath);
for (const entry of entries) {
const entryPath = join(fullPath, entry);
try {
const entryStat = statSync(entryPath);
if (entryStat.isFile()) {
refs.push({
path: join(dir, entry),
type,
name: entry,
});
}
} catch {
continue;
}
}
} catch {
continue;
}
}
return refs;
}
export function stripFrontmatter(raw: string): { frontmatter: Record<string, unknown>; body: string } {
const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
if (!match) {
const emptyMatch = raw.match(/^---\r?\n---\r?\n?([\s\S]*)$/);
if (emptyMatch) {
return { frontmatter: {}, body: emptyMatch[1] };
}
return { frontmatter: {}, body: raw };
}
const fmBlock = match[1];
const body = match[2];
const frontmatter: Record<string, unknown> = {};
for (const line of fmBlock.split('\n')) {
const colonIdx = line.indexOf(':');
if (colonIdx === -1) continue;
const key = line.slice(0, colonIdx).trim();
const value = line.slice(colonIdx + 1).trim();
if (key) {
frontmatter[key] = value;
}
}
return { frontmatter, body };
}
export function parseSkillMd(raw: string, skillDir?: string): ParsedSkillContent {
const { frontmatter, body } = stripFrontmatter(raw);
const references = skillDir ? discoverReferences(skillDir) : [];
return {
frontmatter,
body,
references,
raw,
};
}
@@ -0,0 +1,85 @@
import { describe, it, expect } from 'vitest';
import { RelevanceRanker } from '../relevance.js';
import type { RankableSkill } from '../relevance.js';
describe('RelevanceRanker', () => {
const ranker = new RelevanceRanker();
const skills: RankableSkill[] = [
{
name: 'react-performance',
description: 'Optimize React app performance',
content: 'Full guide on React performance optimization',
stars: 150,
references: ['examples/demo.ts'],
},
{
name: 'testing-basics',
description: 'Unit testing fundamentals',
stars: 10,
},
{
name: 'empty-skill',
},
];
it('ranks skills by relevance score', () => {
const results = ranker.rank(skills);
expect(results).toHaveLength(3);
expect(results[0].skill.name).toBe('react-performance');
expect(results[0].score).toBeGreaterThan(results[1].score);
});
it('gives max content score for description + content', () => {
const results = ranker.rank(skills);
const full = results.find((r) => r.skill.name === 'react-performance')!;
expect(full.breakdown.contentAvailability).toBe(40);
});
it('gives partial content score for description only', () => {
const results = ranker.rank(skills);
const partial = results.find((r) => r.skill.name === 'testing-basics')!;
expect(partial.breakdown.contentAvailability).toBe(20);
});
it('gives zero content score for empty skill', () => {
const results = ranker.rank(skills);
const empty = results.find((r) => r.skill.name === 'empty-skill')!;
expect(empty.breakdown.contentAvailability).toBe(0);
});
it('boosts exact name match on query', () => {
const results = ranker.rank(skills, 'react-performance');
const match = results.find((r) => r.skill.name === 'react-performance')!;
expect(match.breakdown.queryMatch).toBe(30);
});
it('gives partial query match for substring', () => {
const results = ranker.rank(skills, 'react');
const match = results.find((r) => r.skill.name === 'react-performance')!;
expect(match.breakdown.queryMatch).toBeGreaterThan(0);
expect(match.breakdown.queryMatch).toBeLessThan(30);
});
it('scores popularity via log scale', () => {
const results = ranker.rank(skills);
const popular = results.find((r) => r.skill.name === 'react-performance')!;
const less = results.find((r) => r.skill.name === 'testing-basics')!;
expect(popular.breakdown.popularity).toBeGreaterThan(less.breakdown.popularity);
});
it('scores references', () => {
const results = ranker.rank(skills);
const withRefs = results.find((r) => r.skill.name === 'react-performance')!;
const noRefs = results.find((r) => r.skill.name === 'testing-basics')!;
expect(withRefs.breakdown.referenceScore).toBeGreaterThan(0);
expect(noRefs.breakdown.referenceScore).toBe(0);
});
it('returns zero query match when no query provided', () => {
const results = ranker.rank(skills);
for (const r of results) {
expect(r.breakdown.queryMatch).toBe(0);
}
});
});
+1
View File
@@ -0,0 +1 @@
export * from './relevance.js';
+92
View File
@@ -0,0 +1,92 @@
export interface RankableSkill {
name: string;
description?: string;
content?: string;
stars?: number;
installs?: number;
references?: string[];
}
export interface RankedSkill<T extends RankableSkill = RankableSkill> {
skill: T;
score: number;
breakdown: ScoreBreakdown;
}
export interface ScoreBreakdown {
contentAvailability: number;
queryMatch: number;
popularity: number;
referenceScore: number;
}
const WEIGHTS = {
contentAvailability: 40,
queryMatch: 30,
popularity: 15,
references: 15,
} as const;
export class RelevanceRanker {
rank<T extends RankableSkill>(skills: T[], query?: string): RankedSkill<T>[] {
const results = skills.map((skill) => {
const breakdown = this.score(skill, query);
const score =
breakdown.contentAvailability +
breakdown.queryMatch +
breakdown.popularity +
breakdown.referenceScore;
return { skill, score, breakdown };
});
results.sort((a, b) => b.score - a.score);
return results;
}
private score(skill: RankableSkill, query?: string): ScoreBreakdown {
return {
contentAvailability: this.scoreContent(skill),
queryMatch: query ? this.scoreQuery(skill, query) : 0,
popularity: this.scorePopularity(skill),
referenceScore: this.scoreReferences(skill),
};
}
private scoreContent(skill: RankableSkill): number {
let score = 0;
if (skill.description && skill.description.length > 0) score += 20;
if (skill.content && skill.content.length > 0) score += 20;
return score;
}
private scoreQuery(skill: RankableSkill, query: string): number {
const q = query.toLowerCase();
const name = skill.name.toLowerCase();
if (name === q) return WEIGHTS.queryMatch;
if (name.includes(q) || q.includes(name)) {
return WEIGHTS.queryMatch * 0.7;
}
const desc = (skill.description || '').toLowerCase();
const content = (skill.content || '').toLowerCase();
const searchable = `${name} ${desc} ${content}`;
const words = q.split(/\s+/).filter(Boolean);
const matched = words.filter((w) => searchable.includes(w)).length;
if (words.length === 0) return 0;
return Math.round(WEIGHTS.queryMatch * (matched / words.length) * 0.6);
}
private scorePopularity(skill: RankableSkill): number {
const count = (skill.stars ?? 0) + (skill.installs ?? 0);
if (count <= 0) return 0;
return Math.min(WEIGHTS.popularity, Math.round(Math.log10(count + 1) * 5));
}
private scoreReferences(skill: RankableSkill): number {
if (!skill.references || skill.references.length === 0) return 0;
return Math.min(WEIGHTS.references, skill.references.length * 5);
}
}
+91
View File
@@ -11,8 +11,11 @@ import type {
SearchOptions,
SearchResult,
FreshnessResult,
RecommendHybridSearchOptions,
RecommendHybridSearchResult,
} from './types.js';
import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
import type { HybridSearchPipeline } from '../search/hybrid.js';
/**
* Recommendation engine for matching skills to project profiles
@@ -20,16 +23,39 @@ import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
export class RecommendationEngine {
private weights: ScoringWeights;
private index: SkillIndex | null = null;
private hybridPipeline: HybridSearchPipeline | null = null;
constructor(weights?: Partial<ScoringWeights>) {
this.weights = { ...DEFAULT_SCORING_WEIGHTS, ...weights };
}
/**
* Initialize hybrid search pipeline for vector + keyword search
*/
async initHybridSearch(): Promise<void> {
const { createHybridSearchPipeline } = await import('../search/hybrid.js');
this.hybridPipeline = createHybridSearchPipeline();
if (this.index) {
this.hybridPipeline.loadSkillsIndex(this.index);
}
await this.hybridPipeline.initialize();
}
/**
* Check if hybrid search is available
*/
isHybridSearchAvailable(): boolean {
return this.hybridPipeline !== null && this.hybridPipeline.isInitialized();
}
/**
* Load skill index from cache or generate from local skills
*/
loadIndex(index: SkillIndex): void {
this.index = index;
if (this.hybridPipeline) {
this.hybridPipeline.loadSkillsIndex(index);
}
}
/**
@@ -603,6 +629,71 @@ export class RecommendationEngine {
return { relevance, matchedTerms, snippet };
}
/**
* Hybrid search combining vector embeddings and keyword matching
*/
async hybridSearch(options: RecommendHybridSearchOptions): Promise<RecommendHybridSearchResult[]> {
const { query, limit = 10, hybrid = true, enableExpansion = false, enableReranking = false, filters } = options;
if (!hybrid || !this.hybridPipeline) {
const basicResults = this.search({ query, limit, semantic: true, filters });
return basicResults.map((r) => ({
...r,
hybridScore: r.relevance / 100,
}));
}
const response = await this.hybridPipeline.search({
query,
limit,
enableExpansion,
enableReranking,
});
let results = response.results.map((r) => ({
skill: r.skill,
relevance: r.relevance,
matchedTerms: r.matchedTerms,
snippet: r.snippet,
hybridScore: r.hybridScore,
vectorSimilarity: r.vectorSimilarity,
keywordScore: r.keywordScore,
rrfScore: r.rrfScore,
expandedTerms: r.expandedTerms,
}));
if (filters?.tags && filters.tags.length > 0) {
results = results.filter((r) =>
r.skill.tags?.some((t) => filters.tags!.includes(t))
);
}
if (filters?.verified) {
results = results.filter((r) => r.skill.verified);
}
if (filters?.minScore) {
results = results.filter((r) => r.relevance >= filters.minScore!);
}
return results.slice(0, limit);
}
/**
* Build hybrid search index from skills
*/
async buildHybridIndex(
onProgress?: (progress: { phase: string; current: number; total: number; message?: string }) => void
): Promise<void> {
if (!this.index) {
throw new Error('No skill index loaded. Call loadIndex() first.');
}
if (!this.hybridPipeline) {
await this.initHybridSearch();
}
await this.hybridPipeline!.buildIndex(this.index.skills, onProgress);
}
/**
* Check freshness of installed skills against project dependencies
*
+22
View File
@@ -326,3 +326,25 @@ export interface ReasoningRecommendationResult extends RecommendationResult {
strategy: string;
};
}
/**
* Hybrid search options for RecommendationEngine
*/
export interface RecommendHybridSearchOptions extends SearchOptions {
hybrid?: boolean;
enableExpansion?: boolean;
enableReranking?: boolean;
semanticWeight?: number;
keywordWeight?: number;
}
/**
* Hybrid search result with additional metadata for RecommendationEngine
*/
export interface RecommendHybridSearchResult extends SearchResult {
hybridScore?: number;
vectorSimilarity?: number;
keywordScore?: number;
rrfScore?: number;
expandedTerms?: string[];
}
@@ -0,0 +1,87 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { CommunityRegistry } from '../community.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
}));
import { existsSync, readFileSync } from 'node:fs';
const mockExistsSync = vi.mocked(existsSync);
const mockReadFileSync = vi.mocked(readFileSync);
const SAMPLE_SKILLS_MD = `# SkillKit Community Skills Registry
## Code Quality
- [code-simplifier](https://github.com/anthropics/skills) - Simplifies and refines code
- [code-review](https://github.com/anthropics/skills) - Automated code review
## Testing
- [testing-guide](https://github.com/anthropics/skills) - Unit testing fundamentals
- [e2e-testing](https://github.com/anthropics/skills) - End-to-end testing with Playwright
`;
describe('CommunityRegistry', () => {
beforeEach(() => {
vi.clearAllMocks();
mockExistsSync.mockReturnValue(true);
mockReadFileSync.mockReturnValue(SAMPLE_SKILLS_MD);
});
it('parses SKILLS.md entries', async () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const results = await registry.search('code');
expect(results.length).toBeGreaterThan(0);
expect(results[0].registry).toBe('community');
expect(results[0].name).toBe('code-simplifier');
});
it('searches by description', async () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const results = await registry.search('Playwright');
expect(results.length).toBe(1);
expect(results[0].name).toBe('e2e-testing');
});
it('searches by category', async () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const results = await registry.search('Testing');
expect(results.length).toBe(2);
});
it('respects limit', async () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const results = await registry.search('code', { limit: 1 });
expect(results.length).toBe(1);
});
it('returns empty when no match', async () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const results = await registry.search('nonexistent-xyz');
expect(results.length).toBe(0);
});
it('getAll returns all entries', () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const all = registry.getAll();
expect(all.length).toBe(4);
});
it('getCategories returns unique categories', () => {
const registry = new CommunityRegistry('/fake/SKILLS.md');
const cats = registry.getCategories();
expect(cats).toContain('Code Quality');
expect(cats).toContain('Testing');
expect(cats.length).toBe(2);
});
it('handles missing file gracefully', async () => {
mockExistsSync.mockReturnValue(false);
const registry = new CommunityRegistry('/missing/SKILLS.md');
const results = await registry.search('anything');
expect(results).toEqual([]);
});
});
+97
View File
@@ -0,0 +1,97 @@
import { readFileSync, existsSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import type { ExternalRegistry, ExternalSkill } from './index.js';
interface ParsedEntry {
name: string;
url: string;
description: string;
category: string;
}
export class CommunityRegistry implements ExternalRegistry {
name = 'community';
private entries: ParsedEntry[] = [];
private loaded = false;
constructor(private skillsMdPath?: string) {}
private load(): void {
if (this.loaded) return;
this.loaded = true;
const paths = this.skillsMdPath
? [this.skillsMdPath]
: [
join(process.cwd(), 'registry', 'SKILLS.md'),
join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'registry', 'SKILLS.md'),
];
for (const path of paths) {
if (!existsSync(path)) continue;
try {
const content = readFileSync(path, 'utf-8');
this.entries = this.parse(content);
return;
} catch {
continue;
}
}
}
private parse(content: string): ParsedEntry[] {
const results: ParsedEntry[] = [];
let currentCategory = '';
for (const line of content.split('\n')) {
const headerMatch = line.match(/^##\s+(.+)/);
if (headerMatch) {
currentCategory = headerMatch[1].trim();
continue;
}
const entryMatch = line.match(/^-\s+\[([^\]]+)\]\(([^)]+)\)\s*-\s*(.+)/);
if (entryMatch) {
results.push({
name: entryMatch[1].trim(),
url: entryMatch[2].trim(),
description: entryMatch[3].trim(),
category: currentCategory,
});
}
}
return results;
}
async search(query: string, options?: { limit?: number }): Promise<ExternalSkill[]> {
this.load();
const limit = options?.limit ?? 20;
const q = query.toLowerCase();
const matched = this.entries.filter(
(e) =>
e.name.toLowerCase().includes(q) ||
e.description.toLowerCase().includes(q) ||
e.category.toLowerCase().includes(q),
);
return matched.slice(0, limit).map((e) => ({
name: e.name,
description: e.description,
source: e.url,
registry: this.name,
}));
}
getAll(): ParsedEntry[] {
this.load();
return [...this.entries];
}
getCategories(): string[] {
this.load();
return [...new Set(this.entries.map((e) => e.category))];
}
}
+165
View File
@@ -0,0 +1,165 @@
export interface ExternalSkill {
name: string;
description: string;
source: string;
registry: string;
path?: string;
stars?: number;
updatedAt?: string;
}
export interface ExternalRegistry {
name: string;
search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]>;
}
export interface FederatedResult {
skills: ExternalSkill[];
registries: string[];
total: number;
query: string;
}
export class RateLimitError extends Error {
constructor(registry: string) {
super(`Rate limited by ${registry} API. Authenticate with a token or wait before retrying.`);
this.name = 'RateLimitError';
}
}
export class GitHubSkillRegistry implements ExternalRegistry {
name = 'github';
private baseUrl = 'https://api.github.com';
async search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]> {
const limit = options?.limit ?? 20;
const timeoutMs = options?.timeoutMs ?? 10_000;
const searchQuery = `SKILL.md ${query} in:path,file`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const headers: Record<string, string> = {
Accept: 'application/vnd.github.v3+json',
'User-Agent': 'skillkit-cli',
};
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
if (token) {
headers.Authorization = `Bearer ${token}`;
}
const response = await fetch(
`${this.baseUrl}/search/code?q=${encodeURIComponent(searchQuery)}&per_page=${limit}`,
{
headers,
signal: controller.signal,
},
);
clearTimeout(timer);
if (!response.ok) {
if (response.status === 403) {
throw new RateLimitError(this.name);
}
return [];
}
const data = (await response.json()) as {
items?: Array<{
repository: {
full_name: string;
description?: string;
html_url: string;
stargazers_count?: number;
updated_at?: string;
};
path: string;
name: string;
}>;
};
if (!data.items) return [];
const seen = new Set<string>();
const skills: ExternalSkill[] = [];
for (const item of data.items) {
const repo = item.repository.full_name;
if (seen.has(repo)) continue;
seen.add(repo);
const pathParts = item.path.split('/');
const skillName =
pathParts.length > 1
? pathParts[pathParts.length - 2]
: repo.split('/').pop() || repo;
skills.push({
name: skillName,
description: item.repository.description || '',
source: item.repository.html_url,
registry: this.name,
path: item.path,
stars: item.repository.stargazers_count,
updatedAt: item.repository.updated_at,
});
}
return skills;
} catch (err) {
clearTimeout(timer);
if (err instanceof RateLimitError) throw err;
return [];
}
}
}
export { CommunityRegistry } from './community.js';
export class FederatedSearch {
private registries: ExternalRegistry[] = [];
addRegistry(registry: ExternalRegistry): void {
this.registries.push(registry);
}
async search(query: string, options?: { limit?: number }): Promise<FederatedResult> {
const limit = options?.limit ?? 20;
const results = await Promise.allSettled(
this.registries.map((r) => r.search(query, { limit })),
);
const allSkills: ExternalSkill[] = [];
const activeRegistries: string[] = [];
for (let i = 0; i < results.length; i++) {
const result = results[i];
if (result.status === 'fulfilled' && result.value.length > 0) {
allSkills.push(...result.value);
activeRegistries.push(this.registries[i].name);
} else if (result.status === 'rejected' && result.reason instanceof RateLimitError) {
throw result.reason;
}
}
const seen = new Set<string>();
const deduplicated: ExternalSkill[] = [];
for (const skill of allSkills) {
const key = `${skill.source}:${skill.name}`;
if (!seen.has(key)) {
seen.add(key);
deduplicated.push(skill);
}
}
deduplicated.sort((a, b) => (b.stars ?? 0) - (a.stars ?? 0));
return {
skills: deduplicated.slice(0, limit),
registries: activeRegistries,
total: deduplicated.length,
query,
};
}
}
@@ -0,0 +1,113 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { SkillInjector } from '../injector.js';
const mockFetch = vi.fn();
global.fetch = mockFetch;
describe('SkillInjector', () => {
let injector: SkillInjector;
beforeEach(() => {
injector = new SkillInjector(60_000);
mockFetch.mockReset();
});
afterEach(() => {
injector.clearCache();
});
const skillMd = `---
name: test-skill
version: 1.0
---
# Test Skill
This is the body content.`;
it('fetches and parses a SKILL.md from GitHub', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
const result = await injector.fetch('owner/repo', 'test-skill');
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
expect(result.skillId).toBe('test-skill');
expect(result.parsed.frontmatter.name).toBe('test-skill');
expect(result.parsed.body).toContain('# Test Skill');
expect(result.fetchedAt).toBeGreaterThan(0);
});
it('returns cached result on subsequent calls', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
await injector.fetch('owner/repo', 'test-skill');
const second = await injector.fetch('owner/repo', 'test-skill');
expect(mockFetch).toHaveBeenCalledTimes(1);
expect(second.parsed.body).toContain('# Test Skill');
});
it('inject() returns body without frontmatter', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
const body = await injector.inject('owner/repo', 'test-skill');
expect(body).toContain('# Test Skill');
expect(body).not.toContain('---');
expect(body).not.toContain('name: test-skill');
});
it('throws on invalid source format', async () => {
await expect(injector.fetch('invalid', 'skill')).rejects.toThrow('Invalid source format');
});
it('throws when SKILL.md not found after trying all paths', async () => {
mockFetch.mockResolvedValue({ ok: false, status: 404 });
await expect(injector.fetch('owner/repo', 'missing')).rejects.toThrow('SKILL.md not found');
});
it('tries multiple paths before failing', async () => {
mockFetch
.mockResolvedValueOnce({ ok: false, status: 404 })
.mockResolvedValueOnce({ ok: false, status: 404 })
.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
const result = await injector.fetch('owner/repo', 'skill');
expect(mockFetch).toHaveBeenCalledTimes(3);
expect(result.parsed.body).toContain('# Test Skill');
});
it('reports cache stats', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
await injector.fetch('owner/repo', 'skill');
await injector.fetch('owner/repo', 'skill');
const stats = injector.cacheStats();
expect(stats.size).toBe(1);
expect(stats.hits).toBe(1);
expect(stats.misses).toBe(1);
});
it('parses full GitHub URLs as source', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
text: async () => skillMd,
});
const result = await injector.fetch('https://github.com/owner/repo', 'skill');
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
});
});
+1
View File
@@ -0,0 +1 @@
export * from './injector.js';
+99
View File
@@ -0,0 +1,99 @@
import { MemoryCache } from '../cache/memory.js';
import { parseSkillMd } from '../parser/references.js';
import type { ParsedSkillContent } from '../parser/references.js';
export interface RuntimeSkillSource {
owner: string;
repo: string;
}
export interface FetchedSkill {
source: RuntimeSkillSource;
skillId: string;
parsed: ParsedSkillContent;
fetchedAt: number;
}
function parseSource(source: string): RuntimeSkillSource {
const parts = source.replace(/^https?:\/\/github\.com\//, '').split('/');
if (parts.length < 2) {
throw new Error(`Invalid source format: "${source}". Expected "owner/repo".`);
}
return { owner: parts[0], repo: parts[1] };
}
export class SkillInjector {
private cache: MemoryCache<FetchedSkill>;
constructor(cacheTtlMs?: number) {
this.cache = new MemoryCache<FetchedSkill>({
maxSize: 200,
ttlMs: cacheTtlMs ?? 24 * 60 * 60 * 1000,
});
}
async fetch(source: string, skillId: string): Promise<FetchedSkill> {
const cacheKey = `${source}:${skillId}`;
const cached = this.cache.get(cacheKey);
if (cached) return cached;
const { owner, repo } = parseSource(source);
const raw = await this.fetchRawSkillMd(owner, repo, skillId);
const parsed = parseSkillMd(raw);
const result: FetchedSkill = {
source: { owner, repo },
skillId,
parsed,
fetchedAt: Date.now(),
};
this.cache.set(cacheKey, result);
return result;
}
async inject(source: string, skillId: string): Promise<string> {
const fetched = await this.fetch(source, skillId);
return fetched.parsed.body;
}
private async fetchRawSkillMd(owner: string, repo: string, skillId: string): Promise<string> {
const paths = [
`${skillId}/SKILL.md`,
`skills/${skillId}/SKILL.md`,
`SKILL.md`,
];
const headers: Record<string, string> = {
Accept: 'application/vnd.github.v3.raw',
'User-Agent': 'skillkit-runtime',
};
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
if (token) {
headers.Authorization = `Bearer ${token}`;
}
for (const path of paths) {
const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
try {
const response = await fetch(url, { headers });
if (response.ok) {
return await response.text();
}
} catch {
continue;
}
}
throw new Error(`SKILL.md not found in ${owner}/${repo} for skill "${skillId}"`);
}
clearCache(): void {
this.cache.clear();
}
cacheStats() {
return this.cache.stats();
}
}
@@ -0,0 +1,217 @@
import { describe, it, expect, beforeEach } from 'vitest';
import { EmbeddingService } from '../embeddings.js';
import type { SkillSummary } from '../../recommend/types.js';
describe('EmbeddingService', () => {
describe('cosineSimilarity', () => {
let service: EmbeddingService;
beforeEach(() => {
service = new EmbeddingService();
});
it('should return 1 for identical vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(1, 5);
});
it('should return 0 for orthogonal vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([0, 1, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(0, 5);
});
it('should return -1 for opposite vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([-1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(-1, 5);
});
it('should handle normalized vectors', () => {
const a = new Float32Array([0.5, 0.5, 0.5, 0.5]);
const b = new Float32Array([0.5, 0.5, 0.5, 0.5]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(1, 5);
});
it('should throw for mismatched dimensions', () => {
const a = new Float32Array([1, 0]);
const b = new Float32Array([1, 0, 0]);
expect(() => service.cosineSimilarity(a, b)).toThrow('Vector dimensions mismatch');
});
it('should return 0 for zero vectors', () => {
const a = new Float32Array([0, 0, 0]);
const b = new Float32Array([1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBe(0);
});
});
describe('initialization state', () => {
it('should not be initialized by default', () => {
const service = new EmbeddingService();
expect(service.isInitialized()).toBe(false);
});
it('should return default dimensions', () => {
const service = new EmbeddingService();
expect(service.getDimensions()).toBe(768);
});
});
describe('skill text building', () => {
it('should handle skill with all fields', async () => {
const service = new EmbeddingService();
const skill: SkillSummary = {
name: 'test-skill',
description: 'A test skill',
tags: ['tag1', 'tag2'],
compatibility: {
frameworks: ['react'],
languages: ['typescript'],
libraries: ['lodash'],
},
popularity: 100,
quality: 80,
verified: true,
};
const buildSkillText = (s: SkillSummary): string => {
const parts: string[] = [s.name];
if (s.description) parts.push(s.description);
if (s.tags?.length) parts.push(s.tags.join(' '));
if (s.compatibility?.frameworks?.length) parts.push(s.compatibility.frameworks.join(' '));
if (s.compatibility?.languages?.length) parts.push(s.compatibility.languages.join(' '));
if (s.compatibility?.libraries?.length) parts.push(s.compatibility.libraries.join(' '));
return parts.join(' ').toLowerCase();
};
const text = buildSkillText(skill);
expect(text).toContain('test-skill');
expect(text).toContain('a test skill');
expect(text).toContain('tag1');
expect(text).toContain('react');
expect(text).toContain('typescript');
expect(text).toContain('lodash');
});
it('should handle skill with minimal fields', () => {
const skill: SkillSummary = {
name: 'minimal-skill',
tags: [],
popularity: 0,
quality: 50,
verified: false,
};
const buildSkillText = (s: SkillSummary): string => {
const parts: string[] = [s.name];
if (s.description) parts.push(s.description);
if (s.tags?.length) parts.push(s.tags.join(' '));
return parts.join(' ').toLowerCase();
};
const text = buildSkillText(skill);
expect(text).toBe('minimal-skill');
});
});
});
describe('EmbeddingService chunking', () => {
it('should split text into chunks', () => {
const chunkText = (
text: string,
config = { maxTokens: 100, overlapPercent: 15, minChunkSize: 10 }
) => {
const lines = text.split('\n');
const chunks: { content: string; startLine: number; endLine: number }[] = [];
const avgCharsPerToken = 4;
const maxCharsPerChunk = config.maxTokens * avgCharsPerToken;
const overlapChars = Math.floor(maxCharsPerChunk * (config.overlapPercent / 100));
let currentChunk: string[] = [];
let currentChars = 0;
let startLine = 0;
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const lineChars = line.length + 1;
if (currentChars + lineChars > maxCharsPerChunk && currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({ content, startLine, endLine: i - 1 });
}
const overlapLines: string[] = [];
let overlapCharsCount = 0;
for (let j = currentChunk.length - 1; j >= 0 && overlapCharsCount < overlapChars; j--) {
overlapLines.unshift(currentChunk[j]);
overlapCharsCount += currentChunk[j].length + 1;
}
currentChunk = overlapLines;
currentChars = overlapCharsCount;
startLine = i - overlapLines.length;
}
currentChunk.push(line);
currentChars += lineChars;
}
if (currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({ content, startLine, endLine: lines.length - 1 });
}
}
return chunks;
};
const longText = Array(50).fill('This is a line of text for testing.').join('\n');
const chunks = chunkText(longText);
expect(chunks.length).toBeGreaterThan(1);
chunks.forEach((chunk) => {
expect(chunk.content.length).toBeLessThanOrEqual(400);
expect(chunk.startLine).toBeGreaterThanOrEqual(0);
expect(chunk.endLine).toBeGreaterThanOrEqual(chunk.startLine);
});
});
it('should not chunk short text', () => {
const chunkText = (
text: string,
config = { maxTokens: 800, overlapPercent: 15, minChunkSize: 100 }
) => {
const lines = text.split('\n');
if (text.length < config.maxTokens * 4) {
if (text.length >= config.minChunkSize) {
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
}
return [];
}
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
};
const shortText = 'This is a short text that should not be chunked.';
const chunks = chunkText(shortText, { maxTokens: 800, overlapPercent: 15, minChunkSize: 10 });
expect(chunks.length).toBe(1);
expect(chunks[0].content).toBe(shortText);
});
});
@@ -0,0 +1,100 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { QueryExpander, expandQuerySimple } from '../expansion.js';
describe('QueryExpander', () => {
let expander: QueryExpander;
beforeEach(() => {
expander = new QueryExpander();
});
afterEach(() => {
expander.clearCache();
});
describe('expandQuerySimple (without LLM)', () => {
it('should expand "auth" to authentication-related terms', () => {
const result = expandQuerySimple('auth');
expect(result.original).toBe('auth');
expect(result.variations.length).toBeGreaterThan(0);
expect(result.variations.some((v) => v.includes('authentication'))).toBe(true);
});
it('should expand "api" to related terms', () => {
const result = expandQuerySimple('api');
expect(result.original).toBe('api');
expect(result.variations.some((v) => v.includes('rest') || v.includes('endpoint'))).toBe(true);
});
it('should expand "test" to testing-related terms', () => {
const result = expandQuerySimple('testing');
expect(result.original).toBe('testing');
expect(result.variations.some((v) => v.includes('test') || v.includes('unit'))).toBe(true);
});
it('should handle queries without synonyms', () => {
const result = expandQuerySimple('xyz123unique');
expect(result.original).toBe('xyz123unique');
expect(result.variations).toEqual([]);
expect(result.weights).toEqual([2.0]);
});
it('should give original query weight of 2.0', () => {
const result = expandQuerySimple('auth');
expect(result.weights[0]).toBe(2.0);
for (let i = 1; i < result.weights.length; i++) {
expect(result.weights[i]).toBe(1.0);
}
});
it('should limit variations to 3', () => {
const result = expandQuerySimple('auth');
expect(result.variations.length).toBeLessThanOrEqual(3);
});
});
describe('expand (fallback without LLM)', () => {
it('should return expanded query without LLM initialization', async () => {
const result = await expander.expand('auth');
expect(result.original).toBe('auth');
expect(result.variations.length).toBeGreaterThan(0);
});
it('should cache results', async () => {
const result1 = await expander.expand('auth');
const result2 = await expander.expand('auth');
expect(result1).toEqual(result2);
});
it('should handle case-insensitive caching', async () => {
const result1 = await expander.expand('Auth');
const result2 = await expander.expand('AUTH');
expect(result1.original).toBe('Auth');
expect(result2.original).toBe('AUTH');
});
});
describe('clearCache', () => {
it('should clear the expansion cache', async () => {
await expander.expand('auth');
expander.clearCache();
const result = await expander.expand('auth');
expect(result).toBeDefined();
});
});
describe('isInitialized', () => {
it('should return false when not initialized with LLM', () => {
expect(expander.isInitialized()).toBe(false);
});
});
});
@@ -0,0 +1,244 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import type { SkillSummary, SkillIndex } from '../../recommend/types.js';
const mockSkills: SkillSummary[] = [
{
name: 'react-auth',
description: 'Authentication utilities for React applications',
tags: ['react', 'auth', 'authentication'],
compatibility: {
frameworks: ['react'],
languages: ['typescript', 'javascript'],
libraries: ['next-auth'],
},
popularity: 500,
quality: 80,
verified: true,
},
{
name: 'vue-forms',
description: 'Form validation library for Vue',
tags: ['vue', 'forms', 'validation'],
compatibility: {
frameworks: ['vue'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 300,
quality: 75,
verified: false,
},
{
name: 'api-testing',
description: 'API testing utilities for REST endpoints',
tags: ['testing', 'api', 'rest'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: ['jest', 'supertest'],
},
popularity: 400,
quality: 85,
verified: true,
},
{
name: 'login-helper',
description: 'Helper functions for login and authentication flows',
tags: ['auth', 'login', 'oauth'],
compatibility: {
frameworks: ['react', 'vue'],
languages: ['typescript'],
libraries: [],
},
popularity: 200,
quality: 70,
verified: false,
},
];
const mockIndex: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills: mockSkills,
sources: [],
};
vi.mock('better-sqlite3', () => {
return {
default: vi.fn().mockImplementation(() => {
throw new Error("Cannot find module 'better-sqlite3'");
}),
};
});
vi.mock('sqlite-vec', () => {
return {
load: vi.fn(),
};
});
vi.mock('node-llama-cpp', () => {
return {
getLlama: vi.fn().mockImplementation(() => {
throw new Error("Cannot find package 'node-llama-cpp'");
}),
};
});
describe('HybridSearchPipeline', () => {
let HybridSearchPipeline: typeof import('../hybrid.js').HybridSearchPipeline;
let createHybridSearchPipeline: typeof import('../hybrid.js').createHybridSearchPipeline;
let pipeline: InstanceType<typeof HybridSearchPipeline>;
beforeEach(async () => {
const module = await import('../hybrid.js');
HybridSearchPipeline = module.HybridSearchPipeline;
createHybridSearchPipeline = module.createHybridSearchPipeline;
pipeline = createHybridSearchPipeline();
});
afterEach(async () => {
if (pipeline) {
await pipeline.dispose();
}
});
describe('initialization', () => {
it('should create a pipeline', () => {
expect(pipeline).toBeInstanceOf(HybridSearchPipeline);
});
it('should not be initialized before calling initialize()', () => {
expect(pipeline.isInitialized()).toBe(false);
});
it('should be initialized after calling initialize()', async () => {
await pipeline.initialize();
expect(pipeline.isInitialized()).toBe(true);
});
it('should load skills index', async () => {
pipeline.loadSkillsIndex(mockIndex);
const stats = pipeline.getStats();
expect(stats.skillCount).toBe(mockSkills.length);
});
});
describe('search (keyword-only fallback)', () => {
beforeEach(async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
});
it('should find skills matching query', async () => {
const response = await pipeline.search({ query: 'authentication' });
expect(response.results.length).toBeGreaterThan(0);
expect(response.results.some((r) => r.skill.name === 'react-auth')).toBe(true);
});
it('should find skills by tag', async () => {
const response = await pipeline.search({ query: 'react' });
expect(response.results.length).toBeGreaterThan(0);
expect(response.results.some((r) => r.skill.tags?.includes('react'))).toBe(true);
});
it('should respect limit parameter', async () => {
const response = await pipeline.search({ query: 'auth', limit: 2 });
expect(response.results.length).toBeLessThanOrEqual(2);
});
it('should include timing information', async () => {
const response = await pipeline.search({ query: 'test' });
expect(typeof response.timing.totalMs).toBe('number');
expect(response.timing.totalMs).toBeGreaterThanOrEqual(0);
expect(response.timing.keywordSearchMs).toBeGreaterThanOrEqual(0);
});
it('should include stats', async () => {
const response = await pipeline.search({ query: 'auth' });
expect(response.stats.candidatesFromKeyword).toBeGreaterThan(0);
expect(response.stats.totalMerged).toBeGreaterThan(0);
});
it('should return original query in response', async () => {
const response = await pipeline.search({ query: 'authentication' });
expect(response.query.original).toBe('authentication');
});
});
describe('search with expansion', () => {
beforeEach(async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
});
it('should expand query and find more results', async () => {
const response = await pipeline.search({
query: 'auth',
enableExpansion: true,
});
expect(response.results.length).toBeGreaterThan(0);
expect(response.query.expanded).toBeDefined();
});
it('should include expanded terms in response', async () => {
const response = await pipeline.search({
query: 'auth',
enableExpansion: true,
});
if (response.query.expanded) {
expect(response.query.expanded.original).toBe('auth');
expect(response.query.expanded.weights[0]).toBe(2.0);
}
});
});
describe('getStats', () => {
it('should return stats before initialization', () => {
const stats = pipeline.getStats();
expect(stats.initialized).toBe(false);
expect(stats.skillCount).toBe(0);
});
it('should return updated stats after loading index', async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
const stats = pipeline.getStats();
expect(stats.initialized).toBe(true);
expect(stats.skillCount).toBe(mockSkills.length);
});
});
});
describe('hybridSearch helper', () => {
let hybridSearch: typeof import('../hybrid.js').hybridSearch;
beforeEach(async () => {
const module = await import('../hybrid.js');
hybridSearch = module.hybridSearch;
});
it('should perform search on skills array', async () => {
const response = await hybridSearch(mockSkills, 'react');
expect(response.results.length).toBeGreaterThan(0);
expect(response.query.original).toBe('react');
});
it('should respect options', async () => {
const response = await hybridSearch(mockSkills, 'auth', {
limit: 1,
});
expect(response.results.length).toBe(1);
});
});
@@ -0,0 +1,276 @@
import { describe, it, expect } from 'vitest';
import {
computeRRFScore,
fuseWithRRF,
normalizeScores,
weightedCombine,
applyPositionAwareBlending,
getRankFromScore,
mergeRankings,
type RankerResult,
type RRFInput,
} from '../rrf.js';
describe('RRF (Reciprocal Rank Fusion)', () => {
describe('computeRRFScore', () => {
it('should compute RRF score for a single rank', () => {
const score = computeRRFScore([1], 60);
expect(score).toBeCloseTo(1 / 61, 5);
});
it('should sum RRF scores for multiple ranks', () => {
const score = computeRRFScore([1, 2, 3], 60);
const expected = 1 / 61 + 1 / 62 + 1 / 63;
expect(score).toBeCloseTo(expected, 5);
});
it('should use custom k value', () => {
const scoreK60 = computeRRFScore([1], 60);
const scoreK30 = computeRRFScore([1], 30);
expect(scoreK30).toBeGreaterThan(scoreK60);
});
it('should return 0 for empty ranks', () => {
const score = computeRRFScore([]);
expect(score).toBe(0);
});
});
describe('fuseWithRRF', () => {
it('should fuse results from multiple rankers', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [
{ skillName: 'skill-a', score: 0.9 },
{ skillName: 'skill-b', score: 0.8 },
{ skillName: 'skill-c', score: 0.7 },
],
},
{
source: 'keyword',
results: [
{ skillName: 'skill-b', score: 90 },
{ skillName: 'skill-a', score: 80 },
{ skillName: 'skill-d', score: 70 },
],
},
];
const rankings = fuseWithRRF(inputs, 60);
expect(rankings.length).toBe(4);
expect(rankings[0].skillName).toBe('skill-a');
expect(rankings[1].skillName).toBe('skill-b');
});
it('should include rank information from each source', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [{ skillName: 'skill-a', score: 0.9 }],
},
{
source: 'keyword',
results: [{ skillName: 'skill-a', score: 90 }],
},
];
const rankings = fuseWithRRF(inputs);
expect(rankings[0].ranks).toHaveLength(2);
expect(rankings[0].ranks.map((r) => r.source)).toContain('vector');
expect(rankings[0].ranks.map((r) => r.source)).toContain('keyword');
});
it('should handle skills appearing in only one ranker', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [{ skillName: 'skill-a', score: 0.9 }],
},
{
source: 'keyword',
results: [{ skillName: 'skill-b', score: 90 }],
},
];
const rankings = fuseWithRRF(inputs);
expect(rankings).toHaveLength(2);
const skillAInfo = rankings.find((r) => r.skillName === 'skill-a');
const skillBInfo = rankings.find((r) => r.skillName === 'skill-b');
expect(skillAInfo?.ranks).toHaveLength(1);
expect(skillBInfo?.ranks).toHaveLength(1);
});
});
describe('normalizeScores', () => {
it('should normalize scores to 0-1 range', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 100 },
{ skillName: 'b', score: 50 },
{ skillName: 'c', score: 0 },
];
const normalized = normalizeScores(results);
expect(normalized[0].score).toBe(1);
expect(normalized[1].score).toBe(0.5);
expect(normalized[2].score).toBe(0);
});
it('should handle all same scores', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 50 },
{ skillName: 'b', score: 50 },
];
const normalized = normalizeScores(results);
expect(normalized[0].score).toBe(1);
expect(normalized[1].score).toBe(1);
});
it('should return empty array for empty input', () => {
const normalized = normalizeScores([]);
expect(normalized).toEqual([]);
});
});
describe('weightedCombine', () => {
it('should combine results with weights', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [
{ skillName: 'a', score: 100 },
{ skillName: 'b', score: 50 },
],
},
{
source: 'keyword',
results: [
{ skillName: 'b', score: 100 },
{ skillName: 'a', score: 50 },
],
},
];
const combined = weightedCombine(inputs, { vector: 0.6, keyword: 0.4 });
expect(combined).toHaveLength(2);
const skillA = combined.find((r) => r.skillName === 'a')!;
const skillB = combined.find((r) => r.skillName === 'b')!;
expect(skillA.score).toBeCloseTo(0.6 * 1 + 0.4 * 0, 5);
expect(skillB.score).toBeCloseTo(0.6 * 0 + 0.4 * 1, 5);
});
it('should default to weight 1 for unknown sources', () => {
const inputs: RRFInput[] = [
{
source: 'unknown',
results: [{ skillName: 'a', score: 100 }],
},
];
const combined = weightedCombine(inputs, {});
expect(combined[0].score).toBe(1);
});
});
describe('applyPositionAwareBlending', () => {
it('should apply different weights based on position', () => {
const retrievalScores = new Map([
['a', 0.9],
['b', 0.8],
['c', 0.7],
['d', 0.6],
]);
const rerankerScores = new Map([
['a', 0.5],
['b', 0.6],
['c', 0.7],
['d', 0.8],
]);
const sortedSkills = ['a', 'b', 'c', 'd'];
const blended = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkills
);
const scoreA = blended.get('a')!;
expect(scoreA).toBeCloseTo(0.9 * 0.75 + 0.5 * 0.25, 5);
const scoreD = blended.get('d')!;
expect(scoreD).toBeCloseTo(0.6 * 0.6 + 0.8 * 0.4, 5);
});
it('should handle missing scores', () => {
const retrievalScores = new Map([['a', 0.9]]);
const rerankerScores = new Map<string, number>();
const sortedSkills = ['a'];
const blended = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkills
);
expect(blended.get('a')).toBeCloseTo(0.9 * 0.75, 5);
});
});
describe('getRankFromScore', () => {
it('should return correct rank for a skill', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 90 },
{ skillName: 'b', score: 80 },
{ skillName: 'c', score: 70 },
];
expect(getRankFromScore('a', results)).toBe(1);
expect(getRankFromScore('b', results)).toBe(2);
expect(getRankFromScore('c', results)).toBe(3);
});
it('should return length+1 for missing skill', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 90 },
{ skillName: 'b', score: 80 },
];
expect(getRankFromScore('missing', results)).toBe(3);
});
});
describe('mergeRankings', () => {
it('should merge primary and secondary rankings with weights', () => {
const primary = [
{ skillName: 'a', rrfScore: 0.1, ranks: [{ source: 'primary', rank: 1 }] },
{ skillName: 'b', rrfScore: 0.05, ranks: [{ source: 'primary', rank: 2 }] },
];
const secondary = [
{ skillName: 'b', rrfScore: 0.1, ranks: [{ source: 'secondary', rank: 1 }] },
{ skillName: 'c', rrfScore: 0.05, ranks: [{ source: 'secondary', rank: 2 }] },
];
const merged = mergeRankings(primary, secondary, 0.7);
expect(merged).toHaveLength(3);
const skillA = merged.find((r) => r.skillName === 'a')!;
const skillB = merged.find((r) => r.skillName === 'b')!;
const skillC = merged.find((r) => r.skillName === 'c')!;
expect(skillA.rrfScore).toBeCloseTo(0.1 * 0.7, 5);
expect(skillB.rrfScore).toBeCloseTo(0.05 * 0.7 + 0.1 * 0.3, 5);
expect(skillC.rrfScore).toBeCloseTo(0.05 * 0.3, 5);
});
});
});
+294
View File
@@ -0,0 +1,294 @@
import type { SkillSummary } from '../recommend/types.js';
import type {
SkillEmbedding,
IndexBuildCallback,
} from './types.js';
import { DEFAULT_CHUNKING_CONFIG, MODEL_REGISTRY } from './types.js';
import { LocalModelManager } from './local-models.js';
export class EmbeddingService {
private modelManager: LocalModelManager;
private model: unknown = null;
private context: unknown = null;
private initialized = false;
private dimensions: number = 768;
constructor(modelManager?: LocalModelManager) {
this.modelManager = modelManager ?? new LocalModelManager();
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
onProgress?.({
phase: 'loading',
current: 0,
total: 1,
message: 'Loading embedding model...',
});
const modelPath = await this.modelManager.ensureEmbedModel(onProgress);
try {
// @ts-ignore - node-llama-cpp is an optional dependency
const llama = await import('node-llama-cpp');
const { getLlama } = llama;
const llamaInstance = await getLlama();
this.model = await llamaInstance.loadModel({ modelPath });
this.context = await (this.model as { createEmbeddingContext: () => Promise<unknown> }).createEmbeddingContext();
const modelInfo = MODEL_REGISTRY.embeddings[
this.modelManager.getConfig().embedModel as keyof typeof MODEL_REGISTRY.embeddings
];
this.dimensions = modelInfo?.dimensions ?? 768;
this.initialized = true;
onProgress?.({
phase: 'loading',
current: 1,
total: 1,
message: 'Embedding model loaded successfully',
});
} catch (error) {
if (
error instanceof Error &&
error.message.includes("Cannot find package 'node-llama-cpp'")
) {
throw new Error(
'node-llama-cpp is not installed. Install it with: pnpm add node-llama-cpp'
);
}
throw error;
}
}
async embed(text: string): Promise<Float32Array> {
if (!this.initialized || !this.context) {
throw new Error('EmbeddingService not initialized. Call initialize() first.');
}
const ctx = this.context as {
getEmbeddingFor(text: string): Promise<{ vector: number[] }>;
};
const result = await ctx.getEmbeddingFor(text);
return new Float32Array(result.vector);
}
async embedBatch(texts: string[]): Promise<Float32Array[]> {
const results: Float32Array[] = [];
for (const text of texts) {
results.push(await this.embed(text));
}
return results;
}
async embedSkill(skill: SkillSummary): Promise<SkillEmbedding> {
const textContent = this.buildSkillText(skill);
const vector = await this.embed(textContent);
return {
skillName: skill.name,
vector,
textContent,
generatedAt: new Date().toISOString(),
};
}
async embedSkillWithChunks(
skill: SkillSummary,
fullContent?: string
): Promise<SkillEmbedding> {
const textContent = this.buildSkillText(skill);
const mainVector = await this.embed(textContent);
const chunks = fullContent ? this.chunkText(fullContent) : undefined;
let embeddedChunks: SkillEmbedding['chunks'] | undefined;
if (chunks && chunks.length > 0) {
embeddedChunks = [];
for (const chunk of chunks) {
const chunkVector = await this.embed(chunk.content);
embeddedChunks.push({
content: chunk.content,
vector: chunkVector,
startLine: chunk.startLine,
endLine: chunk.endLine,
});
}
}
return {
skillName: skill.name,
vector: mainVector,
textContent,
chunks: embeddedChunks,
generatedAt: new Date().toISOString(),
};
}
async embedSkills(
skills: SkillSummary[],
onProgress?: IndexBuildCallback
): Promise<SkillEmbedding[]> {
await this.initialize(onProgress);
const embeddings: SkillEmbedding[] = [];
const total = skills.length;
for (let i = 0; i < skills.length; i++) {
const skill = skills[i];
onProgress?.({
phase: 'embedding',
current: i + 1,
total,
skillName: skill.name,
message: `Embedding skill ${i + 1}/${total}: ${skill.name}`,
});
const embedding = await this.embedSkill(skill);
embeddings.push(embedding);
}
onProgress?.({
phase: 'complete',
current: total,
total,
message: `Embedded ${total} skills`,
});
return embeddings;
}
private buildSkillText(skill: SkillSummary): string {
const parts: string[] = [skill.name];
if (skill.description) {
parts.push(skill.description);
}
if (skill.tags && skill.tags.length > 0) {
parts.push(skill.tags.join(' '));
}
if (skill.compatibility) {
if (skill.compatibility.frameworks?.length) {
parts.push(skill.compatibility.frameworks.join(' '));
}
if (skill.compatibility.languages?.length) {
parts.push(skill.compatibility.languages.join(' '));
}
if (skill.compatibility.libraries?.length) {
parts.push(skill.compatibility.libraries.join(' '));
}
}
return parts.join(' ').toLowerCase();
}
private chunkText(
text: string,
config = DEFAULT_CHUNKING_CONFIG
): { content: string; startLine: number; endLine: number }[] {
const lines = text.split('\n');
const chunks: { content: string; startLine: number; endLine: number }[] = [];
const avgCharsPerToken = 4;
const maxCharsPerChunk = config.maxTokens * avgCharsPerToken;
const overlapChars = Math.floor(maxCharsPerChunk * (config.overlapPercent / 100));
let currentChunk: string[] = [];
let currentChars = 0;
let startLine = 0;
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const lineChars = line.length + 1;
if (currentChars + lineChars > maxCharsPerChunk && currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({
content,
startLine,
endLine: i - 1,
});
}
const overlapLines: string[] = [];
let overlapCharsCount = 0;
for (let j = currentChunk.length - 1; j >= 0 && overlapCharsCount < overlapChars; j--) {
overlapLines.unshift(currentChunk[j]);
overlapCharsCount += currentChunk[j].length + 1;
}
currentChunk = overlapLines;
currentChars = overlapCharsCount;
startLine = Math.max(0, i - overlapLines.length);
}
currentChunk.push(line);
currentChars += lineChars;
}
if (currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({
content,
startLine,
endLine: lines.length - 1,
});
}
}
return chunks;
}
cosineSimilarity(a: Float32Array, b: Float32Array): number {
if (a.length !== b.length) {
throw new Error(`Vector dimensions mismatch: ${a.length} vs ${b.length}`);
}
let dotProduct = 0;
let normA = 0;
let normB = 0;
for (let i = 0; i < a.length; i++) {
dotProduct += a[i] * b[i];
normA += a[i] * a[i];
normB += b[i] * b[i];
}
const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
if (magnitude === 0) return 0;
return dotProduct / magnitude;
}
getDimensions(): number {
return this.dimensions;
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
if (this.context && typeof (this.context as { dispose?: () => void }).dispose === 'function') {
(this.context as { dispose: () => void }).dispose();
}
if (this.model && typeof (this.model as { dispose?: () => void }).dispose === 'function') {
(this.model as { dispose: () => void }).dispose();
}
this.context = null;
this.model = null;
this.initialized = false;
}
}
export function createEmbeddingService(modelManager?: LocalModelManager): EmbeddingService {
return new EmbeddingService(modelManager);
}
+236
View File
@@ -0,0 +1,236 @@
import type { ExpandedQuery, IndexBuildCallback } from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
import { LocalModelManager } from './local-models.js';
interface CacheEntry {
query: ExpandedQuery;
timestamp: number;
}
const expansionCache = new Map<string, CacheEntry>();
export class QueryExpander {
private modelManager: LocalModelManager;
private model: unknown = null;
private context: unknown = null;
private initialized = false;
private cacheTtlMs: number;
constructor(modelManager?: LocalModelManager, cacheTtlMs?: number) {
this.modelManager = modelManager ?? new LocalModelManager();
this.cacheTtlMs = cacheTtlMs ?? DEFAULT_HYBRID_CONFIG.expansionCacheTtlMs;
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
onProgress?.({
phase: 'loading',
current: 0,
total: 1,
message: 'Loading LLM model for query expansion...',
});
const modelPath = await this.modelManager.ensureLlmModel(onProgress);
try {
// @ts-ignore - node-llama-cpp is an optional dependency
const llamaModule = await import('node-llama-cpp');
const { getLlama, LlamaChatSession } = llamaModule;
const llama = await getLlama();
this.model = await llama.loadModel({ modelPath });
const ctx = await (this.model as { createContext: (opts?: { contextSize?: number }) => Promise<{ getSequence: () => unknown }> }).createContext({ contextSize: 2048 });
this.context = new LlamaChatSession({ contextSequence: ctx.getSequence() as never });
this.initialized = true;
onProgress?.({
phase: 'loading',
current: 1,
total: 1,
message: 'LLM model loaded successfully',
});
} catch (error) {
if (
error instanceof Error &&
error.message.includes("Cannot find package 'node-llama-cpp'")
) {
throw new Error(
'node-llama-cpp is not installed. Install it with: pnpm add node-llama-cpp'
);
}
throw error;
}
}
async expand(query: string, maxVariations: number = 3): Promise<ExpandedQuery> {
const cached = this.getFromCache(query);
if (cached) {
return cached;
}
if (!this.initialized) {
return this.expandWithoutLLM(query);
}
try {
const variations = await this.generateVariations(query, maxVariations);
const weights = [2.0, ...variations.map(() => 1.0)];
const expanded: ExpandedQuery = {
original: query,
variations,
weights,
};
this.addToCache(query, expanded);
return expanded;
} catch {
return this.expandWithoutLLM(query);
}
}
private async generateVariations(query: string, maxVariations: number): Promise<string[]> {
const session = this.context as {
prompt(text: string): Promise<string>;
};
const prompt = `Generate ${maxVariations} alternative search queries for finding software development skills related to: "${query}"
Rules:
- Each alternative should use different terminology but capture the same intent
- Keep each alternative concise (2-5 words)
- Focus on technical terms and synonyms
- Output only the alternatives, one per line, no numbering
Example:
Query: "auth for react"
Alternatives:
authentication react
login react hooks
OAuth react integration
Query: "${query}"
Alternatives:`;
const response = await session.prompt(prompt);
const variations = response
.split('\n')
.map((line) => line.trim())
.filter((line) => line.length > 0 && line.length < 100)
.filter((line) => !line.startsWith('-') && !line.match(/^\d+\./))
.slice(0, maxVariations);
return variations;
}
private expandWithoutLLM(query: string): ExpandedQuery {
const variations: string[] = [];
const queryLower = query.toLowerCase();
const synonyms: Record<string, string[]> = {
auth: ['authentication', 'login', 'oauth', 'jwt'],
authentication: ['auth', 'login', 'oauth'],
login: ['auth', 'authentication', 'signin'],
api: ['rest', 'endpoint', 'http', 'graphql'],
rest: ['api', 'http', 'endpoint'],
db: ['database', 'sql', 'storage'],
database: ['db', 'sql', 'data storage'],
test: ['testing', 'unit test', 'spec'],
testing: ['test', 'unit test', 'e2e'],
ui: ['user interface', 'frontend', 'component'],
frontend: ['ui', 'client', 'browser'],
backend: ['server', 'api', 'service'],
form: ['input', 'validation', 'submit'],
validation: ['form validation', 'input check', 'verify'],
state: ['state management', 'store', 'data flow'],
animation: ['motion', 'transition', 'animate'],
style: ['styling', 'css', 'design'],
css: ['style', 'styling', 'tailwind'],
};
const terms = queryLower.split(/\s+/);
for (const term of terms) {
const termSynonyms = synonyms[term];
if (termSynonyms) {
for (const syn of termSynonyms.slice(0, 2)) {
const variation = query.replace(new RegExp(term, 'i'), syn);
if (variation !== query && !variations.includes(variation)) {
variations.push(variation);
}
}
}
}
const limitedVariations = variations.slice(0, 3);
const weights = [2.0, ...limitedVariations.map(() => 1.0)];
return {
original: query,
variations: limitedVariations,
weights,
};
}
private getFromCache(query: string): ExpandedQuery | null {
const entry = expansionCache.get(query.toLowerCase());
if (!entry) return null;
const now = Date.now();
if (now - entry.timestamp > this.cacheTtlMs) {
expansionCache.delete(query.toLowerCase());
return null;
}
return entry.query;
}
private addToCache(query: string, expanded: ExpandedQuery): void {
const maxCacheSize = 100;
if (expansionCache.size >= maxCacheSize) {
const oldestKey = expansionCache.keys().next().value;
if (oldestKey) {
expansionCache.delete(oldestKey);
}
}
expansionCache.set(query.toLowerCase(), {
query: expanded,
timestamp: Date.now(),
});
}
clearCache(): void {
expansionCache.clear();
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
if (this.context && typeof (this.context as { dispose?: () => void }).dispose === 'function') {
(this.context as { dispose: () => void }).dispose();
}
if (this.model && typeof (this.model as { dispose?: () => void }).dispose === 'function') {
(this.model as { dispose: () => void }).dispose();
}
this.context = null;
this.model = null;
this.initialized = false;
}
}
export function createQueryExpander(
modelManager?: LocalModelManager,
cacheTtlMs?: number
): QueryExpander {
return new QueryExpander(modelManager, cacheTtlMs);
}
export function expandQuerySimple(query: string): ExpandedQuery {
const expander = new QueryExpander();
return expander['expandWithoutLLM'](query);
}
+384
View File
@@ -0,0 +1,384 @@
import type { SkillSummary, SkillIndex } from '../recommend/types.js';
import type {
HybridSearchOptions,
HybridSearchResult,
HybridSearchResponse,
ExpandedQuery,
IndexBuildCallback,
RerankerInput,
RerankerOutput,
LocalModelConfig,
} from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
import { EmbeddingService, createEmbeddingService } from './embeddings.js';
import { VectorStore, createVectorStore } from './vector-store.js';
import { QueryExpander, createQueryExpander } from './expansion.js';
import { LocalModelManager } from './local-models.js';
import {
fuseWithRRF,
applyPositionAwareBlending,
type RankerResult,
type RRFInput,
} from './rrf.js';
import { RecommendationEngine } from '../recommend/engine.js';
export class HybridSearchPipeline {
private embeddingService: EmbeddingService;
private vectorStore: VectorStore;
private queryExpander: QueryExpander;
private modelManager: LocalModelManager;
private recommendationEngine: RecommendationEngine;
private initialized = false;
private skillsMap: Map<string, SkillSummary> = new Map();
constructor(config: Partial<LocalModelConfig> = {}) {
this.modelManager = new LocalModelManager(config);
this.embeddingService = createEmbeddingService(this.modelManager);
this.vectorStore = createVectorStore(undefined, this.embeddingService);
this.queryExpander = createQueryExpander(this.modelManager);
this.recommendationEngine = new RecommendationEngine();
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
await this.vectorStore.initialize();
this.initialized = true;
onProgress?.({
phase: 'complete',
current: 1,
total: 1,
message: 'Hybrid search pipeline initialized',
});
}
async buildIndex(
skills: SkillSummary[],
onProgress?: IndexBuildCallback
): Promise<void> {
await this.initialize(onProgress);
this.skillsMap.clear();
for (const skill of skills) {
this.skillsMap.set(skill.name, skill);
}
const index: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills,
sources: [],
};
this.recommendationEngine.loadIndex(index);
try {
await this.embeddingService.initialize(onProgress);
const embeddings = await this.embeddingService.embedSkills(skills, onProgress);
await this.vectorStore.storeBatch(embeddings, onProgress);
onProgress?.({
phase: 'complete',
current: skills.length,
total: skills.length,
message: `Indexed ${skills.length} skills with embeddings`,
});
} catch {
// Embeddings not available - will use keyword-only search
onProgress?.({
phase: 'complete',
current: skills.length,
total: skills.length,
message: `Indexed ${skills.length} skills (keyword-only, embeddings unavailable)`,
});
}
}
async search(options: HybridSearchOptions): Promise<HybridSearchResponse> {
const startTime = Date.now();
const timing: HybridSearchResponse['timing'] = { totalMs: 0 };
const stats: HybridSearchResponse['stats'] = {
candidatesFromVector: 0,
candidatesFromKeyword: 0,
totalMerged: 0,
reranked: 0,
};
await this.initialize();
const {
query,
limit = 10,
enableExpansion = false,
enableReranking = false,
rrfK = DEFAULT_HYBRID_CONFIG.rrfK,
positionAwareBlending = true,
} = options;
let expandedQuery: ExpandedQuery | undefined;
const searchQueries: string[] = [query];
if (enableExpansion) {
try {
expandedQuery = await this.queryExpander.expand(query);
searchQueries.push(...expandedQuery.variations);
} catch {
expandedQuery = {
original: query,
variations: [],
weights: [2.0],
};
}
}
const rankerInputs: RRFInput[] = [];
const embeddingStart = Date.now();
let queryVector: Float32Array | null = null;
try {
if (this.embeddingService.isInitialized()) {
queryVector = await this.embeddingService.embed(query);
}
} catch {
}
timing.embeddingMs = Date.now() - embeddingStart;
if (queryVector) {
const vectorStart = Date.now();
const vectorResults = await this.vectorStore.search(queryVector, limit * 3);
timing.vectorSearchMs = Date.now() - vectorStart;
const vectorRankerResults: RankerResult[] = vectorResults.map((r) => ({
skillName: r.skillName,
score: r.similarity,
}));
rankerInputs.push({
source: 'vector',
results: vectorRankerResults,
});
stats.candidatesFromVector = vectorResults.length;
}
const keywordStart = Date.now();
const keywordResults: RankerResult[] = [];
for (let i = 0; i < searchQueries.length; i++) {
const searchQuery = searchQueries[i];
const weight = expandedQuery?.weights[i] ?? 1;
const results = this.recommendationEngine.search({
query: searchQuery,
limit: limit * 3,
semantic: true,
});
for (const result of results) {
const existing = keywordResults.find(
(r) => r.skillName === result.skill.name
);
if (existing) {
existing.score = Math.max(existing.score, result.relevance * weight);
} else {
keywordResults.push({
skillName: result.skill.name,
score: result.relevance * weight,
});
}
}
}
timing.keywordSearchMs = Date.now() - keywordStart;
rankerInputs.push({
source: 'keyword',
results: keywordResults,
});
stats.candidatesFromKeyword = keywordResults.length;
const fusionStart = Date.now();
const rrfRankings = fuseWithRRF(rankerInputs, rrfK);
timing.fusionMs = Date.now() - fusionStart;
stats.totalMerged = rrfRankings.length;
let finalScores = new Map<string, number>();
for (const ranking of rrfRankings) {
finalScores.set(ranking.skillName, ranking.rrfScore);
}
if (enableReranking && rrfRankings.length > 0) {
const rerankStart = Date.now();
const topCandidates = rrfRankings.slice(0, DEFAULT_HYBRID_CONFIG.rerankTopN);
const rerankerInputs: RerankerInput[] = topCandidates
.map((r) => {
const skill = this.skillsMap.get(r.skillName);
if (!skill) return null;
return {
query,
skillName: r.skillName,
skillDescription: skill.description ?? '',
skillTags: skill.tags ?? [],
};
})
.filter((r): r is RerankerInput => r !== null);
const rerankerOutputs = await this.rerank(rerankerInputs);
timing.rerankingMs = Date.now() - rerankStart;
stats.reranked = rerankerOutputs.length;
if (positionAwareBlending && rerankerOutputs.length > 0) {
const retrievalScores = new Map<string, number>();
const maxRrfScore = Math.max(...rrfRankings.map((r) => r.rrfScore));
for (const ranking of topCandidates) {
retrievalScores.set(
ranking.skillName,
ranking.rrfScore / (maxRrfScore || 1)
);
}
const rerankerScores = new Map<string, number>();
const maxRerankerScore = Math.max(...rerankerOutputs.map((r) => r.score));
for (const output of rerankerOutputs) {
rerankerScores.set(
output.skillName,
output.score / (maxRerankerScore || 1)
);
}
const sortedSkillNames = topCandidates.map((r) => r.skillName);
const blendedScores = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkillNames
);
for (const [skillName, score] of blendedScores) {
finalScores.set(skillName, score);
}
}
}
const sortedResults = Array.from(finalScores.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, limit);
const vectorInput = rankerInputs.find((r) => r.source === 'vector');
const keywordInput = rankerInputs.find((r) => r.source === 'keyword');
const hybridResults: HybridSearchResult[] = [];
for (const [skillName, hybridScore] of sortedResults) {
const skill = this.skillsMap.get(skillName);
if (!skill) continue;
hybridResults.push({
skill,
relevance: Math.round(hybridScore * 100),
hybridScore,
vectorSimilarity: vectorInput?.results.find((r) => r.skillName === skillName)?.score,
keywordScore: keywordInput?.results.find((r) => r.skillName === skillName)?.score,
rrfScore: rrfRankings.find((r) => r.skillName === skillName)?.rrfScore,
matchedTerms: [],
expandedTerms: expandedQuery?.variations,
});
}
timing.totalMs = Date.now() - startTime;
return {
results: hybridResults,
query: {
original: query,
expanded: expandedQuery,
},
timing,
stats,
};
}
private async rerank(inputs: RerankerInput[]): Promise<RerankerOutput[]> {
const outputs: RerankerOutput[] = [];
for (const input of inputs) {
const baseScore =
(input.skillDescription.toLowerCase().includes(input.query.toLowerCase())
? 0.5
: 0) +
(input.skillTags.some((t) =>
t.toLowerCase().includes(input.query.toLowerCase())
)
? 0.3
: 0) +
(input.skillName.toLowerCase().includes(input.query.toLowerCase())
? 0.2
: 0);
outputs.push({
skillName: input.skillName,
score: Math.min(1, baseScore + 0.3),
});
}
return outputs;
}
loadSkillsIndex(index: SkillIndex): void {
this.skillsMap.clear();
for (const skill of index.skills) {
this.skillsMap.set(skill.name, skill);
}
this.recommendationEngine.loadIndex(index);
}
getStats(): {
vectorStore: ReturnType<VectorStore['getStats']>;
initialized: boolean;
skillCount: number;
} {
return {
vectorStore: this.vectorStore.getStats(),
initialized: this.initialized,
skillCount: this.skillsMap.size,
};
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
await this.embeddingService.dispose();
await this.queryExpander.dispose();
await this.vectorStore.close();
this.initialized = false;
}
}
export function createHybridSearchPipeline(
config?: Partial<LocalModelConfig>
): HybridSearchPipeline {
return new HybridSearchPipeline(config);
}
export async function hybridSearch(
skills: SkillSummary[],
query: string,
options: Partial<HybridSearchOptions> = {}
): Promise<HybridSearchResponse> {
const pipeline = createHybridSearchPipeline();
try {
await pipeline.buildIndex(skills);
return await pipeline.search({
query,
...options,
});
} finally {
await pipeline.dispose();
}
}
+7
View File
@@ -0,0 +1,7 @@
export * from './types.js';
export * from './local-models.js';
export * from './embeddings.js';
export * from './vector-store.js';
export * from './rrf.js';
export * from './expansion.js';
export * from './hybrid.js';
+243
View File
@@ -0,0 +1,243 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { createWriteStream } from 'node:fs';
import type { LocalModelConfig, IndexBuildCallback } from './types.js';
import { MODEL_REGISTRY } from './types.js';
const DEFAULT_MODEL_DIR = path.join(os.homedir(), '.skillkit', 'models');
type EmbeddingModelName = keyof typeof MODEL_REGISTRY.embeddings;
type LlmModelName = keyof typeof MODEL_REGISTRY.llm;
interface ModelInfo {
url: string;
size: number;
description: string;
dimensions?: number;
}
export class LocalModelManager {
private config: Required<LocalModelConfig>;
private embedModelPath: string | null = null;
private llmModelPath: string | null = null;
constructor(config: Partial<LocalModelConfig> = {}) {
this.config = {
embedModel: config.embedModel ?? 'nomic-embed-text-v1.5.Q4_K_M.gguf',
llmModel: config.llmModel ?? 'gemma-2b-it-Q4_K_M.gguf',
modelDir: config.modelDir ?? DEFAULT_MODEL_DIR,
autoDownload: config.autoDownload ?? true,
gpuLayers: config.gpuLayers ?? 0,
};
}
async ensureModelsDirectory(): Promise<void> {
if (!fs.existsSync(this.config.modelDir)) {
await fs.promises.mkdir(this.config.modelDir, { recursive: true });
}
}
getEmbedModelPath(): string {
return path.join(this.config.modelDir, this.config.embedModel);
}
getLlmModelPath(): string {
return path.join(this.config.modelDir, this.config.llmModel);
}
isEmbedModelAvailable(): boolean {
return fs.existsSync(this.getEmbedModelPath());
}
isLlmModelAvailable(): boolean {
return fs.existsSync(this.getLlmModelPath());
}
private getModelInfo(modelType: 'embed' | 'llm', modelName: string): ModelInfo | undefined {
if (modelType === 'embed') {
return MODEL_REGISTRY.embeddings[modelName as EmbeddingModelName] as ModelInfo | undefined;
}
return MODEL_REGISTRY.llm[modelName as LlmModelName] as ModelInfo | undefined;
}
async downloadModel(
modelType: 'embed' | 'llm',
onProgress?: IndexBuildCallback
): Promise<string> {
await this.ensureModelsDirectory();
const modelName = modelType === 'embed' ? this.config.embedModel : this.config.llmModel;
const modelPath = modelType === 'embed' ? this.getEmbedModelPath() : this.getLlmModelPath();
if (fs.existsSync(modelPath)) {
return modelPath;
}
const modelInfo = this.getModelInfo(modelType, modelName);
if (!modelInfo) {
const availableModels = modelType === 'embed'
? Object.keys(MODEL_REGISTRY.embeddings)
: Object.keys(MODEL_REGISTRY.llm);
throw new Error(`Unknown model: ${modelName}. Available models: ${availableModels.join(', ')}`);
}
onProgress?.({
phase: 'downloading',
current: 0,
total: modelInfo.size,
message: `Downloading ${modelName}...`,
});
const response = await fetch(modelInfo.url);
if (!response.ok) {
throw new Error(`Failed to download model: ${response.statusText}`);
}
const contentLength = Number(response.headers.get('content-length')) || modelInfo.size;
let downloaded = 0;
const tempPath = `${modelPath}.tmp`;
const fileStream = createWriteStream(tempPath);
const reader = response.body?.getReader();
if (!reader) {
throw new Error('Failed to get response body reader');
}
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
const canContinue = fileStream.write(Buffer.from(value));
if (!canContinue) {
await new Promise<void>((resolve) => fileStream.once('drain', resolve));
}
downloaded += value.length;
onProgress?.({
phase: 'downloading',
current: downloaded,
total: contentLength,
message: `Downloading ${modelName}: ${Math.round((downloaded / contentLength) * 100)}%`,
});
}
fileStream.end();
await new Promise<void>((resolve, reject) => {
fileStream.on('finish', resolve);
fileStream.on('error', reject);
});
await fs.promises.rename(tempPath, modelPath);
return modelPath;
} catch (error) {
if (fs.existsSync(tempPath)) {
await fs.promises.unlink(tempPath);
}
throw error;
}
}
async ensureEmbedModel(onProgress?: IndexBuildCallback): Promise<string> {
if (this.embedModelPath && fs.existsSync(this.embedModelPath)) {
return this.embedModelPath;
}
if (!this.isEmbedModelAvailable()) {
if (!this.config.autoDownload) {
throw new Error(
`Embedding model not found at ${this.getEmbedModelPath()}. ` +
'Set autoDownload: true or manually download the model.'
);
}
this.embedModelPath = await this.downloadModel('embed', onProgress);
} else {
this.embedModelPath = this.getEmbedModelPath();
}
return this.embedModelPath;
}
async ensureLlmModel(onProgress?: IndexBuildCallback): Promise<string> {
if (this.llmModelPath && fs.existsSync(this.llmModelPath)) {
return this.llmModelPath;
}
if (!this.isLlmModelAvailable()) {
if (!this.config.autoDownload) {
throw new Error(
`LLM model not found at ${this.getLlmModelPath()}. ` +
'Set autoDownload: true or manually download the model.'
);
}
this.llmModelPath = await this.downloadModel('llm', onProgress);
} else {
this.llmModelPath = this.getLlmModelPath();
}
return this.llmModelPath;
}
async ensureAllModels(onProgress?: IndexBuildCallback): Promise<{
embedModel: string;
llmModel: string;
}> {
const embedModel = await this.ensureEmbedModel(onProgress);
const llmModel = await this.ensureLlmModel(onProgress);
return { embedModel, llmModel };
}
getPublicModelInfo(modelType: 'embed' | 'llm'): {
name: string;
path: string;
available: boolean;
size: number;
description: string;
} {
const modelName = modelType === 'embed' ? this.config.embedModel : this.config.llmModel;
const modelPath = modelType === 'embed' ? this.getEmbedModelPath() : this.getLlmModelPath();
const modelInfo = this.getModelInfo(modelType, modelName);
return {
name: modelName,
path: modelPath,
available: fs.existsSync(modelPath),
size: modelInfo?.size ?? 0,
description: modelInfo?.description ?? 'Unknown model',
};
}
async clearModels(): Promise<void> {
const embedPath = this.getEmbedModelPath();
const llmPath = this.getLlmModelPath();
if (fs.existsSync(embedPath)) {
await fs.promises.unlink(embedPath);
}
if (fs.existsSync(llmPath)) {
await fs.promises.unlink(llmPath);
}
this.embedModelPath = null;
this.llmModelPath = null;
}
getConfig(): Required<LocalModelConfig> {
return { ...this.config };
}
}
export function formatBytes(bytes: number): string {
if (bytes === 0) return '0 Bytes';
const k = 1024;
const sizes = ['Bytes', 'KB', 'MB', 'GB'];
const i = Math.floor(Math.log(bytes) / Math.log(k));
return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
}
export function getDefaultModelDir(): string {
return DEFAULT_MODEL_DIR;
}
+177
View File
@@ -0,0 +1,177 @@
import type { RRFRanking } from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
export interface RankerResult {
skillName: string;
score: number;
}
export interface RRFInput {
source: string;
results: RankerResult[];
}
export function computeRRFScore(ranks: number[], k: number = DEFAULT_HYBRID_CONFIG.rrfK): number {
return ranks.reduce((sum, rank) => sum + 1 / (k + rank), 0);
}
export function fuseWithRRF(
rankerInputs: RRFInput[],
k: number = DEFAULT_HYBRID_CONFIG.rrfK
): RRFRanking[] {
const skillRanks = new Map<string, { source: string; rank: number }[]>();
for (const input of rankerInputs) {
const sortedResults = [...input.results].sort((a, b) => b.score - a.score);
for (let i = 0; i < sortedResults.length; i++) {
const result = sortedResults[i];
const rank = i + 1;
if (!skillRanks.has(result.skillName)) {
skillRanks.set(result.skillName, []);
}
skillRanks.get(result.skillName)!.push({
source: input.source,
rank,
});
}
}
const rankings: RRFRanking[] = [];
for (const [skillName, ranks] of skillRanks) {
const rankValues = ranks.map((r) => r.rank);
const rrfScore = computeRRFScore(rankValues, k);
rankings.push({
skillName,
rrfScore,
ranks,
});
}
rankings.sort((a, b) => b.rrfScore - a.rrfScore);
return rankings;
}
export function normalizeScores(results: RankerResult[]): RankerResult[] {
if (results.length === 0) return [];
const maxScore = Math.max(...results.map((r) => r.score));
const minScore = Math.min(...results.map((r) => r.score));
const range = maxScore - minScore;
if (range === 0) {
return results.map((r) => ({ ...r, score: 1 }));
}
return results.map((r) => ({
...r,
score: (r.score - minScore) / range,
}));
}
export function weightedCombine(
results: RRFInput[],
weights: Record<string, number>
): RankerResult[] {
const combinedScores = new Map<string, number>();
for (const input of results) {
const weight = weights[input.source] ?? 1;
const normalizedResults = normalizeScores(input.results);
for (const result of normalizedResults) {
const current = combinedScores.get(result.skillName) ?? 0;
combinedScores.set(result.skillName, current + result.score * weight);
}
}
return Array.from(combinedScores, ([skillName, score]) => ({ skillName, score }))
.sort((a, b) => b.score - a.score);
}
export function applyPositionAwareBlending(
retrievalScores: Map<string, number>,
rerankerScores: Map<string, number>,
sortedSkillNames: string[],
config = DEFAULT_HYBRID_CONFIG.positionBlending
): Map<string, number> {
const blendedScores = new Map<string, number>();
for (let i = 0; i < sortedSkillNames.length; i++) {
const skillName = sortedSkillNames[i];
const rank = i + 1;
let weights: { retrieval: number; reranker: number };
if (rank <= 3) {
weights = config.top3;
} else if (rank <= 10) {
weights = config.top10;
} else {
weights = config.rest;
}
const retrievalScore = retrievalScores.get(skillName) ?? 0;
const rerankerScore = rerankerScores.get(skillName) ?? 0;
const blendedScore =
retrievalScore * weights.retrieval + rerankerScore * weights.reranker;
blendedScores.set(skillName, blendedScore);
}
return blendedScores;
}
export function getRankFromScore(
skillName: string,
rankedResults: RankerResult[]
): number {
const sortedResults = [...rankedResults].sort((a, b) => b.score - a.score);
const index = sortedResults.findIndex((r) => r.skillName === skillName);
return index === -1 ? sortedResults.length + 1 : index + 1;
}
export function mergeRankings(
primaryRankings: RRFRanking[],
secondaryRankings: RRFRanking[],
primaryWeight: number = 0.7
): RRFRanking[] {
const secondaryWeight = 1 - primaryWeight;
const mergedScores = new Map<string, { score: number; ranks: { source: string; rank: number }[] }>();
for (const ranking of primaryRankings) {
mergedScores.set(ranking.skillName, {
score: ranking.rrfScore * primaryWeight,
ranks: [...ranking.ranks],
});
}
for (const ranking of secondaryRankings) {
const existing = mergedScores.get(ranking.skillName);
if (existing) {
existing.score += ranking.rrfScore * secondaryWeight;
existing.ranks = [...existing.ranks, ...ranking.ranks];
} else {
mergedScores.set(ranking.skillName, {
score: ranking.rrfScore * secondaryWeight,
ranks: [...ranking.ranks],
});
}
}
const merged: RRFRanking[] = [];
for (const [skillName, data] of mergedScores) {
merged.push({
skillName,
rrfScore: data.score,
ranks: data.ranks,
});
}
merged.sort((a, b) => b.rrfScore - a.rrfScore);
return merged;
}
+177
View File
@@ -0,0 +1,177 @@
import { z } from 'zod';
import type { SearchResult } from '../recommend/types.js';
export const LocalModelConfigSchema = z.object({
embedModel: z.string().default('nomic-embed-text-v1.5.Q4_K_M.gguf'),
llmModel: z.string().default('gemma-2b-it-Q4_K_M.gguf'),
modelDir: z.string().optional(),
autoDownload: z.boolean().default(true),
gpuLayers: z.number().default(0),
});
export type LocalModelConfig = z.infer<typeof LocalModelConfigSchema>;
export const SkillChunkSchema = z.object({
content: z.string(),
startLine: z.number(),
endLine: z.number(),
tokenCount: z.number(),
});
export type SkillChunk = z.infer<typeof SkillChunkSchema>;
export interface SkillEmbedding {
skillName: string;
vector: Float32Array;
textContent: string;
chunks?: {
content: string;
vector: Float32Array;
startLine: number;
endLine: number;
}[];
generatedAt: string;
}
export interface VectorSearchResult {
skillName: string;
similarity: number;
matchedChunk?: {
content: string;
startLine: number;
};
}
export interface ExpandedQuery {
original: string;
variations: string[];
weights: number[];
}
export interface RRFRanking {
skillName: string;
rrfScore: number;
ranks: {
source: string;
rank: number;
}[];
}
export interface HybridSearchOptions {
query: string;
limit?: number;
enableExpansion?: boolean;
enableReranking?: boolean;
semanticWeight?: number;
keywordWeight?: number;
rrfK?: number;
positionAwareBlending?: boolean;
}
export interface HybridSearchResult extends SearchResult {
hybridScore: number;
vectorSimilarity?: number;
keywordScore?: number;
rrfScore?: number;
rerankerScore?: number;
expandedTerms?: string[];
blendingWeights?: {
retrieval: number;
reranker: number;
};
}
export interface HybridSearchResponse {
results: HybridSearchResult[];
query: {
original: string;
expanded?: ExpandedQuery;
};
timing: {
totalMs: number;
embeddingMs?: number;
vectorSearchMs?: number;
keywordSearchMs?: number;
fusionMs?: number;
rerankingMs?: number;
};
stats: {
candidatesFromVector: number;
candidatesFromKeyword: number;
totalMerged: number;
reranked: number;
};
}
export interface EmbeddingServiceStats {
totalSkillsIndexed: number;
totalChunks: number;
indexSizeBytes: number;
lastIndexedAt: string;
modelName: string;
embeddingDimensions: number;
}
export interface VectorStoreConfig {
dbPath: string;
tableName?: string;
dimensions?: number;
}
export interface IndexBuildProgress {
phase: 'downloading' | 'loading' | 'embedding' | 'storing' | 'complete';
current: number;
total: number;
skillName?: string;
message?: string;
}
export type IndexBuildCallback = (progress: IndexBuildProgress) => void;
export const MODEL_REGISTRY = {
embeddings: {
'nomic-embed-text-v1.5.Q4_K_M.gguf': {
url: 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf',
size: 547000000,
dimensions: 768,
description: 'Nomic Embed Text v1.5 - High quality embeddings',
},
},
llm: {
'gemma-2b-it-Q4_K_M.gguf': {
url: 'https://huggingface.co/bartowski/gemma-2-2b-it-GGUF/resolve/main/gemma-2-2b-it-Q4_K_M.gguf',
size: 1500000000,
description: 'Gemma 2 2B Instruct - Fast query expansion and reranking',
},
},
} as const;
export const DEFAULT_CHUNKING_CONFIG = {
maxTokens: 800,
overlapPercent: 15,
minChunkSize: 100,
} as const;
export const DEFAULT_HYBRID_CONFIG = {
rrfK: 60,
semanticWeight: 0.5,
keywordWeight: 0.5,
rerankTopN: 30,
positionBlending: {
top3: { retrieval: 0.75, reranker: 0.25 },
top10: { retrieval: 0.6, reranker: 0.4 },
rest: { retrieval: 0.4, reranker: 0.6 },
},
expansionCacheTtlMs: 5 * 60 * 1000,
} as const;
export interface RerankerInput {
query: string;
skillName: string;
skillDescription: string;
skillTags: string[];
}
export interface RerankerOutput {
skillName: string;
score: number;
reasoning?: string;
}
+510
View File
@@ -0,0 +1,510 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import type {
SkillEmbedding,
VectorSearchResult,
VectorStoreConfig,
EmbeddingServiceStats,
IndexBuildCallback,
} from './types.js';
import { EmbeddingService } from './embeddings.js';
const DEFAULT_DB_PATH = path.join(os.homedir(), '.skillkit', 'search.db');
const DEFAULT_TABLE_NAME = 'skill_embeddings';
const DEFAULT_DIMENSIONS = 768;
export class VectorStore {
private config: Required<VectorStoreConfig>;
private db: unknown = null;
private initialized = false;
private usingSqliteVec = false;
private embeddings: Map<string, SkillEmbedding> = new Map();
private embeddingService: EmbeddingService;
constructor(config: Partial<VectorStoreConfig> = {}, embeddingService?: EmbeddingService) {
const tableName = config.tableName ?? DEFAULT_TABLE_NAME;
if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
throw new Error(`Invalid table name: ${tableName}. Must be a valid SQL identifier.`);
}
this.config = {
dbPath: config.dbPath ?? DEFAULT_DB_PATH,
tableName,
dimensions: config.dimensions ?? DEFAULT_DIMENSIONS,
};
this.embeddingService = embeddingService ?? new EmbeddingService();
}
async initialize(): Promise<void> {
if (this.initialized) return;
const dbDir = path.dirname(this.config.dbPath);
if (!fs.existsSync(dbDir)) {
await fs.promises.mkdir(dbDir, { recursive: true });
}
try {
const BetterSqlite3Module = await import('better-sqlite3');
const BetterSqlite3 = BetterSqlite3Module.default || BetterSqlite3Module;
this.db = new BetterSqlite3(this.config.dbPath);
try {
const sqliteVec = await import('sqlite-vec');
sqliteVec.load(this.db as Parameters<typeof sqliteVec.load>[0]);
this.usingSqliteVec = true;
await this.initializeSqliteVecTables();
} catch {
this.usingSqliteVec = false;
await this.initializeFallbackTables();
}
await this.loadEmbeddingsFromDb();
this.initialized = true;
} catch (error) {
if (
error instanceof Error &&
(error.message.includes("Cannot find package 'better-sqlite3'") ||
error.message.includes("Cannot find module 'better-sqlite3'"))
) {
this.initialized = true;
this.usingSqliteVec = false;
return;
}
throw error;
}
}
private async initializeSqliteVecTables(): Promise<void> {
const db = this.db as {
exec(sql: string): void;
prepare(sql: string): { run(...args: unknown[]): void };
};
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_meta (
skill_name TEXT PRIMARY KEY,
text_content TEXT NOT NULL,
generated_at TEXT NOT NULL,
chunk_count INTEGER DEFAULT 0
)
`);
db.exec(`
CREATE VIRTUAL TABLE IF NOT EXISTS ${this.config.tableName}_vec USING vec0(
skill_name TEXT PRIMARY KEY,
embedding float[${this.config.dimensions}]
)
`);
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_chunks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_name TEXT NOT NULL,
content TEXT NOT NULL,
start_line INTEGER NOT NULL,
end_line INTEGER NOT NULL,
FOREIGN KEY (skill_name) REFERENCES ${this.config.tableName}_meta(skill_name)
)
`);
db.exec(`
CREATE VIRTUAL TABLE IF NOT EXISTS ${this.config.tableName}_chunks_vec USING vec0(
chunk_id INTEGER PRIMARY KEY,
embedding float[${this.config.dimensions}]
)
`);
}
private async initializeFallbackTables(): Promise<void> {
const db = this.db as { exec(sql: string): void };
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName} (
skill_name TEXT PRIMARY KEY,
text_content TEXT NOT NULL,
vector BLOB NOT NULL,
generated_at TEXT NOT NULL
)
`);
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_chunks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_name TEXT NOT NULL,
content TEXT NOT NULL,
vector BLOB NOT NULL,
start_line INTEGER NOT NULL,
end_line INTEGER NOT NULL
)
`);
db.exec(`
CREATE INDEX IF NOT EXISTS idx_${this.config.tableName}_skill
ON ${this.config.tableName}_chunks(skill_name)
`);
}
private async loadEmbeddingsFromDb(): Promise<void> {
if (!this.db) return;
const db = this.db as {
prepare(sql: string): { all(): Array<{
skill_name: string;
text_content: string;
vector?: Buffer;
generated_at: string;
}> };
};
try {
if (this.usingSqliteVec) {
const rows = db.prepare(`
SELECT skill_name, text_content, generated_at
FROM ${this.config.tableName}_meta
`).all();
for (const row of rows) {
this.embeddings.set(row.skill_name, {
skillName: row.skill_name,
textContent: row.text_content,
vector: new Float32Array(this.config.dimensions),
generatedAt: row.generated_at,
});
}
} else {
const rows = db.prepare(`
SELECT skill_name, text_content, vector, generated_at
FROM ${this.config.tableName}
`).all();
for (const row of rows) {
if (row.vector) {
this.embeddings.set(row.skill_name, {
skillName: row.skill_name,
textContent: row.text_content,
vector: new Float32Array(row.vector.buffer),
generatedAt: row.generated_at,
});
}
}
}
} catch {
// Failed to load embeddings from DB - will start with empty in-memory store
}
}
async store(embedding: SkillEmbedding): Promise<void> {
await this.initialize();
this.embeddings.set(embedding.skillName, embedding);
if (!this.db) return;
const db = this.db as {
prepare(sql: string): {
run(...args: unknown[]): { lastInsertRowid?: number };
};
};
if (this.usingSqliteVec) {
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}_meta
(skill_name, text_content, generated_at, chunk_count)
VALUES (?, ?, ?, ?)
`).run(
embedding.skillName,
embedding.textContent,
embedding.generatedAt,
embedding.chunks?.length ?? 0
);
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}_vec
(skill_name, embedding)
VALUES (?, ?)
`).run(embedding.skillName, Buffer.from(embedding.vector.buffer));
if (embedding.chunks) {
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?
`).run(embedding.skillName);
for (const chunk of embedding.chunks) {
const result = db.prepare(`
INSERT INTO ${this.config.tableName}_chunks
(skill_name, content, start_line, end_line)
VALUES (?, ?, ?, ?)
`).run(embedding.skillName, chunk.content, chunk.startLine, chunk.endLine);
const rowId = result.lastInsertRowid ?? 0;
db.prepare(`
INSERT INTO ${this.config.tableName}_chunks_vec
(chunk_id, embedding)
VALUES (?, ?)
`).run(rowId, Buffer.from(chunk.vector.buffer));
}
}
} else {
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}
(skill_name, text_content, vector, generated_at)
VALUES (?, ?, ?, ?)
`).run(
embedding.skillName,
embedding.textContent,
Buffer.from(embedding.vector.buffer),
embedding.generatedAt
);
if (embedding.chunks) {
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?
`).run(embedding.skillName);
for (const chunk of embedding.chunks) {
db.prepare(`
INSERT INTO ${this.config.tableName}_chunks
(skill_name, content, vector, start_line, end_line)
VALUES (?, ?, ?, ?, ?)
`).run(
embedding.skillName,
chunk.content,
Buffer.from(chunk.vector.buffer),
chunk.startLine,
chunk.endLine
);
}
}
}
}
async storeBatch(
embeddings: SkillEmbedding[],
onProgress?: IndexBuildCallback
): Promise<void> {
await this.initialize();
const total = embeddings.length;
for (let i = 0; i < embeddings.length; i++) {
const embedding = embeddings[i];
onProgress?.({
phase: 'storing',
current: i + 1,
total,
skillName: embedding.skillName,
message: `Storing embedding ${i + 1}/${total}: ${embedding.skillName}`,
});
await this.store(embedding);
}
onProgress?.({
phase: 'complete',
current: total,
total,
message: `Stored ${total} embeddings`,
});
}
async search(
queryVector: Float32Array,
limit: number = 10
): Promise<VectorSearchResult[]> {
await this.initialize();
if (this.usingSqliteVec && this.db) {
return this.searchWithSqliteVec(queryVector, limit);
}
return this.searchInMemory(queryVector, limit);
}
private async searchWithSqliteVec(
queryVector: Float32Array,
limit: number
): Promise<VectorSearchResult[]> {
const db = this.db as {
prepare(sql: string): {
all(...args: unknown[]): Array<{ skill_name: string; distance: number }>;
};
};
const rows = db.prepare(`
SELECT skill_name, distance
FROM ${this.config.tableName}_vec
WHERE embedding MATCH ?
ORDER BY distance
LIMIT ?
`).all(Buffer.from(queryVector.buffer), limit);
return rows.map((row) => ({
skillName: row.skill_name,
similarity: 1 - row.distance,
}));
}
private searchInMemory(
queryVector: Float32Array,
limit: number
): VectorSearchResult[] {
const results: VectorSearchResult[] = [];
for (const [skillName, embedding] of this.embeddings) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, embedding.vector);
results.push({ skillName, similarity });
}
results.sort((a, b) => b.similarity - a.similarity);
return results.slice(0, limit);
}
async searchChunks(
queryVector: Float32Array,
limit: number = 10
): Promise<VectorSearchResult[]> {
await this.initialize();
const results: VectorSearchResult[] = [];
for (const [skillName, embedding] of this.embeddings) {
if (!embedding.chunks || embedding.chunks.length === 0) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, embedding.vector);
results.push({ skillName, similarity });
continue;
}
let bestChunk: { similarity: number; content: string; startLine: number } | null = null;
for (const chunk of embedding.chunks) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, chunk.vector);
if (!bestChunk || similarity > bestChunk.similarity) {
bestChunk = {
similarity,
content: chunk.content,
startLine: chunk.startLine,
};
}
}
if (bestChunk) {
results.push({
skillName,
similarity: bestChunk.similarity,
matchedChunk: {
content: bestChunk.content,
startLine: bestChunk.startLine,
},
});
}
}
results.sort((a, b) => b.similarity - a.similarity);
return results.slice(0, limit);
}
has(skillName: string): boolean {
return this.embeddings.has(skillName);
}
get(skillName: string): SkillEmbedding | undefined {
return this.embeddings.get(skillName);
}
async delete(skillName: string): Promise<void> {
await this.initialize();
this.embeddings.delete(skillName);
if (!this.db) return;
const db = this.db as {
prepare(sql: string): { run(...args: unknown[]): void };
};
if (this.usingSqliteVec) {
db.prepare(`DELETE FROM ${this.config.tableName}_meta WHERE skill_name = ?`).run(skillName);
db.prepare(`DELETE FROM ${this.config.tableName}_vec WHERE skill_name = ?`).run(skillName);
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks_vec
WHERE chunk_id IN (
SELECT id FROM ${this.config.tableName}_chunks WHERE skill_name = ?
)
`).run(skillName);
} else {
db.prepare(`DELETE FROM ${this.config.tableName} WHERE skill_name = ?`).run(skillName);
}
db.prepare(`DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?`).run(skillName);
}
async clear(): Promise<void> {
await this.initialize();
this.embeddings.clear();
if (!this.db) return;
const db = this.db as { exec(sql: string): void };
if (this.usingSqliteVec) {
db.exec(`DELETE FROM ${this.config.tableName}_meta`);
db.exec(`DELETE FROM ${this.config.tableName}_vec`);
db.exec(`DELETE FROM ${this.config.tableName}_chunks_vec`);
} else {
db.exec(`DELETE FROM ${this.config.tableName}`);
}
db.exec(`DELETE FROM ${this.config.tableName}_chunks`);
}
getStats(): EmbeddingServiceStats {
let indexSizeBytes = 0;
let totalChunks = 0;
for (const embedding of this.embeddings.values()) {
indexSizeBytes += embedding.vector.byteLength;
indexSizeBytes += embedding.textContent.length * 2;
if (embedding.chunks) {
totalChunks += embedding.chunks.length;
for (const chunk of embedding.chunks) {
indexSizeBytes += chunk.vector.byteLength;
indexSizeBytes += chunk.content.length * 2;
}
}
}
return {
totalSkillsIndexed: this.embeddings.size,
totalChunks,
indexSizeBytes,
lastIndexedAt: new Date().toISOString(),
modelName: 'nomic-embed-text-v1.5',
embeddingDimensions: this.config.dimensions,
};
}
isInitialized(): boolean {
return this.initialized;
}
isUsingSqliteVec(): boolean {
return this.usingSqliteVec;
}
getEmbeddingCount(): number {
return this.embeddings.size;
}
async close(): Promise<void> {
if (this.db && typeof (this.db as { close?: () => void }).close === 'function') {
(this.db as { close: () => void }).close();
}
this.db = null;
this.initialized = false;
}
}
export function createVectorStore(
config?: Partial<VectorStoreConfig>,
embeddingService?: EmbeddingService
): VectorStore {
return new VectorStore(config, embeddingService);
}
+4 -3
View File
@@ -1,5 +1,5 @@
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, basename } from 'node:path';
import { join, basename, resolve, sep } from 'node:path';
import { parse as parseYaml } from 'yaml';
import { SkillFrontmatter, SkillMetadata, type Skill, type SkillLocation } from './types.js';
@@ -391,6 +391,7 @@ export function validateSkill(skillPath: string): { valid: boolean; errors: stri
}
export function isPathInside(child: string, parent: string): boolean {
const relative = child.replace(parent, '');
return !relative.startsWith('..') && !relative.includes('/..');
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/mcp-memory",
"version": "1.9.0",
"version": "1.12.0",
"description": "MCP (Model Context Protocol) server for SkillKit persistent memory",
"type": "module",
"main": "./dist/index.js",
+52
View File
@@ -0,0 +1,52 @@
{
"name": "@skillkit/mcp",
"version": "1.12.0",
"description": "MCP server for SkillKit skill discovery — agent-native skill search",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"bin": {
"skillkit-mcp": "./dist/index.js"
},
"exports": {
".": {
"import": "./dist/index.js",
"types": "./dist/index.d.ts"
}
},
"files": [
"dist"
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"start": "node dist/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0",
"@skillkit/core": "workspace:*",
"zod": "^3.24.0"
},
"devDependencies": {
"@types/node": "^22.10.5",
"tsup": "^8.3.5",
"typescript": "^5.7.2",
"vitest": "^2.1.8"
},
"engines": {
"node": ">=18.0.0"
},
"license": "Apache-2.0",
"keywords": [
"mcp",
"model-context-protocol",
"skillkit",
"skills",
"discovery",
"ai",
"agents",
"claude"
]
}
+84
View File
@@ -0,0 +1,84 @@
import { describe, it, expect } from 'vitest';
import {
handleSearchSkills,
handleGetSkill,
handleRecommendSkills,
handleListCategories,
} from '../tools.js';
import type { SkillEntry } from '../tools.js';
const testSkills: SkillEntry[] = [
{ name: 'react-perf', description: 'React performance tips', source: 'owner/repo', tags: ['react', 'performance'] },
{ name: 'testing-guide', description: 'Unit testing guide', source: 'owner/repo2', tags: ['testing'] },
{ name: 'nextjs-auth', description: 'Next.js authentication', source: 'other/repo', tags: ['nextjs', 'auth'], category: 'framework' },
];
describe('handleSearchSkills', () => {
it('returns ranked results for query', () => {
const result = handleSearchSkills(testSkills, { query: 'react', limit: 10 });
const data = JSON.parse(result.content[0].text);
expect(data.skills.length).toBeGreaterThan(0);
expect(data.query).toBe('react');
expect(data.total).toBeGreaterThan(0);
});
it('applies tag filters', () => {
const result = handleSearchSkills(testSkills, {
query: 'guide',
limit: 10,
filters: { tags: ['testing'] },
});
const data = JSON.parse(result.content[0].text);
expect(data.skills.length).toBeGreaterThanOrEqual(1);
});
it('respects limit', () => {
const result = handleSearchSkills(testSkills, { query: 'test', limit: 1 });
const data = JSON.parse(result.content[0].text);
expect(data.skills.length).toBeLessThanOrEqual(1);
});
});
describe('handleGetSkill', () => {
it('returns a specific skill', () => {
const result = handleGetSkill(testSkills, { source: 'owner/repo', skill_id: 'react-perf' });
expect(result.isError).toBeUndefined();
const data = JSON.parse(result.content[0].text);
expect(data.name).toBe('react-perf');
});
it('returns error for missing skill', () => {
const result = handleGetSkill(testSkills, { source: 'owner/repo', skill_id: 'nonexistent' });
expect(result.isError).toBe(true);
});
});
describe('handleRecommendSkills', () => {
it('recommends based on languages', () => {
const result = handleRecommendSkills(testSkills, { languages: ['react'], limit: 5 });
const data = JSON.parse(result.content[0].text);
expect(data.recommendations.length).toBeGreaterThan(0);
});
it('recommends based on task description', () => {
const result = handleRecommendSkills(testSkills, { task: 'testing react components', limit: 5 });
const data = JSON.parse(result.content[0].text);
expect(data.recommendations.length).toBeGreaterThan(0);
});
it('errors with no input', () => {
const result = handleRecommendSkills(testSkills, { limit: 5 });
expect(result.isError).toBe(true);
});
});
describe('handleListCategories', () => {
it('returns tag counts', () => {
const result = handleListCategories(testSkills);
const data = JSON.parse(result.content[0].text);
expect(data.categories.length).toBeGreaterThan(0);
expect(data.total).toBeGreaterThan(0);
const react = data.categories.find((c: { name: string }) => c.name === 'react');
expect(react?.count).toBe(1);
});
});
+223
View File
@@ -0,0 +1,223 @@
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { fileURLToPath } from 'node:url';
import {
CallToolRequestSchema,
ListToolsRequestSchema,
ListResourcesRequestSchema,
ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import {
handleSearchSkills,
handleGetSkill,
handleRecommendSkills,
handleListCategories,
} from './tools.js';
import type { SkillEntry } from './tools.js';
import { getTrendingResource, getCategoriesResource } from './resources.js';
let skills: SkillEntry[] = [];
async function loadSkills(): Promise<SkillEntry[]> {
const { readFileSync } = await import('node:fs');
const { join, dirname } = await import('node:path');
const possiblePaths = [
join(process.cwd(), 'marketplace', 'skills.json'),
join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'marketplace', 'skills.json'),
join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'marketplace', 'skills.json'),
];
for (const path of possiblePaths) {
try {
const data = JSON.parse(readFileSync(path, 'utf-8'));
if (data.skills && Array.isArray(data.skills)) {
return data.skills.map((s: Record<string, unknown>) => ({
name: s.name as string,
description: s.description as string | undefined,
source: (s.source as string) || '',
repo: s.repo as string | undefined,
tags: s.tags as string[] | undefined,
category: s.category as string | undefined,
}));
}
} catch {
continue;
}
}
return [];
}
const server = new Server(
{
name: 'skillkit-discovery',
version: '1.12.0',
},
{
capabilities: {
tools: {},
resources: {},
},
},
);
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'search_skills',
description: 'Search for AI agent skills by keyword, tag, or description. Returns ranked results from the SkillKit marketplace.',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query' },
limit: { type: 'number', minimum: 1, maximum: 50, default: 10, description: 'Max results' },
include_content: { type: 'boolean', default: false, description: 'Include full content' },
include_references: { type: 'boolean', default: false, description: 'Include references' },
filters: {
type: 'object',
properties: {
tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
category: { type: 'string', description: 'Filter by category' },
source: { type: 'string', description: 'Filter by source repo' },
},
},
},
required: ['query'],
},
},
{
name: 'get_skill',
description: 'Get details of a specific skill by source and ID.',
inputSchema: {
type: 'object',
properties: {
source: { type: 'string', description: 'Skill source (e.g. owner/repo)' },
skill_id: { type: 'string', description: 'Skill name' },
include_references: { type: 'boolean', default: false, description: 'Include references' },
},
required: ['source', 'skill_id'],
},
},
{
name: 'recommend_skills',
description: 'Get skill recommendations based on your tech stack and current task.',
inputSchema: {
type: 'object',
properties: {
languages: { type: 'array', items: { type: 'string' }, description: 'Programming languages' },
frameworks: { type: 'array', items: { type: 'string' }, description: 'Frameworks' },
libraries: { type: 'array', items: { type: 'string' }, description: 'Libraries' },
task: { type: 'string', description: 'Current task description' },
limit: { type: 'number', minimum: 1, maximum: 20, default: 5, description: 'Max results' },
},
},
},
{
name: 'list_categories',
description: 'List all skill categories with their counts.',
inputSchema: {
type: 'object',
properties: {},
},
},
],
};
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
switch (name) {
case 'search_skills':
return handleSearchSkills(skills, args);
case 'get_skill':
return handleGetSkill(skills, args);
case 'recommend_skills':
return handleRecommendSkills(skills, args);
case 'list_categories':
return handleListCategories(skills);
default:
return {
content: [{ type: 'text', text: `Unknown tool: ${name}` }],
isError: true,
};
}
} catch (error) {
const message = error instanceof Error ? error.message : 'Unknown error';
return {
content: [{ type: 'text', text: `Error: ${message}` }],
isError: true,
};
}
});
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: 'skills://trending',
name: 'Trending Skills',
description: 'Top trending skills by relevance score',
mimeType: 'application/json',
},
{
uri: 'skills://categories',
name: 'Skill Categories',
description: 'All skill categories with counts',
mimeType: 'application/json',
},
],
};
});
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
if (uri === 'skills://trending') {
return {
contents: [
{
uri,
mimeType: 'application/json',
text: getTrendingResource(skills),
},
],
};
}
if (uri === 'skills://categories') {
return {
contents: [
{
uri,
mimeType: 'application/json',
text: getCategoriesResource(skills),
},
],
};
}
throw new Error(`Unknown resource: ${uri}`);
});
async function main() {
skills = await loadSkills();
console.error(`SkillKit Discovery MCP Server starting (${skills.length} skills loaded)`);
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('SkillKit Discovery MCP Server running on stdio');
}
const isMain = process.argv[1] === fileURLToPath(import.meta.url);
if (isMain) {
main().catch((error) => {
console.error('Fatal error:', error);
process.exit(1);
});
}
export { server };
+48
View File
@@ -0,0 +1,48 @@
import { RelevanceRanker } from '@skillkit/core';
import type { SkillEntry } from './tools.js';
const ranker = new RelevanceRanker();
export function getTrendingResource(skills: SkillEntry[]) {
const skillMap = new Map(skills.map((s) => [s.name, s]));
const ranked = ranker.rank(
skills.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
})),
);
const trending = ranked.slice(0, 20).map((r) => {
const original = skillMap.get(r.skill.name);
if (!original) return null;
return {
name: original.name,
description: original.description,
source: original.source,
tags: original.tags,
score: r.score,
};
}).filter(Boolean);
return JSON.stringify({ trending, count: trending.length }, null, 2);
}
export function getCategoriesResource(skills: SkillEntry[]) {
const tagCounts = new Map<string, number>();
for (const skill of skills) {
if (skill.tags) {
for (const tag of skill.tags) {
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
}
}
}
const categories = Array.from(tagCounts.entries())
.map(([name, count]) => ({ name, count }))
.sort((a, b) => b.count - a.count);
return JSON.stringify({ categories, total: categories.length }, null, 2);
}
+169
View File
@@ -0,0 +1,169 @@
import { RelevanceRanker } from '@skillkit/core';
import {
SearchSkillsInputSchema,
GetSkillInputSchema,
RecommendSkillsInputSchema,
} from './types.js';
export interface SkillEntry {
name: string;
description?: string;
source: string;
repo?: string;
tags?: string[];
category?: string;
content?: string;
}
const ranker = new RelevanceRanker();
export function handleSearchSkills(skills: SkillEntry[], args: unknown) {
const input = SearchSkillsInputSchema.parse(args);
let filtered = skills;
if (input.filters) {
if (input.filters.tags?.length) {
filtered = filtered.filter((s) =>
input.filters!.tags!.some((t) => s.tags?.includes(t)),
);
}
if (input.filters.category) {
filtered = filtered.filter((s) => s.category === input.filters!.category);
}
if (input.filters.source) {
filtered = filtered.filter((s) => s.source.includes(input.filters!.source!));
}
}
const skillMap = new Map(filtered.map((s) => [`${s.source}:${s.name}`, s]));
const ranked = ranker.rank(
filtered.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
source: s.source,
})),
input.query,
);
const results = ranked.slice(0, input.limit).map((r) => {
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
const original = skillMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!;
const result: Record<string, unknown> = {
name: original.name,
description: original.description,
source: original.source,
tags: original.tags,
score: r.score,
};
if (input.include_content) result.content = original.content;
return result;
});
return {
content: [
{
type: 'text' as const,
text: JSON.stringify({ skills: results, total: ranked.length, query: input.query }, null, 2),
},
],
};
}
export function handleGetSkill(skills: SkillEntry[], args: unknown) {
const input = GetSkillInputSchema.parse(args);
const skill = skills.find(
(s) => s.source === input.source && s.name === input.skill_id,
);
if (!skill) {
return {
content: [{ type: 'text' as const, text: `Skill not found: ${input.source}/${input.skill_id}` }],
isError: true,
};
}
return {
content: [
{
type: 'text' as const,
text: JSON.stringify(skill, null, 2),
},
],
};
}
export function handleRecommendSkills(skills: SkillEntry[], args: unknown) {
const input = RecommendSkillsInputSchema.parse(args);
const queryParts: string[] = [];
if (input.languages?.length) queryParts.push(...input.languages);
if (input.frameworks?.length) queryParts.push(...input.frameworks);
if (input.libraries?.length) queryParts.push(...input.libraries);
if (input.task) queryParts.push(input.task);
const query = queryParts.join(' ');
if (!query) {
return {
content: [{ type: 'text' as const, text: 'Provide at least one of: languages, frameworks, libraries, or task' }],
isError: true,
};
}
const ranked = ranker.rank(
skills.map((s) => ({
name: s.name,
description: s.description,
content: s.content,
})),
query,
);
const recommendMap = new Map(skills.map((s) => [s.name, s]));
const results = ranked.slice(0, input.limit).map((r) => {
const original = recommendMap.get(r.skill.name)!;
return {
name: original.name,
description: original.description,
source: original.source,
tags: original.tags,
score: r.score,
};
});
return {
content: [
{
type: 'text' as const,
text: JSON.stringify({ recommendations: results, query }, null, 2),
},
],
};
}
export function handleListCategories(skills: SkillEntry[]) {
const tagCounts = new Map<string, number>();
for (const skill of skills) {
if (skill.tags) {
for (const tag of skill.tags) {
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
}
}
}
const categories = Array.from(tagCounts.entries())
.map(([name, count]) => ({ name, count }))
.sort((a, b) => b.count - a.count);
return {
content: [
{
type: 'text' as const,
text: JSON.stringify({ categories, total: categories.length }, null, 2),
},
],
};
}
+36
View File
@@ -0,0 +1,36 @@
import { z } from 'zod';
export const SearchSkillsInputSchema = z.object({
query: z.string().describe('Search query for skills'),
limit: z.number().min(1).max(50).default(10).describe('Maximum results'),
include_content: z.boolean().default(false).describe('Include full skill content'),
include_references: z.boolean().default(false).describe('Include reference file paths'),
filters: z
.object({
tags: z.array(z.string()).optional(),
category: z.string().optional(),
source: z.string().optional(),
})
.optional()
.describe('Optional filters'),
});
export const GetSkillInputSchema = z.object({
source: z.string().describe('Skill source (e.g. owner/repo)'),
skill_id: z.string().describe('Skill name/identifier'),
include_references: z.boolean().default(false).describe('Include reference file paths'),
});
export const RecommendSkillsInputSchema = z.object({
languages: z.array(z.string()).optional().describe('Programming languages'),
frameworks: z.array(z.string()).optional().describe('Frameworks in use'),
libraries: z.array(z.string()).optional().describe('Libraries in use'),
task: z.string().optional().describe('Current task description'),
limit: z.number().min(1).max(20).default(5).describe('Maximum results'),
});
export const ListCategoriesInputSchema = z.object({});
export type SearchSkillsInput = z.infer<typeof SearchSkillsInputSchema>;
export type GetSkillInput = z.infer<typeof GetSkillInputSchema>;
export type RecommendSkillsInput = z.infer<typeof RecommendSkillsInputSchema>;
+10
View File
@@ -0,0 +1,10 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"composite": false
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
+15
View File
@@ -0,0 +1,15 @@
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['esm'],
dts: true,
clean: true,
sourcemap: true,
target: 'node18',
skipNodeModulesBundle: true,
platform: 'node',
banner: {
js: '#!/usr/bin/env node',
},
});
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/memory",
"version": "1.9.0",
"version": "1.12.0",
"description": "CozoDB-backed semantic memory with embeddings for SkillKit",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/mesh",
"version": "1.9.0",
"version": "1.12.0",
"description": "Peer mesh network for multi-machine agent distribution",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/messaging",
"version": "1.9.0",
"version": "1.12.0",
"description": "Inter-agent messaging system for SkillKit",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/resources",
"version": "1.9.0",
"version": "1.12.0",
"description": "Bundled resources for SkillKit - agents, commands, profiles, guidelines, and hooks",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/tui",
"version": "1.9.0",
"version": "1.12.0",
"description": "Unified Terminal UI for SkillKit - Built on OpenTUI",
"type": "module",
"main": "./dist/index.js",
+1379
View File
File diff suppressed because it is too large Load Diff
+1
View File
@@ -1,3 +1,4 @@
packages:
- 'packages/*'
- 'apps/*'
- 'clients/*'
+29
View File
@@ -0,0 +1,29 @@
# SkillKit Community Registry
This directory contains the community-curated skills registry for SkillKit.
## How to Contribute
1. Fork this repository
2. Add your skill to `SKILLS.md` under the appropriate category
3. Follow the format: `- [skill-name](repo-url) - Brief description`
4. Submit a pull request
## Format
Each entry follows this format:
```markdown
- [skill-name](https://github.com/owner/repo) - Brief description of what the skill does
```
## Categories
Skills are organized into categories. If your skill doesn't fit an existing category, propose a new one in your PR.
## Requirements
- Skill must have a valid `SKILL.md` file
- Description must be clear and concise (under 100 characters)
- Repository must be publicly accessible
- Skill must follow SkillKit conventions
+66
View File
@@ -0,0 +1,66 @@
# SkillKit Community Skills Registry
A curated list of community-contributed skills for AI coding agents.
## Code Quality
- [code-simplifier](https://github.com/anthropics/skills) - Simplifies and refines code for clarity and maintainability
- [code-review](https://github.com/anthropics/skills) - Automated code review with best practices
## React & Frontend
- [react-performance](https://github.com/anthropics/skills) - React app performance optimization
- [nextjs-best-practices](https://github.com/vercel-labs/agent-skills) - Next.js patterns and conventions
- [css-architecture](https://github.com/anthropics/skills) - Scalable CSS organization patterns
## Testing
- [testing-guide](https://github.com/anthropics/skills) - Comprehensive unit testing fundamentals
- [e2e-testing](https://github.com/anthropics/skills) - End-to-end testing with Playwright
- [tdd-workflow](https://github.com/anthropics/skills) - Test-driven development workflow
## DevOps & Infrastructure
- [docker-best-practices](https://github.com/anthropics/skills) - Container optimization patterns
- [kubernetes-basics](https://github.com/anthropics/skills) - Kubernetes deployment fundamentals
- [cicd-pipelines](https://github.com/anthropics/skills) - CI/CD pipeline configuration
## API Development
- [rest-api-design](https://github.com/anthropics/skills) - RESTful API design patterns
- [graphql-patterns](https://github.com/anthropics/skills) - GraphQL schema and resolver patterns
## Database
- [sql-optimization](https://github.com/anthropics/skills) - SQL query optimization techniques
- [migration-patterns](https://github.com/anthropics/skills) - Database migration best practices
## Security
- [security-audit](https://github.com/anthropics/skills) - Security vulnerability detection
- [auth-patterns](https://github.com/anthropics/skills) - Authentication and authorization patterns
## Documentation
- [api-docs](https://github.com/anthropics/skills) - API documentation generation
- [readme-guide](https://github.com/anthropics/skills) - README writing best practices
## AI & ML
- [prompt-engineering](https://github.com/anthropics/skills) - Prompt engineering patterns
- [llm-integration](https://github.com/anthropics/skills) - LLM API integration patterns
## Mobile
- [react-native-perf](https://github.com/anthropics/skills) - React Native performance optimization
- [mobile-accessibility](https://github.com/anthropics/skills) - Mobile accessibility patterns
## Data Processing
- [data-pipeline](https://github.com/anthropics/skills) - Data pipeline design patterns
- [etl-patterns](https://github.com/anthropics/skills) - ETL workflow best practices
## Animation & Video
- [remotion-best-practices](https://github.com/remotion-dev/skills) - Video creation with Remotion
- [motion-graphics](https://github.com/remotion-dev/skills) - Kinetic typography and logo animations
+4 -3
View File
@@ -1,5 +1,5 @@
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, basename } from 'node:path';
import { join, basename, resolve, sep } from 'node:path';
import { parse as parseYaml } from 'yaml';
import { SkillFrontmatter, SkillMetadata, type Skill, type SkillLocation } from './types.js';
@@ -328,6 +328,7 @@ export function validateSkill(skillPath: string): { valid: boolean; errors: stri
}
export function isPathInside(child: string, parent: string): boolean {
const relative = child.replace(parent, '');
return !relative.startsWith('..') && !relative.includes('/..');
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}