Skip to content

Commit 19694dc

Browse files
rohitg00rohitg00
committed
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
1 parent b432400 commit 19694dc

File tree

10 files changed

+693
-15
lines changed

10 files changed

+693
-15
lines changed

‎README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ SkillKit features a polished, interactive CLI with visual feedback:
8181
| **Context Sync** | Configure each agent separately | One config, synced everywhere |
8282
| **Session Memory** | Knowledge dies with each session | Persistent learning across agents |
8383
| **Skill Testing** | Hope it works | Test framework with assertions |
84+
| **Runtime Discovery** | No API access | REST API + MCP server + Python client |
8485

8586
## 5-Minute Quick Start
8687

@@ -182,6 +183,54 @@ skillkit memory export auth-insight --output auth-patterns.md
182183
skillkit memory --global
183184
```
184185

186+
### Runtime Skill Discovery
187+
188+
Start a REST API server or MCP server for agent-native skill discovery:
189+
190+
```bash
191+
# Start REST API server (port 3737)
192+
skillkit serve
193+
194+
# Custom port and host
195+
skillkit serve --port 8080 --host localhost
196+
197+
# Endpoints:
198+
# GET /search?q=react - Search skills
199+
# POST /search - Search with filters
200+
# GET /skills/owner/repo/id - Get specific skill
201+
# GET /trending - Top skills by relevance
202+
# GET /categories - Skill categories
203+
# GET /health - Server health check
204+
```
205+
206+
**MCP Server** for Claude Desktop, Cursor, and any MCP client:
207+
208+
```json
209+
{
210+
"mcpServers": {
211+
"skillkit": {
212+
"command": "npx",
213+
"args": ["@skillkit/mcp"]
214+
}
215+
}
216+
}
217+
```
218+
219+
**Python Client:**
220+
221+
```bash
222+
pip install skillkit-client
223+
```
224+
225+
```python
226+
from skillkit import SkillKitClient
227+
228+
async with SkillKitClient("http://localhost:3737") as client:
229+
results = await client.search("react performance", limit=5)
230+
skill = await client.get_skill("owner/repo", "skill-name")
231+
trending = await client.trending(limit=10)
232+
```
233+
185234
### Skill Marketplace
186235

187236
Browse and install from curated skill repositories:
@@ -328,6 +377,16 @@ skillkit find <query> # Quick skill search
328377
skillkit check # Check skill health and updates
329378
```
330379

380+
### Runtime Discovery Server
381+
382+
```bash
383+
skillkit serve # Start REST API on :3737
384+
skillkit serve --port 8080 # Custom port
385+
skillkit serve --host localhost # Bind to localhost
386+
skillkit serve --cors "http://localhost:3000" # Custom CORS
387+
skillkit serve --cache-ttl 3600000 # Cache TTL (1hr)
388+
```
389+
331390
### Translation & Context
332391

333392
```bash
@@ -597,6 +656,33 @@ console.log(mode.mode); // 'standalone' or 'enhanced'
597656
console.log(mode.capabilities); // Available MCP capabilities
598657
```
599658

659+
### REST API (TypeScript)
660+
661+
```typescript
662+
import { createApp, startServer } from '@skillkit/api';
663+
664+
// Start with custom options
665+
await startServer({
666+
port: 3737,
667+
corsOrigin: '*',
668+
cacheTtlMs: 86_400_000,
669+
skills: [...],
670+
});
671+
```
672+
673+
### Caching & Ranking
674+
675+
```typescript
676+
import { MemoryCache, RelevanceRanker } from '@skillkit/core';
677+
678+
// LRU cache with TTL
679+
const cache = new MemoryCache({ maxSize: 500, ttlMs: 86_400_000 });
680+
681+
// Multi-signal relevance scoring (0-100)
682+
const ranker = new RelevanceRanker();
683+
const results = ranker.rank(skills, 'react performance');
684+
```
685+
600686
## Skill Sources & Attribution
601687

602688
SkillKit aggregates skills from trusted sources. We credit and link back to all original creators. Each source retains its original license.

‎docs/fumadocs/content/docs/commands.mdx‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Complete reference for all SkillKit CLI commands
55

66
# CLI Commands
77

8-
SkillKit provides 40+ commands organized into functional categories. Built on Clipanion v4 with interactive prompts via @clack/prompts.
8+
SkillKit provides 50+ commands organized into functional categories. Built on Clipanion v4 with interactive prompts via @clack/prompts.
99

