docs: add v1.12.0 runtime skill discovery documentation

- README: add Runtime Discovery, serve command, REST API, MCP, Python
  client sections with examples and comparison table update
- Website Hero: update terminal animation with serve/API demo
- Website Features: add REST & MCP APIs card, API Access comparison row
- Website Commands: add Server tab with serve command options
- Fumadocs: create rest-api.mdx, mcp-server.mdx, python-client.mdx
- Fumadocs: update index (v1.12.0, architecture, discovery section),
  commands (serve command), and meta.json navigation
This commit is contained in:
Rohit Ghumare
2026-02-04 00:40:49 +00:00
parent b432400b5a
commit 19694dcaa1
10 changed files with 693 additions and 15 deletions
+86
View File
@@ -81,6 +81,7 @@ SkillKit features a polished, interactive CLI with visual feedback:
| **Context Sync** | Configure each agent separately | One config, synced everywhere |
| **Session Memory** | Knowledge dies with each session | Persistent learning across agents |
| **Skill Testing** | Hope it works | Test framework with assertions |
| **Runtime Discovery** | No API access | REST API + MCP server + Python client |
## 5-Minute Quick Start
@@ -182,6 +183,54 @@ skillkit memory export auth-insight --output auth-patterns.md
skillkit memory --global
```
### Runtime Skill Discovery
Start a REST API server or MCP server for agent-native skill discovery:
```bash
# Start REST API server (port 3737)
skillkit serve
# Custom port and host
skillkit serve --port 8080 --host localhost
# Endpoints:
# GET /search?q=react - Search skills
# POST /search - Search with filters
# GET /skills/owner/repo/id - Get specific skill
# GET /trending - Top skills by relevance
# GET /categories - Skill categories
# GET /health - Server health check
```
**MCP Server** for Claude Desktop, Cursor, and any MCP client:
```json
{
"mcpServers": {
"skillkit": {
"command": "npx",
"args": ["@skillkit/mcp"]
}
}
}
```
**Python Client:**
```bash
pip install skillkit-client
```
```python
from skillkit import SkillKitClient
async with SkillKitClient("http://localhost:3737") as client:
results = await client.search("react performance", limit=5)
skill = await client.get_skill("owner/repo", "skill-name")
trending = await client.trending(limit=10)
```
### Skill Marketplace
Browse and install from curated skill repositories:
@@ -328,6 +377,16 @@ skillkit find <query> # Quick skill search
skillkit check # Check skill health and updates
```
### Runtime Discovery Server
```bash
skillkit serve # Start REST API on :3737
skillkit serve --port 8080 # Custom port
skillkit serve --host localhost # Bind to localhost
skillkit serve --cors "http://localhost:3000" # Custom CORS
skillkit serve --cache-ttl 3600000 # Cache TTL (1hr)
```
### Translation & Context
```bash
@@ -597,6 +656,33 @@ console.log(mode.mode); // 'standalone' or 'enhanced'
console.log(mode.capabilities); // Available MCP capabilities
```
### REST API (TypeScript)
```typescript
import { createApp, startServer } from '@skillkit/api';
// Start with custom options
await startServer({
port: 3737,
corsOrigin: '*',
cacheTtlMs: 86_400_000,
skills: [...],
});
```
### Caching & Ranking
```typescript
import { MemoryCache, RelevanceRanker } from '@skillkit/core';
// LRU cache with TTL
const cache = new MemoryCache({ maxSize: 500, ttlMs: 86_400_000 });
// Multi-signal relevance scoring (0-100)
const ranker = new RelevanceRanker();
const results = ranker.rank(skills, 'react performance');
```
## Skill Sources & Attribution
SkillKit aggregates skills from trusted sources. We credit and link back to all original creators. Each source retains its original license.
+44 -1
View File
@@ -5,7 +5,7 @@ description: Complete reference for all SkillKit CLI commands
# CLI Commands
SkillKit provides 40+ commands organized into functional categories. Built on Clipanion v4 with interactive prompts via @clack/prompts.
SkillKit provides 50+ commands organized into functional categories. Built on Clipanion v4 with interactive prompts via @clack/prompts.
## Global Options
@@ -226,6 +226,49 @@ skillkit cicd gitlab-ci # Generate GitLab CI
skillkit cicd pre-commit # Generate pre-commit hooks
```
## Serve Command
Start the SkillKit REST API server for runtime skill discovery.
```bash
skillkit serve [options]
```
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--port` | `-p` | `3737` | Port to listen on |
| `--host` | `-H` | `0.0.0.0` | Host to bind to |
| `--cors` | — | `*` | CORS allowed origin |
| `--cache-ttl` | — | `86400000` | Cache TTL in milliseconds |
### Examples
```bash
# Start with defaults
skillkit serve
# Custom port and host
skillkit serve --port 8080 --host localhost
# Restricted CORS
skillkit serve --cors "http://localhost:3000"
# Short cache TTL (1 hour)
skillkit serve --cache-ttl 3600000
```
### Endpoints
| Method | Path | Description |
|--------|------|-------------|
| GET | `/search?q=...` | Search skills |
| POST | `/search` | Search with filters |
| GET | `/skills/:owner/:repo/:id` | Get specific skill |
| GET | `/trending?limit=20` | Trending skills |
| GET | `/categories` | Skill categories |
| GET | `/health` | Server health |
| GET | `/cache/stats` | Cache statistics |
## Utility Commands
```bash
+27 -2
View File
@@ -7,7 +7,7 @@ description: Universal CLI for managing AI agent skills across 32 coding platfor
SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across **32 AI coding platforms**.
**Current Version:** v1.8.0
**Current Version:** v1.12.0
## The Problem
@@ -49,6 +49,9 @@ skillkit sync
| **Workflow Orchestration** | Compose skills into multi-step automated workflows |
| **Skill Testing** | Built-in test framework with assertions |
| **CI/CD Integration** | GitHub Actions, GitLab CI, and pre-commit hooks |
| **REST API Server** | Runtime skill discovery via HTTP on port 3737 |
| **MCP Server** | Agent-native discovery for Claude Desktop, Cursor |
| **Python Client** | Async Python SDK for the REST API |
| **TypeScript API** | Full programmatic access to all features |
| **Interactive TUI** | Beautiful terminal interface with real-time updates |
@@ -100,11 +103,30 @@ skillkit message inbox # Check your inbox
[Learn more →](/docs/messaging)
### Runtime Skill Discovery
Start a REST API or MCP server for runtime skill discovery by agents and applications.
```bash
skillkit serve # REST API on :3737
```
```json
{
"mcpServers": {
"skillkit": { "command": "npx", "args": ["@skillkit/mcp"] }
}
}
```
[REST API →](/docs/rest-api) · [MCP Server →](/docs/mcp-server) · [Python Client →](/docs/python-client)
## Architecture
| Tier | Components |
|------|------------|
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/React), Documentation |
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/Solid.js), Documentation |
| **APIs** | @skillkit/api (REST/Hono), @skillkit/mcp (MCP/stdio) |
| **Business Logic** | @skillkit/core, @skillkit/agents (32 adapters) |
| **Data Layer** | @skillkit/memory (CozoDB), @skillkit/mesh (WebSocket/UDP) |
| **External Systems** | GitHub/GitLab, Marketplace (15,000+ skills) |
@@ -131,6 +153,9 @@ Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Anti
3. [Commands](/docs/commands) - Full CLI reference
4. [Skills](/docs/skills) - Skill format and lifecycle
5. [API Reference](/docs/api-reference) - Programmatic access
6. [REST API](/docs/rest-api) - Runtime discovery server
7. [MCP Server](/docs/mcp-server) - Agent-native discovery
8. [Python Client](/docs/python-client) - Python SDK
## Use Cases
+128
View File
@@ -0,0 +1,128 @@
---
title: MCP Server
description: Agent-native skill discovery via Model Context Protocol
---
# MCP Server
The `@skillkit/mcp` package provides a Model Context Protocol (MCP) server for agent-native skill discovery. It works with Claude Desktop, Cursor, and any MCP-compatible client.
## Setup
### Claude Desktop
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"skillkit": {
"command": "npx",
"args": ["@skillkit/mcp"]
}
}
}
```
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"skillkit": {
"command": "npx",
"args": ["@skillkit/mcp"]
}
}
}
```
### Any MCP Client
The server uses stdio transport. Run directly:
```bash
npx @skillkit/mcp
```
## Tools
The MCP server exposes 4 tools:
### search_skills
Search for skills by keyword, tag, or description.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `limit` | number | No | Max results (1-50, default 10) |
| `include_content` | boolean | No | Include full content |
| `include_references` | boolean | No | Include references |
| `filters.tags` | string[] | No | Filter by tags |
| `filters.category` | string | No | Filter by category |
| `filters.source` | string | No | Filter by source repo |
**Example prompt:** "Search for React performance optimization skills"
### get_skill
Get details of a specific skill.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | string | Yes | Skill source (e.g., `owner/repo`) |
| `skill_id` | string | Yes | Skill name |
| `include_references` | boolean | No | Include references |
**Example prompt:** "Get the pdf-processing skill from anthropics/skills"
### recommend_skills
Get skill recommendations based on your tech stack and current task.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `languages` | string[] | No | Programming languages |
| `frameworks` | string[] | No | Frameworks used |
| `libraries` | string[] | No | Libraries used |
| `task` | string | No | Current task description |
| `limit` | number | No | Max results (1-20, default 5) |
**Example prompt:** "Recommend skills for a TypeScript React project using Next.js"
### list_categories
List all skill categories with their counts.
**Example prompt:** "List all available skill categories"
## Resources
The MCP server exposes 2 resources:
| URI | Description |
|-----|-------------|
| `skills://trending` | Top 20 trending skills by relevance score |
| `skills://categories` | All skill categories with counts |
## How It Works
1. On startup, the server loads the skill catalog from `marketplace/skills.json`
2. Skills are indexed and available for search via the 4 tools
3. The `RelevanceRanker` from `@skillkit/core` scores results using multi-signal ranking
4. Results are returned as structured JSON via the MCP protocol
## Integration with AI Agents
Once configured, your AI agent can natively discover and recommend skills:
> "Search for skills related to authentication and security"
The agent will call `search_skills` and return ranked results with descriptions and sources.
> "What skills would you recommend for my React + TypeScript project?"
The agent will call `recommend_skills` with your stack context and return personalized recommendations.
+3
View File
@@ -20,6 +20,9 @@
"commands",
"configuration",
"api-reference",
"rest-api",
"mcp-server",
"python-client",
"cicd",
"teams",
"custom-agents",
@@ -0,0 +1,197 @@
---
title: Python Client
description: Async Python client for the SkillKit REST API
---
# Python Client
The `skillkit-client` package provides an async Python client for the SkillKit REST API.
## Installation
```bash
pip install skillkit-client
```
Requires Python 3.10+ with `httpx` and `pydantic`.
## Quick Start
```python
from skillkit import SkillKitClient
async with SkillKitClient("http://localhost:3737") as client:
# Search for skills
results = await client.search("react performance", limit=5)
for skill in results.skills:
print(f"{skill.name}: {skill.description}")
# Get trending skills
trending = await client.trending(limit=10)
# Get categories
categories = await client.categories()
```
## API Reference
### SkillKitClient
```python
SkillKitClient(base_url: str = "http://localhost:3737", timeout: float = 30.0)
```
Supports async context manager (`async with`) for automatic connection cleanup.
### Methods
#### search
```python
async def search(
query: str,
limit: int = 20,
include_content: bool = False,
) -> SearchResponse
```
Search skills by keyword. Returns `SearchResponse` with `skills`, `total`, `query`, and `limit`.
#### search_with_filters
```python
async def search_with_filters(
query: str,
limit: int = 20,
include_content: bool = False,
tags: list[str] | None = None,
category: str | None = None,
source: str | None = None,
) -> SearchResponse
```
Search with tag, category, and source filters via POST.
#### get_skill
```python
async def get_skill(source: str, skill_id: str) -> Skill
```
Get a specific skill by source (`owner/repo`) and name.
```python
skill = await client.get_skill("anthropics/skills", "pdf-processing")
print(skill.name, skill.description)
```
#### trending
```python
async def trending(limit: int = 20) -> list[Skill]
```
Get top trending skills ranked by relevance score.
#### categories
```python
async def categories() -> list[Category]
```
Get all skill categories with counts.
#### health
```python
async def health() -> HealthResponse
```
Check server health. Returns `status`, `version`, `skill_count`, `uptime`.
#### cache_stats
```python
async def cache_stats() -> CacheStats
```
Get cache statistics: `hits`, `misses`, `size`, `max_size`, `hit_rate`.
#### close
```python
async def close() -> None
```
Manually close the HTTP client. Not needed when using `async with`.
## Models
### Skill
```python
@dataclass
class Skill:
name: str
source: str
description: str | None
tags: list[str] | None
category: str | None
content: str | None
score: float | None
```
### SearchResponse
```python
@dataclass
class SearchResponse:
skills: list[Skill]
total: int
query: str
limit: int
```
### HealthResponse
```python
@dataclass
class HealthResponse:
status: str
version: str
skill_count: int
uptime: float
```
### Category
```python
@dataclass
class Category:
name: str
count: int
```
### CacheStats
```python
@dataclass
class CacheStats:
hits: int
misses: int
size: int
max_size: int
hit_rate: float
```
## Prerequisites
The Python client requires a running SkillKit API server:
```bash
# In one terminal
skillkit serve
# In another terminal / script
python my_script.py
```
+186
View File
@@ -0,0 +1,186 @@
---
title: REST API Server
description: Runtime skill discovery via HTTP REST API
---
# REST API Server
SkillKit includes a built-in REST API server for runtime skill discovery. Start it with the `serve` command or programmatically via `@skillkit/api`.
## Quick Start
```bash
# Start the API server
skillkit serve
# Server running at http://0.0.0.0:3737
```
## CLI Options
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--port` | `-p` | `3737` | Port to listen on |
| `--host` | `-H` | `0.0.0.0` | Host to bind to |
| `--cors` | — | `*` | CORS allowed origin |
| `--cache-ttl` | — | `86400000` | Cache TTL in ms (default 24h) |
```bash
skillkit serve --port 8080 --host localhost --cors "http://localhost:3000"
```
## Endpoints
### Search Skills
**GET** `/search?q=<query>&limit=20&include_content=false`
```bash
curl "http://localhost:3737/search?q=react+performance&limit=5"
```
```json
{
"skills": [
{
"name": "react-performance",
"description": "React app performance optimization",
"source": "anthropics/skills",
"tags": ["react", "performance"],
"score": 87
}
],
"total": 42,
"query": "react performance",
"limit": 5
}
```
**POST** `/search` — Search with filters
```bash
curl -X POST http://localhost:3737/search \
-H "Content-Type: application/json" \
-d '{
"query": "auth",
"limit": 10,
"filters": {
"tags": ["security"],
"category": "backend"
}
}'
```
### Get Specific Skill
**GET** `/skills/:owner/:repo/:id`
```bash
curl http://localhost:3737/skills/anthropics/skills/pdf-processing
```
### Trending Skills
**GET** `/trending?limit=20`
```bash
curl http://localhost:3737/trending?limit=10
```
Returns top skills ranked by multi-signal relevance score (content availability, popularity, references).
### Categories
**GET** `/categories`
```bash
curl http://localhost:3737/categories
```
```json
{
"categories": [
{ "name": "react", "count": 156 },
{ "name": "typescript", "count": 134 }
],
"total": 89
}
```
### Health Check
**GET** `/health`
```bash
curl http://localhost:3737/health
```
```json
{
"status": "ok",
"version": "1.12.0",
"skillCount": 15062,
"uptime": 3600
}
```
### Cache Statistics
**GET** `/cache/stats`
```bash
curl http://localhost:3737/cache/stats
```
## Rate Limiting
The server includes per-IP rate limiting (60 requests per minute by default). Response headers:
| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Max requests per window |
| `X-RateLimit-Remaining` | Remaining requests |
| `X-RateLimit-Reset` | Window reset timestamp |
Exceeding the limit returns HTTP 429 with a `retryAfter` field.
## Programmatic Usage
```typescript
import { createApp, startServer } from '@skillkit/api';
// Full server
const { server, app, cache } = await startServer({
port: 3737,
host: '0.0.0.0',
corsOrigin: '*',
cacheTtlMs: 86_400_000,
skills: [...],
});
// Or just the Hono app (for testing or custom servers)
const { app, cache } = createApp({
skills: [...],
cacheTtlMs: 3_600_000,
});
```
## Relevance Ranking
Search results are ranked using a multi-signal scoring system (0-100):
| Signal | Max Points | Description |
|--------|-----------|-------------|
| Content Availability | 40 | Has description and content |
| Query Match | 30 | Name/description match quality |
| Popularity | 15 | Log-scaled stars + installs |
| References | 15 | Has example files or docs |
## Caching
The server uses an in-memory LRU cache with configurable TTL. Search results are cached by query parameters to avoid redundant ranking computations.
```bash
# Set 1-hour cache TTL
skillkit serve --cache-ttl 3600000
```
+11 -1
View File
@@ -72,6 +72,16 @@ const COMMAND_GROUPS: CommandGroup[] = [
{ cmd: 'team sync', desc: 'Sync team skills' },
],
},
{
name: 'Server',
commands: [
{ cmd: 'serve', desc: 'Start REST API' },
{ cmd: 'serve --port 8080', desc: 'Custom port' },
{ cmd: 'serve --host localhost', desc: 'Bind host' },
{ cmd: 'serve --cors "*"', desc: 'Set CORS origin' },
{ cmd: 'serve --cache-ttl 3600000', desc: 'Cache TTL' },
],
},
{
name: 'Advanced',
commands: [
@@ -93,7 +103,7 @@ export function Commands(): React.ReactElement {
<section className="py-12 border-b border-zinc-800">
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="text-center mb-8">
<h2 className="text-xl font-bold text-white mb-2 font-mono">40+ Commands</h2>
<h2 className="text-xl font-bold text-white mb-2 font-mono">50+ Commands</h2>
<p className="text-zinc-500 font-mono text-sm">
Everything you need from the terminal.
</p>
+4 -3
View File
@@ -89,11 +89,11 @@ const FEATURES: Feature[] = [
)
},
{
title: 'TS API',
description: 'Programmatic access for custom tooling.',
title: 'REST & MCP APIs',
description: 'REST server, MCP server, and Python client for runtime discovery.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4" />
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01" />
</svg>
)
}
@@ -106,6 +106,7 @@ const COMPARISONS = [
['Translation', 'Rewrite for each', 'One-click conversion'],
['Team Sharing', 'Copy/paste files', '.skills manifest'],
['Discovery', 'Search forums', 'AI recommendations'],
['API Access', 'None', 'REST + MCP + Python'],
] as const;
export function Features(): React.ReactElement {
+7 -8
View File
@@ -20,17 +20,16 @@ interface TerminalLine {
}
const TERMINAL_LINES: TerminalLine[] = [
{ type: 'cmd', text: 'skillkit primer --all-agents' },
{ type: 'out', text: '→ Analyzing codebase...' },
{ type: 'out', text: ' ✓ Generated CLAUDE.md' },
{ type: 'out', text: ' ✓ Generated .cursorrules' },
{ type: 'cmd', text: 'skillkit install anthropics/skills --agent all' },
{ type: 'out', text: '→ Installed to 32 agents' },
{ type: 'cmd', text: 'skillkit recommend' },
{ type: 'out', text: ' 92% vercel-react-best-practices' },
{ type: 'out', text: ' 87% typescript-strict-mode' },
{ type: 'cmd', text: 'skillkit install anthropics/skills --agent all' },
{ type: 'out', text: '→ Installed to 32 agents' },
{ type: 'cmd', text: 'skillkit memory compress' },
{ type: 'out', text: '→ 12 learnings persisted' },
{ type: 'cmd', text: 'skillkit serve' },
{ type: 'out', text: '→ API server on http://0.0.0.0:3737' },
{ type: 'out', text: ' GET /search · /trending · /categories' },
{ type: 'cmd', text: 'curl localhost:3737/search?q=react' },
{ type: 'out', text: ' {"skills":[...],"total":42}' },
];
const FADE_ANIMATION_STYLES = `