diff --git a/README.md b/README.md index 3166089b..8663e312 100644 --- a/README.md +++ b/README.md @@ -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 # 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. diff --git a/docs/fumadocs/content/docs/commands.mdx b/docs/fumadocs/content/docs/commands.mdx index bb9be6ff..3e05bb20 100644 --- a/docs/fumadocs/content/docs/commands.mdx +++ b/docs/fumadocs/content/docs/commands.mdx @@ -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 diff --git a/docs/fumadocs/content/docs/index.mdx b/docs/fumadocs/content/docs/index.mdx index 5df54d32..b9a76c0d 100644 --- a/docs/fumadocs/content/docs/index.mdx +++ b/docs/fumadocs/content/docs/index.mdx @@ -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 diff --git a/docs/fumadocs/content/docs/mcp-server.mdx b/docs/fumadocs/content/docs/mcp-server.mdx new file mode 100644 index 00000000..fe7135bd --- /dev/null +++ b/docs/fumadocs/content/docs/mcp-server.mdx @@ -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. diff --git a/docs/fumadocs/content/docs/meta.json b/docs/fumadocs/content/docs/meta.json index a455a4f1..c4cb7af9 100644 --- a/docs/fumadocs/content/docs/meta.json +++ b/docs/fumadocs/content/docs/meta.json @@ -20,6 +20,9 @@ "commands", "configuration", "api-reference", + "rest-api", + "mcp-server", + "python-client", "cicd", "teams", "custom-agents", diff --git a/docs/fumadocs/content/docs/python-client.mdx b/docs/fumadocs/content/docs/python-client.mdx new file mode 100644 index 00000000..fdd2eff6 --- /dev/null +++ b/docs/fumadocs/content/docs/python-client.mdx @@ -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 +``` diff --git a/docs/fumadocs/content/docs/rest-api.mdx b/docs/fumadocs/content/docs/rest-api.mdx new file mode 100644 index 00000000..49efe444 --- /dev/null +++ b/docs/fumadocs/content/docs/rest-api.mdx @@ -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=&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 +``` diff --git a/docs/skillkit/components/Commands.tsx b/docs/skillkit/components/Commands.tsx index 4a49d1ea..082a46d7 100644 --- a/docs/skillkit/components/Commands.tsx +++ b/docs/skillkit/components/Commands.tsx @@ -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 {
-

40+ Commands

+

50+ Commands

Everything you need from the terminal.

diff --git a/docs/skillkit/components/Features.tsx b/docs/skillkit/components/Features.tsx index 428d7f08..ae1583f8 100644 --- a/docs/skillkit/components/Features.tsx +++ b/docs/skillkit/components/Features.tsx @@ -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: ( - + ) } @@ -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 { diff --git a/docs/skillkit/components/Hero.tsx b/docs/skillkit/components/Hero.tsx index e04de192..beac6641 100644 --- a/docs/skillkit/components/Hero.tsx +++ b/docs/skillkit/components/Hero.tsx @@ -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 = `