diff --git a/docs/fumadocs/content/docs/index.mdx b/docs/fumadocs/content/docs/index.mdx index b9a76c0d..2aeeff4b 100644 --- a/docs/fumadocs/content/docs/index.mdx +++ b/docs/fumadocs/content/docs/index.mdx @@ -1,116 +1,76 @@ --- -title: SkillKit Documentation -description: Universal CLI for managing AI agent skills across 32 coding platforms +title: SkillKit +description: Universal skill management for AI coding agents --- # SkillKit -SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across **32 AI coding platforms**. +Skills make AI coding agents smarter. But every agent uses a different format — Claude Code wants `.claude/skills/`, Cursor uses `.mdc`, Copilot expects `.github/skills/`. You end up rewriting the same skill three times, or locking into one platform. -**Current Version:** v1.12.0 +SkillKit fixes this. Write a skill once, deploy it to all 32 agents. -## The Problem - -Each AI coding agent uses different skill formats and directory structures: -- Claude Code uses `.claude/skills/` with SKILL.md -- Cursor uses `.cursor/skills/` with .mdc format -- GitHub Copilot uses `.github/skills/` - -Without SkillKit, you either rewrite skills for each agent, lock into one platform, or abandon skills entirely. - -## The Solution - -SkillKit provides a **"write once, deploy everywhere"** platform. Maintain a single skill definition that automatically translates across all 32 platforms. - -## Quick Install +## Get Started ```bash -# Run instantly with npx (no install required) npx skillkit@latest +``` + +That's it. No global install needed. Or if you prefer: -# Or install globally for frequent use +```bash npm install -g skillkit skillkit init skillkit install anthropics/skills skillkit sync ``` -## Core Features - -| Feature | Description | -|---------|-------------| -| **Cross-Platform Translation** | Automatic conversion between 32 agent formats | -| **Smart Recommendations** | AI-powered skill suggestions based on your tech stack | -| **Session Memory** | Persistent learning that survives across sessions | -| **Primer** | Auto-generate agent instructions from your codebase | -| **Mesh Network** | Multi-machine agent distribution with encrypted P2P | -| **Inter-Agent Messaging** | Send messages between AI agents across your network | -| **Team Collaboration** | Git-based `.skills` manifest for sharing | -| **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 | - -## Advanced Capabilities +Four commands. Your agents now have skills for PDF processing, code review, and more. -### Session Memory System +## What Can You Do? -Your AI agents learn patterns during sessions—then forget everything. SkillKit captures these learnings and makes them permanent. +### Install skills from anywhere ```bash -skillkit memory compress # Compress learnings -skillkit memory search auth # Search knowledge -skillkit memory export auth-patterns # Export as skill +skillkit install anthropics/skills # GitHub +skillkit install gitlab:team/skills # GitLab +skillkit install ./my-local-skills # Local ``` -[Learn more →](/docs/memory) +### Translate between agents -### Primer - Auto-Generate Instructions - -Automatically generate CLAUDE.md, .cursorrules, and agent instructions by analyzing your codebase. +Write for Claude, deploy to Cursor: ```bash -skillkit primer # Analyze project -skillkit primer --all-agents # Generate for all 32 agents +skillkit translate my-skill --to cursor +skillkit translate --all --to windsurf # All skills at once ``` -[Learn more →](/docs/primer) - -### Mesh Network +### Get smart recommendations -Run agents across multiple machines with encrypted P2P communication. +SkillKit reads your `package.json`, detects your stack, and suggests relevant skills: ```bash -skillkit mesh init # Initialize mesh node -skillkit mesh discover # Find peers on LAN -skillkit mesh security init # Setup Ed25519 encryption +skillkit recommend +# 92% vercel-react-best-practices +# 87% tailwind-v4-patterns +# 85% nextjs-app-router ``` -[Learn more →](/docs/mesh) +### Discover skills at runtime -### Inter-Agent Messaging - -Send messages between AI agents across your mesh network. +Start an API server and let agents find skills on demand: ```bash -skillkit message send # Send to another agent -skillkit message inbox # Check your inbox +skillkit serve +# Server running at http://localhost:3737 ``` -[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 +curl "http://localhost:3737/search?q=react+performance" ``` +Or use MCP for native agent integration: + ```json { "mcpServers": { @@ -119,55 +79,75 @@ skillkit serve # REST API on :3737 } ``` -[REST API →](/docs/rest-api) · [MCP Server →](/docs/mcp-server) · [Python Client →](/docs/python-client) +[REST API](/docs/rest-api) | [MCP Server](/docs/mcp-server) | [Python Client](/docs/python-client) -## Architecture +## How It Works -| Tier | Components | -|------|------------| -| **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) | +SkillKit sits between your skills and your agents. It handles format translation, discovery, and synchronization automatically. -## Supported Agents (32) +| Layer | What It Does | +|-------|-------------| +| **CLI + TUI** | Install, translate, recommend, sync | +| **APIs** | REST server on :3737, MCP via stdio | +| **Core** | Translation engine, relevance ranker, skill parser | +| **Data** | 15,000+ skills from 31 curated sources | -Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Amp, Clawdbot, Droid, Goose, Kilo Code, Kiro CLI, Roo Code, Trae, Cline, CodeBuddy, Continue, Crush, Factory, MCPJam, Mux, Neovate, OpenHands, Pi, Qoder, Qwen, Vercel, Zencoder, CommandCode, Universal +## Supported Agents -[Full agent details →](/docs/agents) +32 agents and counting: -## Popular Skill Sources +**Claude Code** | **Cursor** | **Codex** | **Gemini CLI** | **OpenCode** | **GitHub Copilot** | **Windsurf** | Amp | Antigravity | Clawdbot | Cline | CodeBuddy | CommandCode | Continue | Crush | Droid | Factory | Goose | Kilo Code | Kiro CLI | MCPJam | Mux | Neovate | OpenHands | Pi | Qoder | Qwen | Roo Code | Trae | Vercel | Zencoder | Universal -| Repository | Skills | -|------------|--------| -| anthropics/skills | PDF, XLSX, DOCX processing | -| vercel-labs/agent-skills | React/Next.js best practices | -| nextlevelbuilder/ui-ux-pro-max-skill | UI/UX design patterns | -| superdesigndev/superdesign-skill | Modern design systems | +[Full agent details](/docs/agents) -## Get Started +## Beyond Basic Skills + +### Session Memory + +Your AI agents learn patterns during sessions, then forget everything. SkillKit captures those learnings and makes them permanent. + +```bash +skillkit memory compress +skillkit memory search "auth patterns" +skillkit memory export auth-patterns +``` + +### Primer + +Auto-generate CLAUDE.md, .cursorrules, and agent instructions by analyzing your codebase: + +```bash +skillkit primer --all-agents +``` + +### Mesh Network + +Distribute agents across machines with encrypted P2P: + +```bash +skillkit mesh init +skillkit mesh discover +``` + +### Team Collaboration + +Share skills via a Git-committable `.skills` manifest: + +```bash +skillkit manifest init +skillkit manifest add anthropics/skills +git commit -m "add team skills" +``` + +Team members run `skillkit manifest install` and they're in sync. + +## Next Steps + +- [Installation](/docs/installation) — Install and configure +- [Quick Start](/docs/quickstart) — First project setup +- [Commands](/docs/commands) — Full CLI reference +- [REST API](/docs/rest-api) — Runtime discovery server +- [MCP Server](/docs/mcp-server) — Agent-native discovery +- [Python Client](/docs/python-client) — Python SDK -1. [Installation](/docs/installation) - Install and initialize -2. [Quick Start](/docs/quickstart) - 5-minute guide -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 - -- **Multi-Agent Developer** - Write skills once, use across Claude, Cursor, Windsurf, and more -- **Team Lead** - Share skills via Git-based manifest, ensure team alignment -- **New Project Starter** - Auto-generate agent instructions with Primer -- **Enterprise Architect** - Distribute agents across multiple machines with Mesh Network - -## Enterprise Features - -- **Private Registries** - Host internal skills in private repos -- **Git-Based Sync** - Skills live in your repo, push to share -- **CI/CD Integration** - Auto-validate and deploy skills on every commit -- **TypeScript API** - Full programmatic access for custom workflows -- **Security** - Ed25519 encryption, XChaCha20-Poly1305, TLS 1.3 +**Current version:** v1.12.0 | [npm](https://www.npmjs.com/package/skillkit) | [GitHub](https://github.com/rohitg00/skillkit) | Apache-2.0 diff --git a/docs/fumadocs/content/docs/installation.mdx b/docs/fumadocs/content/docs/installation.mdx index 2b79e467..e84aec7f 100644 --- a/docs/fumadocs/content/docs/installation.mdx +++ b/docs/fumadocs/content/docs/installation.mdx @@ -5,139 +5,82 @@ description: Install SkillKit and set up your first project # Installation -SkillKit is distributed as an npm package. Current version: **v1.8.0** +## No install needed -## Quick Start (No Install) +The fastest way to start: ```bash -# Run without installing npx skillkit@latest - -# Run specific commands -npx skillkit recommend -npx skillkit install anthropics/skills ``` -## Install Globally +This runs the latest version directly. No global install, no setup. + +## Global install + +For frequent use, install globally: ```bash npm install -g skillkit ``` -The CLI provides two command aliases: `skillkit` and `sk` (shorthand). - -## Alternative Methods +Also works with pnpm, yarn, or bun: ```bash -# pnpm pnpm add -g skillkit - -# yarn yarn global add skillkit - -# bun bun add -g skillkit - -# npx (no install required) -npx skillkit ``` -## GitHub Packages - -```bash -npm install -g @rohitg00/skillkit --registry=https://npm.pkg.github.com -``` +Both `skillkit` and `sk` work as command aliases. -## Verify Installation +## Verify ```bash skillkit --version -# or -sk --version ``` -## Requirements +**Requirements:** Node.js 18+ (Bun 1.2+ for the TUI). -- **Node.js** 18.0.0 or higher -- **Bun** 1.2.0 or higher (for TUI only) +## Initialize a project -## First Run Experience - -When you run SkillKit for the first time, it initiates an interactive onboarding that: +```bash +cd my-project +skillkit init +``` -1. Detects your current AI agent automatically -2. Creates necessary project directories -3. Gathers user preferences for future sessions -4. Displays contextual guidance +The init command: -Preferences are stored in `~/.skillkit/preferences.json`. +1. **Detects your AI agent** — scans for `.claude/`, `.cursor/`, `.github/` directories +2. **Creates the skills folder** — sets up the right directory for your agent +3. **Saves preferences** — remembers your choices for next time -## Initialize a Project +### Specify an agent directly ```bash -skillkit init +skillkit init --agent cursor +skillkit init --list # Show all 32 supported agents +skillkit init --quiet # Skip logo and prompts (for CI) ``` -### Init Command Options +### What gets created -| Flag | Short | Purpose | -|------|-------|---------| -| `--agent` | `-a` | Specify target agent (auto-detected if omitted) | -| `--list` | `-l` | Display all supported agents | -| `--quiet` | `-q` | Suppress welcome logo and confirmations | - -### What Init Creates - -| Agent | Skills Directory | Config File | -|-------|-----------------|-------------| +| Agent | Skills Directory | Config | +|-------|-----------------|--------| | Claude Code | `.claude/skills/` | `.claude/config.json` | | Cursor | `.cursor/skills/` | `.cursor/config.mdc` | | Codex | `.codex/skills/` | `AGENTS.md` | | GitHub Copilot | `.github/skills/` | — | | Universal | `skills/` | `AGENTS.md` | -## Visual Theme - -The CLI adapts its logo based on terminal width: - -- **≥70 columns** - Full ASCII art with block characters -- **50-69 columns** - Spaced text display -- **less than 50 columns** - Minimal format with symbols - -## Agent Icons - -| Agent | Icon | -|-------|------| -| Claude Code | ⟁ | -| Cursor | ◫ | -| Codex | ◎ | -| Gemini CLI | ✦ | -| OpenCode | ⬡ | - -## Non-Interactive Mode +Preferences are stored in `~/.skillkit/preferences.json`. -For CI/CD or piped input environments: +## Next steps ```bash -skillkit init --quiet +skillkit recommend # Get skill suggestions for your project +skillkit install anthropics/skills # Install skills from GitHub +skillkit sync # Deploy to your agent +skillkit ui # Launch the terminal UI ``` -This skips the welcome logo, runs agent detection automatically, and produces minimal output. - -## Next Steps - -After installation, continue with: - -```bash -# Install skills from GitHub -skillkit install anthropics/skills - -# Browse marketplace -skillkit marketplace - -# Synchronize to agent directories -skillkit sync - -# Launch interactive terminal UI -skillkit ui -``` +[Quick Start guide](/docs/quickstart) | [Full command reference](/docs/commands) diff --git a/docs/fumadocs/content/docs/mcp-server.mdx b/docs/fumadocs/content/docs/mcp-server.mdx index fe7135bd..23b80ab4 100644 --- a/docs/fumadocs/content/docs/mcp-server.mdx +++ b/docs/fumadocs/content/docs/mcp-server.mdx @@ -5,13 +5,15 @@ 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. +The REST API works great for HTTP clients. But AI agents speak MCP — the Model Context Protocol. The `@skillkit/mcp` package lets agents discover skills natively, without HTTP calls or curl commands. + +Think of it as giving your agent a direct line to the entire skill catalog. ## Setup ### Claude Desktop -Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`): +Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { @@ -24,9 +26,11 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/ } ``` +Restart Claude Desktop. Done. + ### Cursor -Add to `.cursor/mcp.json`: +Add to `.cursor/mcp.json` in your project: ```json { @@ -39,90 +43,63 @@ Add to `.cursor/mcp.json`: } ``` -### Any MCP Client +### Any MCP client -The server uses stdio transport. Run directly: +The server uses stdio transport. Works with any MCP-compatible client: ```bash npx @skillkit/mcp ``` -## Tools - -The MCP server exposes 4 tools: +## What your agent can do -### search_skills +Once connected, your agent gets four tools: -Search for skills by keyword, tag, or description. +### Search skills -| 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 | +Ask your agent: *"Find skills for React performance optimization"* -**Example prompt:** "Search for React performance optimization skills" +Behind the scenes, it calls `search_skills` with your query and returns ranked results. You can filter by tags, category, or source repository. -### get_skill +``` +> Search for authentication skills tagged with "security" +``` -Get details of a specific skill. +The agent searches across the full catalog, ranks results by relevance, and shows you the best matches. -| 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 | +### Get a specific skill -**Example prompt:** "Get the pdf-processing skill from anthropics/skills" +Ask: *"Get the pdf-processing skill from anthropics/skills"* -### recommend_skills +The agent calls `get_skill` and returns the full skill details — description, tags, content, and references. -Get skill recommendations based on your tech stack and current task. +### Get recommendations -| 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) | +Ask: *"What skills would you recommend for my TypeScript React project?"* -**Example prompt:** "Recommend skills for a TypeScript React project using Next.js" +The agent calls `recommend_skills` with your stack context (languages, frameworks, libraries) and returns personalized suggestions ranked by relevance. -### list_categories +### Browse categories -List all skill categories with their counts. +Ask: *"What skill categories are available?"* -**Example prompt:** "List all available skill categories" +The agent calls `list_categories` and returns all categories with counts, so you know what's out there. ## 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 +The server also exposes two read-only resources: -Once configured, your AI agent can natively discover and recommend skills: +- **`skills://trending`** — Top 20 skills by relevance score +- **`skills://categories`** — All categories with counts -> "Search for skills related to authentication and security" +Agents can read these without making a tool call. -The agent will call `search_skills` and return ranked results with descriptions and sources. +## How it works -> "What skills would you recommend for my React + TypeScript project?" +1. On startup, the server loads all skills from the marketplace catalog +2. Your agent sends a natural language request +3. The MCP client translates it into a tool call +4. The `RelevanceRanker` scores and ranks results (same algorithm as the REST API) +5. Results come back as structured JSON through the MCP protocol -The agent will call `recommend_skills` with your stack context and return personalized recommendations. +Same ranking, same data, same quality — just native to your agent instead of going through HTTP. diff --git a/docs/fumadocs/content/docs/python-client.mdx b/docs/fumadocs/content/docs/python-client.mdx index fdd2eff6..8cfd0c51 100644 --- a/docs/fumadocs/content/docs/python-client.mdx +++ b/docs/fumadocs/content/docs/python-client.mdx @@ -1,197 +1,105 @@ --- title: Python Client -description: Async Python client for the SkillKit REST API +description: Async Python SDK for skill discovery --- # Python Client -The `skillkit-client` package provides an async Python client for the SkillKit REST API. +Not everything runs on Node. The `skillkit-client` package gives Python apps the same skill discovery capabilities as the REST API — async, typed, and ready to go. -## Installation +## Install ```bash pip install skillkit-client ``` -Requires Python 3.10+ with `httpx` and `pydantic`. +Requires Python 3.10+. -## Quick Start +## Quick start ```python from skillkit import SkillKitClient -async with SkillKitClient("http://localhost:3737") as client: - # Search for skills +async with SkillKitClient() as client: 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 -``` +The client connects to `http://localhost:3737` by default. Make sure the API server is running: -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 +```bash +skillkit serve ``` -Search with tag, category, and source filters via POST. - -#### get_skill +## Search with filters ```python -async def get_skill(source: str, skill_id: str) -> Skill +results = await client.search_with_filters( + "authentication", + tags=["security"], + category="backend", + limit=10, +) ``` -Get a specific skill by source (`owner/repo`) and name. +## Get a specific skill ```python skill = await client.get_skill("anthropics/skills", "pdf-processing") -print(skill.name, skill.description) +print(skill.name, skill.description, skill.tags) ``` -#### trending +## Trending and categories ```python -async def trending(limit: int = 20) -> list[Skill] -``` - -Get top trending skills ranked by relevance score. +trending = await client.trending(limit=10) +categories = await client.categories() -#### categories +for skill in trending: + print(f"{skill.name} ({skill.source})") -```python -async def categories() -> list[Category] +for cat in categories: + print(f"{cat.name}: {cat.count} skills") ``` -Get all skill categories with counts. - -#### health +## Health and cache ```python -async def health() -> HealthResponse -``` +health = await client.health() +print(f"v{health.version} — {health.skill_count} skills loaded") -Check server health. Returns `status`, `version`, `skill_count`, `uptime`. - -#### cache_stats - -```python -async def cache_stats() -> CacheStats +stats = await client.cache_stats() +print(f"Cache hit rate: {stats.hit_rate:.0%}") ``` -Get cache statistics: `hits`, `misses`, `size`, `max_size`, `hit_rate`. - -#### close +## Connect to a remote server ```python -async def close() -> None +async with SkillKitClient("https://my-server.example.com:3737") as client: + results = await client.search("deployment") ``` -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 +The client returns typed dataclasses: ```python -@dataclass -class Category: - name: str - count: int +Skill(name, source, description, tags, category, content, score) +SearchResponse(skills, total, query, limit) +HealthResponse(status, version, skill_count, uptime) +Category(name, count) +CacheStats(hits, misses, size, max_size, hit_rate) ``` -### CacheStats - -```python -@dataclass -class CacheStats: - hits: int - misses: int - size: int - max_size: int - hit_rate: float -``` +All fields except `name` and `source` on `Skill` are optional — they depend on what the server returns and whether you requested `include_content`. ## Prerequisites -The Python client requires a running SkillKit API server: +The Python client talks to the SkillKit REST API. You need a running server: ```bash -# In one terminal skillkit serve - -# In another terminal / script -python my_script.py ``` + +Then run your Python script in another terminal. The client handles connection management, retries, and cleanup automatically when used with `async with`. diff --git a/docs/fumadocs/content/docs/quickstart.mdx b/docs/fumadocs/content/docs/quickstart.mdx index dc545ee6..b9a9148a 100644 --- a/docs/fumadocs/content/docs/quickstart.mdx +++ b/docs/fumadocs/content/docs/quickstart.mdx @@ -1,58 +1,27 @@ --- title: Quick Start -description: Get up and running with SkillKit in 5 minutes +description: Get productive with SkillKit in under 5 minutes --- # Quick Start -This guide walks you through installing SkillKit, setting up your first project, and installing skills. +Go from zero to skills-enabled in four steps. -## 1. Run SkillKit - -No installation required! Use npx: - -```bash -npx skillkit@latest -``` - -Or install globally for frequent use: +## 1. Init ```bash -npm install -g skillkit -skillkit --version +npx skillkit@latest init ``` -## 2. Initialize Your Project +SkillKit detects your AI agent, creates the skills directory, and saves your preferences. -Navigate to your project directory and run: - -```bash -skillkit init -``` - -This starts an interactive onboarding that: - -1. **Detects your AI agent** - Scans for `.claude/`, `.cursor/`, `.github/` directories -2. **Creates directories** - Sets up the skills folder for your agent -3. **Saves preferences** - Remembers your choices for future commands - -### Quick Agent Selection - -Three options appear for faster interaction: - -- **"Same as last time"** - Reuse previous agent choices -- **"All detected agents"** - Select every agent found -- **"Select specific agents"** - Open full selection menu - -## 3. Get Recommendations - -SkillKit analyzes your project and suggests relevant skills: +## 2. Get recommendations ```bash skillkit recommend ``` -Example output: +SkillKit reads your project (package.json, languages, frameworks) and suggests relevant skills: ``` Project: my-app (Next.js + TypeScript + Tailwind) @@ -61,235 +30,93 @@ Recommended Skills: 92% vercel-react-best-practices 87% tailwind-v4-patterns 85% nextjs-app-router - 78% typescript-strict-mode ``` -## 4. Install Skills - -### Interactive Installation +## 3. Install ```bash skillkit install anthropics/skills ``` -This prompts you to: -- Select which skills to install -- Choose target agents -- Pick installation method (symlink or copy) - -### Non-Interactive Installation - -For CI/CD or scripting: +Pick which skills to install, choose target agents, and you're set. For CI/CD or scripting: ```bash skillkit install anthropics/skills --skills=pdf,xlsx --agent claude --yes ``` -### List Available Skills - -Preview without installing: +Install for multiple agents at once: ```bash -skillkit install anthropics/skills --list +skillkit install vercel-labs/agent-skills --agent claude,cursor,windsurf ``` -## 5. Sync to Your Agent - -Deploy installed skills to your agent's configuration: +## 4. Sync ```bash skillkit sync ``` -## 6. Launch the TUI +Skills are now in your agent's configuration. Start coding. -For a visual interface: +## What else? -```bash -skillkit ui -# or just -skillkit -``` +### Translate between agents -**Navigation:** `h` Home | `m` Marketplace | `r` Recommend | `i` Installed | `s` Sync | `q` Quit - -## Complete Example +Already have Claude skills? Deploy them to Cursor: ```bash -# Install SkillKit -npm install -g skillkit - -# Initialize in your project -cd my-project -skillkit init - -# Get recommendations -skillkit recommend - -# Install from official marketplace -skillkit install anthropics/skills - -# Install for multiple agents -skillkit install vercel-labs/agent-skills --agent claude,cursor,windsurf - -# Sync to agents -skillkit sync +skillkit translate my-skill --to cursor ``` -## 7. Advanced Features - -### Auto-Generate Instructions (Primer) +### Auto-generate agent instructions -Let SkillKit analyze your codebase and generate optimized instructions: +Let SkillKit analyze your codebase and create CLAUDE.md, .cursorrules, etc.: ```bash -skillkit primer # Analyze and generate -skillkit primer --all-agents # Generate for all 32 agents +skillkit primer --all-agents ``` -[Learn more about Primer →](/docs/primer) - -### Session Memory - -Capture learnings from your AI sessions: +### Launch the TUI ```bash -skillkit memory compress # Compress learnings -skillkit memory search auth # Search knowledge -skillkit memory export auth-skill # Export as skill -``` - -[Learn more about Memory →](/docs/memory) - -### Mesh Network (Multi-Machine) - -Distribute agents across multiple machines: - -```bash -skillkit mesh init # Initialize mesh node -skillkit mesh discover # Find peers on LAN -skillkit mesh security init # Setup encryption +skillkit ui ``` -[Learn more about Mesh →](/docs/mesh) +`h` Home | `m` Marketplace | `r` Recommend | `i` Installed | `s` Sync | `q` Quit -### Inter-Agent Messaging +### Start the discovery server -Send messages between AI agents: +Let agents find skills at runtime: ```bash -skillkit message send # Send to another agent -skillkit message inbox # Check your inbox -skillkit message reply # Reply to message +skillkit serve ``` -[Learn more about Messaging →](/docs/messaging) +[REST API](/docs/rest-api) | [MCP Server](/docs/mcp-server) -## Team Collaboration - -Share skills with your team using manifest files: +### Share with your team ```bash -# Create manifest skillkit manifest init - -# Add skill sources skillkit manifest add anthropics/skills -skillkit manifest add ./local-skills - -# Team members install from manifest -skillkit manifest install +git add .skills && git commit -m "add team skills" ``` -The `.skills` file can be committed to Git for team-wide consistency. +Team members run `skillkit manifest install` and get the same setup. -## Workflows & Automation - -### Workflow Orchestration - -Compose skills into multi-step workflows: +## Full workflow ```bash -skillkit workflow create feature-development -skillkit workflow run feature-development -``` - -[Learn more about Workflows →](/docs/workflows) - -### Skill Testing - -Test skills before deployment: - -```bash -skillkit test # Run all tests -skillkit test --tags unit # Run specific tests -``` - -[Learn more about Testing →](/docs/testing) - -### CI/CD Integration - -Generate GitHub Actions, GitLab CI configs: - -```bash -skillkit cicd init --provider github -skillkit cicd init --provider gitlab -``` - -[Learn more about CI/CD →](/docs/cicd) - -## User Preferences - -Your choices are saved to `~/.skillkit/preferences.json`: - -```json -{ - "lastSelectedAgents": ["claude", "cursor"], - "autoSync": true, - "marketplace": { - "lastRefresh": "2025-01-01T00:00:00Z" - } -} -``` - -## Complete Workflow Example - -```bash -# 1. Install SkillKit -npm install -g skillkit - -# 2. Initialize in your project -cd my-project -skillkit init - -# 3. Auto-generate base instructions -skillkit primer --all-agents - -# 4. Get smart recommendations -skillkit recommend - -# 5. Install recommended skills -skillkit install anthropics/skills - -# 6. Setup mesh network (optional) -skillkit mesh init - -# 7. Setup session memory (optional) -skillkit memory compress - -# 8. Sync everything to agents -skillkit sync - -# 9. Launch TUI for visual management -skillkit +npx skillkit@latest init # Detect agents, create dirs +skillkit recommend # Get smart suggestions +skillkit install anthropics/skills # Install from marketplace +skillkit primer --all-agents # Generate agent instructions +skillkit sync # Deploy everything ``` -## Next Steps +## Next steps -- **Browse Marketplace** - `skillkit marketplace` -- **Create Custom Skills** - `skillkit create my-skill` -- **Translate Between Agents** - `skillkit translate skill --to cursor` -- **Auto-Generate Instructions** - `skillkit primer` -- **Setup Memory System** - `skillkit memory compress` -- **View All Commands** - `skillkit --help` -- **API Reference** - [Programmatic Access →](/docs/api-reference) \ No newline at end of file +- [Commands](/docs/commands) — Full CLI reference +- [Skills](/docs/skills) — Skill format and lifecycle +- [Memory](/docs/memory) — Persistent session learning +- [Mesh](/docs/mesh) — Multi-machine distribution diff --git a/docs/fumadocs/content/docs/rest-api.mdx b/docs/fumadocs/content/docs/rest-api.mdx index 55691a26..66d9b469 100644 --- a/docs/fumadocs/content/docs/rest-api.mdx +++ b/docs/fumadocs/content/docs/rest-api.mdx @@ -1,42 +1,24 @@ --- -title: REST API Server -description: Runtime skill discovery via HTTP REST API +title: REST API +description: Runtime skill discovery via HTTP --- -# REST API Server +# REST API -SkillKit includes a built-in REST API server for runtime skill discovery. Start it with the `serve` command or programmatically via `@skillkit/api`. +Skills shouldn't require pre-installation. With the SkillKit REST API, any agent, framework, or tool can discover and retrieve skills on demand over HTTP. -## Quick Start +## Start the server ```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 +That's it. The API is now running at `http://localhost:3737`. -**GET** `/search?q=&limit=20&include_content=false` +## Search for skills ```bash -curl "http://localhost:3737/search?q=react+performance&limit=5" +curl "http://localhost:3737/search?q=react+performance" ``` ```json @@ -52,46 +34,50 @@ curl "http://localhost:3737/search?q=react+performance&limit=5" ], "total": 42, "query": "react performance", - "limit": 5 + "limit": 20 } ``` -**POST** `/search` — Search with filters +Results are ranked by a multi-signal scoring system. The best matches come first. + +### With filters + +Use POST for advanced filtering: ```bash curl -X POST http://localhost:3737/search \ -H "Content-Type: application/json" \ -d '{ "query": "auth", - "limit": 10, - "filters": { - "tags": ["security"], - "category": "backend" - } + "filters": { "tags": ["security"], "category": "backend" } }' ``` -### Get Specific Skill +### Include full content + +Add `include_content=true` to get the complete SKILL.md body: + +```bash +curl "http://localhost:3737/search?q=pdf&include_content=true&limit=3" +``` -**GET** `/skills/:owner/:repo/:id` +## Get a specific skill ```bash curl http://localhost:3737/skills/anthropics/skills/pdf-processing ``` -### Trending Skills +The path follows the pattern `/skills/:owner/:repo/:skill-name`. -**GET** `/trending?limit=20` +## Browse trending skills ```bash curl http://localhost:3737/trending?limit=10 ``` -Returns top skills ranked by multi-signal relevance score (content availability, popularity, references). +Returns the top skills ranked by relevance score across all sources. -### Categories - -**GET** `/categories` +## List categories ```bash curl http://localhost:3737/categories @@ -101,96 +87,119 @@ curl http://localhost:3737/categories { "categories": [ { "name": "react", "count": 156 }, - { "name": "typescript", "count": 134 } + { "name": "typescript", "count": 134 }, + { "name": "testing", "count": 89 } ], "total": 89 } ``` -### Health Check +## How ranking works + +Every search result gets a score from 0 to 100, computed from four signals: + +| Signal | Points | What it measures | +|--------|--------|-----------------| +| Content | 40 | Has a description and SKILL.md body | +| Query match | 30 | How well the name/description matches your search | +| Popularity | 15 | GitHub stars + install count (log-scaled) | +| References | 15 | Has example files, docs, or resources | + +A skill with full content, an exact name match, high stars, and example files scores close to 100. A skill with just a name and no content scores around 10. -**GET** `/health` +## Server options ```bash -curl http://localhost:3737/health +skillkit serve --port 8080 --host localhost --cors "http://localhost:3000" ``` -```json -{ - "status": "ok", - "version": "1.12.0", - "skillCount": 15062, - "uptime": 3600 -} -``` +| Option | Default | What it does | +|--------|---------|-------------| +| `--port` / `-p` | `3737` | Port to listen on | +| `--host` / `-H` | `0.0.0.0` | Host to bind to | +| `--cors` | `*` | Allowed CORS origin | +| `--cache-ttl` | `86400000` | Cache lifetime in ms (default 24h) | + +## Rate limiting -### Cache Statistics +60 requests per minute per IP. Response headers tell you where you stand: -**GET** `/cache/stats` +| Header | Meaning | +|--------|---------| +| `X-RateLimit-Remaining` | Requests left in this window | +| `X-RateLimit-Reset` | When the window resets | + +Exceed the limit and you'll get HTTP 429 with a `retryAfter` field. + +## Caching + +Search results are cached in memory using an LRU strategy. Same query, same results, no recomputation. Check cache performance: ```bash curl http://localhost:3737/cache/stats ``` -## Rate Limiting +```json +{ + "hits": 142, + "misses": 38, + "size": 45, + "maxSize": 500, + "hitRate": 0.789 +} +``` -The server includes per-IP rate limiting (60 requests per minute by default). Response headers: +## Health check -| Header | Description | -|--------|-------------| -| `X-RateLimit-Limit` | Max requests per window | -| `X-RateLimit-Remaining` | Remaining requests | -| `X-RateLimit-Reset` | Window reset timestamp | +```bash +curl http://localhost:3737/health +``` -Exceeding the limit returns HTTP 429 with a `retryAfter` field. +```json +{ + "status": "ok", + "version": "1.12.0", + "skillCount": 15062, + "uptime": 3600 +} +``` -## Programmatic Usage +## Use it programmatically ```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: [...], + skills: mySkillsArray, }); +``` + +Or get just the Hono app for testing: -// Or just the Hono app (for testing or custom servers) +```typescript const { app, cache } = createApp({ - skills: [...], + skills: mySkillsArray, cacheTtlMs: 3_600_000, }); ``` -## Relevance Ranking - -Search results are ranked using a multi-signal scoring system (0-100): +## Interactive docs -| 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 | +The server includes built-in Swagger UI at `/docs` and an OpenAPI 3.1 spec at `/openapi.json`. Open `http://localhost:3737/docs` in your browser to try endpoints interactively. -## Interactive API Documentation +The hosted version is available at [agenstskills.com/api](https://agenstskills.com/api). -The server includes built-in interactive API docs powered by Swagger UI: +## All endpoints -- **`GET /docs`** — Interactive Swagger UI with try-it-out support -- **`GET /openapi.json`** — OpenAPI 3.1 specification -- **`GET /`** — API info with endpoint listing - -Open `http://localhost:3737/docs` in your browser after starting the server. - -## 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 -``` +| 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 | +| GET | `/docs` | Swagger UI | +| GET | `/openapi.json` | OpenAPI spec | diff --git a/docs/skillkit/public/api.html b/docs/skillkit/public/api.html index 3315595f..bc9c7e5c 100644 --- a/docs/skillkit/public/api.html +++ b/docs/skillkit/public/api.html @@ -3,8 +3,8 @@ - SkillKit API Documentation - + SkillKit API +