From e5f0d6d450742450335d9bb6b5f5b50a521d813d Mon Sep 17 00:00:00 2001 From: Rohit Ghumare <48523873+rohitg00@users.noreply.github.com> Date: Wed, 4 Feb 2026 00:27:25 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20runtime=20skill=20discovery=20=E2=80=94?= =?UTF-8?q?=20REST=20API,=20MCP=20server,=20cache,=20ranking,=20Python=20c?= =?UTF-8?q?lient=20(#42)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- apps/skillkit/package.json | 1 + apps/skillkit/src/cli.ts | 3 + clients/python/pyproject.toml | 42 ++++ clients/python/skillkit/__init__.py | 12 + clients/python/skillkit/client.py | 140 +++++++++++ clients/python/skillkit/models.py | 51 ++++ clients/python/tests/__init__.py | 0 clients/python/tests/test_client.py | 99 ++++++++ docs/fumadocs/package.json | 2 +- docs/skillkit/package.json | 2 +- packages/api/package.json | 52 ++++ packages/api/src/__tests__/health.test.ts | 27 +++ packages/api/src/__tests__/search.test.ts | 56 +++++ packages/api/src/__tests__/skills.test.ts | 53 +++++ packages/api/src/index.ts | 11 + packages/api/src/middleware/rate-limit.ts | 43 ++++ packages/api/src/routes/categories.ts | 34 +++ packages/api/src/routes/health.ts | 33 +++ packages/api/src/routes/search.ts | 128 ++++++++++ packages/api/src/routes/skills.ts | 23 ++ packages/api/src/routes/trending.ts | 39 +++ packages/api/src/server.ts | 55 +++++ packages/api/src/types.ts | 48 ++++ packages/api/tsconfig.json | 10 + packages/api/tsup.config.ts | 17 ++ packages/cli/package.json | 1 + packages/cli/src/commands/index.ts | 3 + packages/cli/src/commands/serve.ts | 93 ++++++++ .../core/src/cache/__tests__/memory.test.ts | 91 +++++++ packages/core/src/cache/index.ts | 2 + packages/core/src/cache/memory.ts | 101 ++++++++ packages/core/src/cache/types.ts | 21 ++ packages/core/src/index.ts | 13 + .../src/parser/__tests__/references.test.ts | 94 ++++++++ packages/core/src/parser/index.ts | 1 + packages/core/src/parser/references.ts | 105 +++++++++ .../src/ranking/__tests__/relevance.test.ts | 85 +++++++ packages/core/src/ranking/index.ts | 1 + packages/core/src/ranking/relevance.ts | 92 ++++++++ .../src/registry/__tests__/community.test.ts | 87 +++++++ packages/core/src/registry/community.ts | 97 ++++++++ packages/core/src/registry/index.ts | 2 + .../src/runtime/__tests__/injector.test.ts | 113 +++++++++ packages/core/src/runtime/index.ts | 1 + packages/core/src/runtime/injector.ts | 99 ++++++++ packages/mcp/package.json | 52 ++++ packages/mcp/src/__tests__/tools.test.ts | 84 +++++++ packages/mcp/src/index.ts | 223 ++++++++++++++++++ packages/mcp/src/resources.ts | 48 ++++ packages/mcp/src/tools.ts | 169 +++++++++++++ packages/mcp/src/types.ts | 36 +++ packages/mcp/tsconfig.json | 10 + packages/mcp/tsup.config.ts | 15 ++ pnpm-lock.yaml | 59 +++++ pnpm-workspace.yaml | 1 + registry/README.md | 29 +++ registry/SKILLS.md | 66 ++++++ 57 files changed, 2873 insertions(+), 2 deletions(-) create mode 100644 clients/python/pyproject.toml create mode 100644 clients/python/skillkit/__init__.py create mode 100644 clients/python/skillkit/client.py create mode 100644 clients/python/skillkit/models.py create mode 100644 clients/python/tests/__init__.py create mode 100644 clients/python/tests/test_client.py create mode 100644 packages/api/package.json create mode 100644 packages/api/src/__tests__/health.test.ts create mode 100644 packages/api/src/__tests__/search.test.ts create mode 100644 packages/api/src/__tests__/skills.test.ts create mode 100644 packages/api/src/index.ts create mode 100644 packages/api/src/middleware/rate-limit.ts create mode 100644 packages/api/src/routes/categories.ts create mode 100644 packages/api/src/routes/health.ts create mode 100644 packages/api/src/routes/search.ts create mode 100644 packages/api/src/routes/skills.ts create mode 100644 packages/api/src/routes/trending.ts create mode 100644 packages/api/src/server.ts create mode 100644 packages/api/src/types.ts create mode 100644 packages/api/tsconfig.json create mode 100644 packages/api/tsup.config.ts create mode 100644 packages/cli/src/commands/serve.ts create mode 100644 packages/core/src/cache/__tests__/memory.test.ts create mode 100644 packages/core/src/cache/index.ts create mode 100644 packages/core/src/cache/memory.ts create mode 100644 packages/core/src/cache/types.ts create mode 100644 packages/core/src/parser/__tests__/references.test.ts create mode 100644 packages/core/src/parser/index.ts create mode 100644 packages/core/src/parser/references.ts create mode 100644 packages/core/src/ranking/__tests__/relevance.test.ts create mode 100644 packages/core/src/ranking/index.ts create mode 100644 packages/core/src/ranking/relevance.ts create mode 100644 packages/core/src/registry/__tests__/community.test.ts create mode 100644 packages/core/src/registry/community.ts create mode 100644 packages/core/src/runtime/__tests__/injector.test.ts create mode 100644 packages/core/src/runtime/index.ts create mode 100644 packages/core/src/runtime/injector.ts create mode 100644 packages/mcp/package.json create mode 100644 packages/mcp/src/__tests__/tools.test.ts create mode 100644 packages/mcp/src/index.ts create mode 100644 packages/mcp/src/resources.ts create mode 100644 packages/mcp/src/tools.ts create mode 100644 packages/mcp/src/types.ts create mode 100644 packages/mcp/tsconfig.json create mode 100644 packages/mcp/tsup.config.ts create mode 100644 registry/README.md create mode 100644 registry/SKILLS.md diff --git a/apps/skillkit/package.json b/apps/skillkit/package.json index 66bf9298..675da107 100644 --- a/apps/skillkit/package.json +++ b/apps/skillkit/package.json @@ -53,6 +53,7 @@ "node": ">=18.0.0" }, "dependencies": { + "@skillkit/api": "workspace:*", "@skillkit/core": "workspace:*", "@skillkit/agents": "workspace:*", "@skillkit/cli": "workspace:*", diff --git a/apps/skillkit/src/cli.ts b/apps/skillkit/src/cli.ts index 8e1eb15a..244a79aa 100644 --- a/apps/skillkit/src/cli.ts +++ b/apps/skillkit/src/cli.ts @@ -102,6 +102,7 @@ import { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand, + ServeCommand, } from '@skillkit/cli'; const __filename = fileURLToPath(import.meta.url); @@ -229,4 +230,6 @@ cli.register(SkillMdValidateCommand); cli.register(SkillMdInitCommand); cli.register(SkillMdCheckCommand); +cli.register(ServeCommand); + cli.runExit(process.argv.slice(2)); diff --git a/clients/python/pyproject.toml b/clients/python/pyproject.toml new file mode 100644 index 00000000..d9c83cea --- /dev/null +++ b/clients/python/pyproject.toml @@ -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" diff --git a/clients/python/skillkit/__init__.py b/clients/python/skillkit/__init__.py new file mode 100644 index 00000000..7c272c2c --- /dev/null +++ b/clients/python/skillkit/__init__.py @@ -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" diff --git a/clients/python/skillkit/client.py b/clients/python/skillkit/client.py new file mode 100644 index 00000000..30fe9954 --- /dev/null +++ b/clients/python/skillkit/client.py @@ -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 diff --git a/clients/python/skillkit/models.py b/clients/python/skillkit/models.py new file mode 100644 index 00000000..bd9c32ff --- /dev/null +++ b/clients/python/skillkit/models.py @@ -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 diff --git a/clients/python/tests/__init__.py b/clients/python/tests/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/clients/python/tests/test_client.py b/clients/python/tests/test_client.py new file mode 100644 index 00000000..10ddfd00 --- /dev/null +++ b/clients/python/tests/test_client.py @@ -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 diff --git a/docs/fumadocs/package.json b/docs/fumadocs/package.json index 580f4c9f..c503e2e1 100644 --- a/docs/fumadocs/package.json +++ b/docs/fumadocs/package.json @@ -1,6 +1,6 @@ { "name": "skillkit-docs", - "version": "1.10.0", + "version": "1.11.0", "private": true, "scripts": { "build": "next build", diff --git a/docs/skillkit/package.json b/docs/skillkit/package.json index 6d767877..2221196e 100644 --- a/docs/skillkit/package.json +++ b/docs/skillkit/package.json @@ -1,7 +1,7 @@ { "name": "skillkit", "private": true, - "version": "1.10.0", + "version": "1.11.0", "type": "module", "scripts": { "dev": "vite", diff --git a/packages/api/package.json b/packages/api/package.json new file mode 100644 index 00000000..4880d463 --- /dev/null +++ b/packages/api/package.json @@ -0,0 +1,52 @@ +{ + "name": "@skillkit/api", + "version": "1.11.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" + ] +} diff --git a/packages/api/src/__tests__/health.test.ts b/packages/api/src/__tests__/health.test.ts new file mode 100644 index 00000000..c967cf8c --- /dev/null +++ b/packages/api/src/__tests__/health.test.ts @@ -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'); + }); +}); diff --git a/packages/api/src/__tests__/search.test.ts b/packages/api/src/__tests__/search.test.ts new file mode 100644 index 00000000..5c07a222 --- /dev/null +++ b/packages/api/src/__tests__/search.test.ts @@ -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); + }); +}); diff --git a/packages/api/src/__tests__/skills.test.ts b/packages/api/src/__tests__/skills.test.ts new file mode 100644 index 00000000..d6de9801 --- /dev/null +++ b/packages/api/src/__tests__/skills.test.ts @@ -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); + }); +}); diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts new file mode 100644 index 00000000..7193d510 --- /dev/null +++ b/packages/api/src/index.ts @@ -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'; diff --git a/packages/api/src/middleware/rate-limit.ts b/packages/api/src/middleware/rate-limit.ts new file mode 100644 index 00000000..abc1039d --- /dev/null +++ b/packages/api/src/middleware/rate-limit.ts @@ -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(); + + 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 => { + 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(); + }; +} diff --git a/packages/api/src/routes/categories.ts b/packages/api/src/routes/categories.ts new file mode 100644 index 00000000..8d39ff2a --- /dev/null +++ b/packages/api/src/routes/categories.ts @@ -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(); + + 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; +} diff --git a/packages/api/src/routes/health.ts b/packages/api/src/routes/health.ts new file mode 100644 index 00000000..3c450468 --- /dev/null +++ b/packages/api/src/routes/health.ts @@ -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; +} diff --git a/packages/api/src/routes/search.ts b/packages/api/src/routes/search.ts new file mode 100644 index 00000000..32fa2cc7 --- /dev/null +++ b/packages/api/src/routes/search.ts @@ -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) { + 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).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).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; +} diff --git a/packages/api/src/routes/skills.ts b/packages/api/src/routes/skills.ts new file mode 100644 index 00000000..5db08cb9 --- /dev/null +++ b/packages/api/src/routes/skills.ts @@ -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; +} diff --git a/packages/api/src/routes/trending.ts b/packages/api/src/routes/trending.ts new file mode 100644 index 00000000..05b81078 --- /dev/null +++ b/packages/api/src/routes/trending.ts @@ -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).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; +} diff --git a/packages/api/src/server.ts b/packages/api/src/server.ts new file mode 100644 index 00000000..31e324da --- /dev/null +++ b/packages/api/src/server.ts @@ -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({ + 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 }; +} diff --git a/packages/api/src/types.ts b/packages/api/src/types.ts new file mode 100644 index 00000000..63696ad2 --- /dev/null +++ b/packages/api/src/types.ts @@ -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; +} diff --git a/packages/api/tsconfig.json b/packages/api/tsconfig.json new file mode 100644 index 00000000..c64c5089 --- /dev/null +++ b/packages/api/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "composite": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} diff --git a/packages/api/tsup.config.ts b/packages/api/tsup.config.ts new file mode 100644 index 00000000..8c2729e6 --- /dev/null +++ b/packages/api/tsup.config.ts @@ -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', + }, +}); diff --git a/packages/cli/package.json b/packages/cli/package.json index f3b30de6..c1102227 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -22,6 +22,7 @@ }, "dependencies": { "@clack/prompts": "^0.11.0", + "@skillkit/api": "workspace:*", "@skillkit/core": "workspace:*", "@skillkit/agents": "workspace:*", "@skillkit/resources": "workspace:*", diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index 68799556..db979691 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -114,3 +114,6 @@ export { QuickCommand } from './quick.js'; // SKILL.md ecosystem export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from './skillmd.js'; + +// API server +export { ServeCommand } from './serve.js'; diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts new file mode 100644 index 00000000..aee22ba4 --- /dev/null +++ b/packages/cli/src/commands/serve.ts @@ -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 { + header('SkillKit API Server'); + + const skills = (skillsData.skills || []).map((skill: Record) => ({ + 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; + } +} diff --git a/packages/core/src/cache/__tests__/memory.test.ts b/packages/core/src/cache/__tests__/memory.test.ts new file mode 100644 index 00000000..6beb7f87 --- /dev/null +++ b/packages/core/src/cache/__tests__/memory.test.ts @@ -0,0 +1,91 @@ +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import { MemoryCache } from '../memory.js'; + +describe('MemoryCache', () => { + let cache: MemoryCache; + + beforeEach(() => { + cache = new MemoryCache({ 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(); + const stats = defaultCache.stats(); + expect(stats.maxSize).toBe(1000); + }); +}); diff --git a/packages/core/src/cache/index.ts b/packages/core/src/cache/index.ts new file mode 100644 index 00000000..4714b820 --- /dev/null +++ b/packages/core/src/cache/index.ts @@ -0,0 +1,2 @@ +export * from './types.js'; +export * from './memory.js'; diff --git a/packages/core/src/cache/memory.ts b/packages/core/src/cache/memory.ts new file mode 100644 index 00000000..c870aec5 --- /dev/null +++ b/packages/core/src/cache/memory.ts @@ -0,0 +1,101 @@ +import type { CacheBackend, CacheOptions, CacheStats } from './types.js'; + +interface CacheEntry { + value: V; + expiresAt: number; + lastAccessed: number; +} + +const DEFAULT_MAX_SIZE = 1000; +const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; + +export class MemoryCache implements CacheBackend { + private store = new Map>(); + 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); + } + } +} diff --git a/packages/core/src/cache/types.ts b/packages/core/src/cache/types.ts new file mode 100644 index 00000000..db66ebac --- /dev/null +++ b/packages/core/src/cache/types.ts @@ -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 { + get(key: string): V | undefined; + set(key: string, value: V): void; + delete(key: string): boolean; + has(key: string): boolean; + clear(): void; + stats(): CacheStats; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 4b826049..4a1aff2d 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -107,3 +107,16 @@ 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'; diff --git a/packages/core/src/parser/__tests__/references.test.ts b/packages/core/src/parser/__tests__/references.test.ts new file mode 100644 index 00000000..51178e8d --- /dev/null +++ b/packages/core/src/parser/__tests__/references.test.ts @@ -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([]); + }); +}); diff --git a/packages/core/src/parser/index.ts b/packages/core/src/parser/index.ts new file mode 100644 index 00000000..f84e47e8 --- /dev/null +++ b/packages/core/src/parser/index.ts @@ -0,0 +1 @@ +export * from './references.js'; diff --git a/packages/core/src/parser/references.ts b/packages/core/src/parser/references.ts new file mode 100644 index 00000000..88a0db9c --- /dev/null +++ b/packages/core/src/parser/references.ts @@ -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; + body: string; + references: SkillReference[]; + raw: string; +} + +const REFERENCE_DIRS = ['references', 'resources', 'docs', 'examples', 'assets', 'scripts']; + +const DIR_TYPE_MAP: Record = { + 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; 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 = {}; + 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, + }; +} diff --git a/packages/core/src/ranking/__tests__/relevance.test.ts b/packages/core/src/ranking/__tests__/relevance.test.ts new file mode 100644 index 00000000..8a0b657d --- /dev/null +++ b/packages/core/src/ranking/__tests__/relevance.test.ts @@ -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); + } + }); +}); diff --git a/packages/core/src/ranking/index.ts b/packages/core/src/ranking/index.ts new file mode 100644 index 00000000..71c7c4e6 --- /dev/null +++ b/packages/core/src/ranking/index.ts @@ -0,0 +1 @@ +export * from './relevance.js'; diff --git a/packages/core/src/ranking/relevance.ts b/packages/core/src/ranking/relevance.ts new file mode 100644 index 00000000..3d6458c5 --- /dev/null +++ b/packages/core/src/ranking/relevance.ts @@ -0,0 +1,92 @@ +export interface RankableSkill { + name: string; + description?: string; + content?: string; + stars?: number; + installs?: number; + references?: string[]; +} + +export interface RankedSkill { + 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(skills: T[], query?: string): RankedSkill[] { + 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); + } +} diff --git a/packages/core/src/registry/__tests__/community.test.ts b/packages/core/src/registry/__tests__/community.test.ts new file mode 100644 index 00000000..a51dd777 --- /dev/null +++ b/packages/core/src/registry/__tests__/community.test.ts @@ -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([]); + }); +}); diff --git a/packages/core/src/registry/community.ts b/packages/core/src/registry/community.ts new file mode 100644 index 00000000..53cb7988 --- /dev/null +++ b/packages/core/src/registry/community.ts @@ -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 { + 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))]; + } +} diff --git a/packages/core/src/registry/index.ts b/packages/core/src/registry/index.ts index e3fc26d7..7541cec5 100644 --- a/packages/core/src/registry/index.ts +++ b/packages/core/src/registry/index.ts @@ -115,6 +115,8 @@ export class GitHubSkillRegistry implements ExternalRegistry { } } +export { CommunityRegistry } from './community.js'; + export class FederatedSearch { private registries: ExternalRegistry[] = []; diff --git a/packages/core/src/runtime/__tests__/injector.test.ts b/packages/core/src/runtime/__tests__/injector.test.ts new file mode 100644 index 00000000..b9f82b12 --- /dev/null +++ b/packages/core/src/runtime/__tests__/injector.test.ts @@ -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' }); + }); +}); diff --git a/packages/core/src/runtime/index.ts b/packages/core/src/runtime/index.ts new file mode 100644 index 00000000..85c7cc11 --- /dev/null +++ b/packages/core/src/runtime/index.ts @@ -0,0 +1 @@ +export * from './injector.js'; diff --git a/packages/core/src/runtime/injector.ts b/packages/core/src/runtime/injector.ts new file mode 100644 index 00000000..a8395595 --- /dev/null +++ b/packages/core/src/runtime/injector.ts @@ -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; + + constructor(cacheTtlMs?: number) { + this.cache = new MemoryCache({ + maxSize: 200, + ttlMs: cacheTtlMs ?? 24 * 60 * 60 * 1000, + }); + } + + async fetch(source: string, skillId: string): Promise { + 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 { + const fetched = await this.fetch(source, skillId); + return fetched.parsed.body; + } + + private async fetchRawSkillMd(owner: string, repo: string, skillId: string): Promise { + const paths = [ + `${skillId}/SKILL.md`, + `skills/${skillId}/SKILL.md`, + `SKILL.md`, + ]; + + const headers: Record = { + 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(); + } +} diff --git a/packages/mcp/package.json b/packages/mcp/package.json new file mode 100644 index 00000000..5d936d77 --- /dev/null +++ b/packages/mcp/package.json @@ -0,0 +1,52 @@ +{ + "name": "@skillkit/mcp", + "version": "1.11.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" + ] +} diff --git a/packages/mcp/src/__tests__/tools.test.ts b/packages/mcp/src/__tests__/tools.test.ts new file mode 100644 index 00000000..57f781b3 --- /dev/null +++ b/packages/mcp/src/__tests__/tools.test.ts @@ -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); + }); +}); diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts new file mode 100644 index 00000000..ccad80ea --- /dev/null +++ b/packages/mcp/src/index.ts @@ -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 { + 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) => ({ + 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.11.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 }; diff --git a/packages/mcp/src/resources.ts b/packages/mcp/src/resources.ts new file mode 100644 index 00000000..dff6c7e4 --- /dev/null +++ b/packages/mcp/src/resources.ts @@ -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(); + + 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); +} diff --git a/packages/mcp/src/tools.ts b/packages/mcp/src/tools.ts new file mode 100644 index 00000000..42071523 --- /dev/null +++ b/packages/mcp/src/tools.ts @@ -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).source}:${r.skill.name}`; + const original = skillMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!; + const result: Record = { + 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(); + + 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), + }, + ], + }; +} diff --git a/packages/mcp/src/types.ts b/packages/mcp/src/types.ts new file mode 100644 index 00000000..893e513f --- /dev/null +++ b/packages/mcp/src/types.ts @@ -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; +export type GetSkillInput = z.infer; +export type RecommendSkillsInput = z.infer; diff --git a/packages/mcp/tsconfig.json b/packages/mcp/tsconfig.json new file mode 100644 index 00000000..c64c5089 --- /dev/null +++ b/packages/mcp/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "composite": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} diff --git a/packages/mcp/tsup.config.ts b/packages/mcp/tsup.config.ts new file mode 100644 index 00000000..113ae2ac --- /dev/null +++ b/packages/mcp/tsup.config.ts @@ -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', + }, +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e8dac132..ced7853c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -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': diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 4e708bd3..385a7028 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,3 +1,4 @@ packages: - 'packages/*' - 'apps/*' + - 'clients/*' diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 00000000..65506a69 --- /dev/null +++ b/registry/README.md @@ -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 diff --git a/registry/SKILLS.md b/registry/SKILLS.md new file mode 100644 index 00000000..a0af13cb --- /dev/null +++ b/registry/SKILLS.md @@ -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