feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42)

* feat: runtime skill discovery — REST API, MCP server, cache, ranking, Python client (#42)

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

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

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

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

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

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

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

All 856+ tests pass across 24 workspace tasks.

* fix: resolve TypeScript errors in API package

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

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

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

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

- Use source+name composite key Map lookups in search GET/POST routes
- Use source+name composite key Map lookup in trending route
- Fix Python client get_skill to use /skills/:owner/:repo/:id URL pattern
- Update Python test to match new 3-segment skill URL

Author: rohitg00

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:*",

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));

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"

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"

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

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

clients/python/tests/__init__.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

clients/python/tests/test_client.py

@@ -1,6 +1,6 @@
 {
   "name": "skillkit-docs",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "private": true,
   "scripts": {
     "build": "next build",

docs/fumadocs/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skillkit",
   "private": true,
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
   "scripts": {
     "dev": "vite",