1010
## Global Options
1111

@@ -226,6 +226,49 @@ skillkit cicd gitlab-ci # Generate GitLab CI
226226
skillkit cicd pre-commit # Generate pre-commit hooks
227227
```
228228

229+
## Serve Command
230+
231+
Start the SkillKit REST API server for runtime skill discovery.
232+
233+
```bash
234+
skillkit serve [options]
235+
```
236+
237+
| Option | Short | Default | Description |
238+
|--------|-------|---------|-------------|
239+
| `--port` | `-p` | `3737` | Port to listen on |
240+
| `--host` | `-H` | `0.0.0.0` | Host to bind to |
241+
| `--cors` | — | `*` | CORS allowed origin |
242+
| `--cache-ttl` | — | `86400000` | Cache TTL in milliseconds |
243+
244+
### Examples
245+
246+
```bash
247+
# Start with defaults
248+
skillkit serve
249+
250+
# Custom port and host
251+
skillkit serve --port 8080 --host localhost
252+
253+
# Restricted CORS
254+
skillkit serve --cors "http://localhost:3000"
255+
256+
# Short cache TTL (1 hour)
257+
skillkit serve --cache-ttl 3600000
258+
```
259+
260+
### Endpoints
261+
262+
| Method | Path | Description |
263+
|--------|------|-------------|
264+
| GET | `/search?q=...` | Search skills |
265+
| POST | `/search` | Search with filters |
266+
| GET | `/skills/:owner/:repo/:id` | Get specific skill |
267+
| GET | `/trending?limit=20` | Trending skills |
268+
| GET | `/categories` | Skill categories |
269+
| GET | `/health` | Server health |
270+
| GET | `/cache/stats` | Cache statistics |
271+
229272
## Utility Commands
230273

231274
```bash

‎docs/fumadocs/content/docs/index.mdx‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: Universal CLI for managing AI agent skills across 32 coding platfor
77

88
SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across **32 AI coding platforms**.
99

10-
**Current Version:** v1.8.0
10+
**Current Version:** v1.12.0
1111

1212
## The Problem
1313

@@ -49,6 +49,9 @@ skillkit sync
4949
| **Workflow Orchestration** | Compose skills into multi-step automated workflows |
5050
| **Skill Testing** | Built-in test framework with assertions |
5151
| **CI/CD Integration** | GitHub Actions, GitLab CI, and pre-commit hooks |
52+
| **REST API Server** | Runtime skill discovery via HTTP on port 3737 |
53+
| **MCP Server** | Agent-native discovery for Claude Desktop, Cursor |
54+
| **Python Client** | Async Python SDK for the REST API |
5255
| **TypeScript API** | Full programmatic access to all features |
5356
| **Interactive TUI** | Beautiful terminal interface with real-time updates |
5457

@@ -100,11 +103,30 @@ skillkit message inbox # Check your inbox
100103

101104
[Learn more →](/docs/messaging)
102105

106+
### Runtime Skill Discovery
107+
108+
Start a REST API or MCP server for runtime skill discovery by agents and applications.
109+
110+
```bash
111+
skillkit serve # REST API on :3737
112+
```
113+
114+
```json
115+
{
116+
"mcpServers": {
117+
"skillkit": { "command": "npx", "args": ["@skillkit/mcp"] }
118+
}
119+
}
120+
```
121+
122+
[REST API →](/docs/rest-api) · [MCP Server →](/docs/mcp-server) · [Python Client →](/docs/python-client)
123+
103124
## Architecture
104125

105126
| Tier | Components |
106127
|------|------------|
107-
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/React), Documentation |
128+
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/Solid.js), Documentation |
129+
| **APIs** | @skillkit/api (REST/Hono), @skillkit/mcp (MCP/stdio) |
108130
| **Business Logic** | @skillkit/core, @skillkit/agents (32 adapters) |
109131
| **Data Layer** | @skillkit/memory (CozoDB), @skillkit/mesh (WebSocket/UDP) |
110132
| **External Systems** | GitHub/GitLab, Marketplace (15,000+ skills) |
@@ -131,6 +153,9 @@ Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Anti
131153
3. [Commands](/docs/commands) - Full CLI reference
132154
4. [Skills](/docs/skills) - Skill format and lifecycle
133155
5. [API Reference](/docs/api-reference) - Programmatic access
156+
6. [REST API](/docs/rest-api) - Runtime discovery server
157+
7. [MCP Server](/docs/mcp-server) - Agent-native discovery
158+
8. [Python Client](/docs/python-client) - Python SDK
134159

