Compare commits

..
4 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
79 changed files with 4635 additions and 32 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.10.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.10.0",
"version": "1.12.0",
"private": true,
"scripts": {
"build": "next build",
+26
View File
@@ -12,6 +12,8 @@ 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 = (
@@ -61,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')}
@@ -172,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" />
+5 -5
View File
@@ -134,14 +134,14 @@ export function Hero({ version }: HeroProps): React.ReactElement {
</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">
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "skillkit",
"private": true,
"version": "1.10.0",
"version": "1.12.0",
"type": "module",
"scripts": {
"dev": "vite",
+9 -3
View File
@@ -1,8 +1,8 @@
{
"name": "skillkit-monorepo",
"version": "1.10.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.10.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.10.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;
}
}
}
+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
}
}
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.10.0",
"version": "1.12.0",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
+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;
}
+16
View File
@@ -104,3 +104,19 @@ 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);
}
}
@@ -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();
}
}
+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.10.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.10.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.10.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.10.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.10.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.10.0",
"version": "1.12.0",
"description": "Unified Terminal UI for SkillKit - Built on OpenTUI",
"type": "module",
"main": "./dist/index.js",
+59
View File
@@ -32,6 +32,9 @@ importers:
'@skillkit/agents':
specifier: workspace:*
version: link:../../packages/agents
'@skillkit/api':
specifier: workspace:*
version: link:../../packages/api
'@skillkit/cli':
specifier: workspace:*
version: link:../../packages/cli
@@ -89,6 +92,34 @@ importers:
specifier: ^2.1.8
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
packages/api:
dependencies:
'@hono/node-server':
specifier: ^1.0.0
version: 1.19.9(hono@4.11.7)
'@skillkit/core':
specifier: workspace:*
version: link:../core
hono:
specifier: ^4.0.0
version: 4.11.7
zod:
specifier: ^3.24.0
version: 3.25.76
devDependencies:
'@types/node':
specifier: ^22.10.5
version: 22.19.7
tsup:
specifier: ^8.3.5
version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.2)
typescript:
specifier: ^5.7.2
version: 5.9.3
vitest:
specifier: ^2.1.8
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
packages/cli:
dependencies:
'@clack/prompts':
@@ -97,6 +128,9 @@ importers:
'@skillkit/agents':
specifier: workspace:*
version: link:../agents
'@skillkit/api':
specifier: workspace:*
version: link:../api
'@skillkit/core':
specifier: workspace:*
version: link:../core
@@ -188,6 +222,31 @@ importers:
specifier: ^2.1.8
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
packages/mcp:
dependencies:
'@modelcontextprotocol/sdk':
specifier: ^1.0.0
version: 1.25.3(hono@4.11.7)(zod@3.25.76)
'@skillkit/core':
specifier: workspace:*
version: link:../core
zod:
specifier: ^3.24.0
version: 3.25.76
devDependencies:
'@types/node':
specifier: ^22.10.5
version: 22.19.7
tsup:
specifier: ^8.3.5
version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.2)
typescript:
specifier: ^5.7.2
version: 5.9.3
vitest:
specifier: ^2.1.8
version: 2.1.9(@types/node@22.19.7)(lightningcss@1.30.2)
packages/mcp-memory:
dependencies:
'@modelcontextprotocol/sdk':
+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);
}