135160
## Use Cases
136161

‎docs/fumadocs/content/docs/mcp-server.mdx‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: MCP Server
3+
description: Agent-native skill discovery via Model Context Protocol
4+
---
5+
6+
# MCP Server
7+
8+
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.
9+
10+
## Setup
11+
12+
### Claude Desktop
13+
14+
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
15+
16+
```json
17+
{
18+
"mcpServers": {
19+
"skillkit": {
20+
"command": "npx",
21+
"args": ["@skillkit/mcp"]
22+
}
23+
}
24+
}
25+
```
26+
27+
### Cursor
28+
29+
Add to `.cursor/mcp.json`:
30+
31+
```json
32+
{
33+
"mcpServers": {
34+
"skillkit": {
35+
"command": "npx",
36+
"args": ["@skillkit/mcp"]
37+
}
38+
}
39+
}
40+
```
41+
42+
### Any MCP Client
43+
44+
The server uses stdio transport. Run directly:
45+
46+
```bash
47+
npx @skillkit/mcp
48+
```
49+
50+
## Tools
51+
52+
The MCP server exposes 4 tools:
53+
54+
### search_skills
55+
56+
Search for skills by keyword, tag, or description.
57+
58+
| Parameter | Type | Required | Description |
59+
|-----------|------|----------|-------------|
60+
| `query` | string | Yes | Search query |
61+
| `limit` | number | No | Max results (1-50, default 10) |
62+
| `include_content` | boolean | No | Include full content |
63+
| `include_references` | boolean | No | Include references |
64+
| `filters.tags` | string[] | No | Filter by tags |
65+
| `filters.category` | string | No | Filter by category |
66+
| `filters.source` | string | No | Filter by source repo |
67+
68+
**Example prompt:** "Search for React performance optimization skills"
69+
70+
### get_skill
71+
72+
Get details of a specific skill.
73+
74+
| Parameter | Type | Required | Description |
75+
|-----------|------|----------|-------------|
76+
| `source` | string | Yes | Skill source (e.g., `owner/repo`) |
77+
| `skill_id` | string | Yes | Skill name |
78+
| `include_references` | boolean | No | Include references |
79+
80+
**Example prompt:** "Get the pdf-processing skill from anthropics/skills"
81+
82+
### recommend_skills
83+
84+
Get skill recommendations based on your tech stack and current task.
85+
86+
| Parameter | Type | Required | Description |
87+
|-----------|------|----------|-------------|
88+
| `languages` | string[] | No | Programming languages |
89+
| `frameworks` | string[] | No | Frameworks used |
90+
| `libraries` | string[] | No | Libraries used |
91+
| `task` | string | No | Current task description |
92+
| `limit` | number | No | Max results (1-20, default 5) |
93+
94+
**Example prompt:** "Recommend skills for a TypeScript React project using Next.js"
95+
96+
### list_categories
97+
98+
List all skill categories with their counts.
99+
100+
**Example prompt:** "List all available skill categories"
101+
102+
## Resources
103+
104+
The MCP server exposes 2 resources:
105+
106+
| URI | Description |
107+
|-----|-------------|
108+
| `skills://trending` | Top 20 trending skills by relevance score |
109+
| `skills://categories` | All skill categories with counts |
110+
111+
## How It Works
112+
113+
1. On startup, the server loads the skill catalog from `marketplace/skills.json`
114+
2. Skills are indexed and available for search via the 4 tools
115+
3. The `RelevanceRanker` from `@skillkit/core` scores results using multi-signal ranking
116+
4. Results are returned as structured JSON via the MCP protocol
117+
118+
## Integration with AI Agents
119+
120+
Once configured, your AI agent can natively discover and recommend skills:
121+
122+
> "Search for skills related to authentication and security"
123+
124+
The agent will call `search_skills` and return ranked results with descriptions and sources.
125+
126+
> "What skills would you recommend for my React + TypeScript project?"
127+
128+
The agent will call `recommend_skills` with your stack context and return personalized recommendations.

‎docs/fumadocs/content/docs/meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@
2020
"commands",
2121
"configuration",
2222
"api-reference",
23+
"rest-api",
24+
"mcp-server",
25+
"python-client",
2326
"cicd",
2427
"teams",
2528
"custom-agents",

0 commit comments

Comments
 (0)