mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-20 12:23:29 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a546b04953 | ||
|
|
6d290171b7 | ||
|
|
a994726952 | ||
|
|
1ee5258447 | ||
|
|
db38c9059d | ||
|
|
988a49f38f | ||
|
|
19694dcaa1 | ||
|
|
b432400b5a | ||
|
|
e5f0d6d450 | ||
|
|
e569046776 | ||
|
|
5bd7ebf607 | ||
|
|
549a21ad84 | ||
|
|
109f00cd95 | ||
|
|
e3d7e0e28f | ||
|
|
6cbbdabf59 | ||
|
|
c1c179217d |
@@ -9,498 +9,217 @@
|
||||
|
||||
[](https://www.npmjs.com/package/skillkit)
|
||||
[](https://www.npmjs.com/package/skillkit)
|
||||
[](https://github.com/rohitg00/skillkit/pkgs/npm/skillkit)
|
||||
[](https://github.com/rohitg00/skillkit/actions/workflows/ci.yml)
|
||||
[](https://agenstskills.com)
|
||||
[](https://agenstskills.com/docs)
|
||||
[](https://agenstskills.com/api)
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
[](https://agenstskills.com)
|
||||
|
||||
## Supercharge Every AI Coding Agent
|
||||
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 for each agent, or locking into one platform.
|
||||
|
||||
**Give your AI agents new abilities with portable, reusable skills.** Install from a curated marketplace, create your own, and use them across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 27 more agents (32 total).
|
||||
|
||||
> **What are AI Agent Skills?** Skills are instruction files that teach AI coding agents how to handle specific tasks - like processing PDFs, following React best practices, or enforcing security patterns. Think of them as plugins for your AI assistant.
|
||||
SkillKit fixes this. Write a skill once, deploy it to all 32 agents.
|
||||
|
||||
```bash
|
||||
# Quick start (no install required)
|
||||
npx skillkit@latest
|
||||
|
||||
# Or install globally
|
||||
npm install -g skillkit
|
||||
```
|
||||
|
||||
## Why SkillKit?
|
||||
|
||||
**The problem:** You've built amazing skills for Claude Code. Now you want to try Cursor. Or your team uses different agents. Each agent has different formats and directories. Without SkillKit, you either rewrite everything, lock yourself into one agent, or give up on skills entirely.
|
||||
|
||||
**The solution:** SkillKit translates skills between all 32 agents automatically. Write once, use everywhere.
|
||||
|
||||
## See It In Action
|
||||
|
||||
<video src="https://raw.githubusercontent.com/rohitg00/skillkit/main/docs/video/skillkit.mp4" controls width="100%"></video>
|
||||
|
||||
> **Note:** If the video doesn't play above, [watch it here](https://raw.githubusercontent.com/rohitg00/skillkit/main/docs/video/skillkit.mp4)
|
||||
> If the video doesn't play above, [watch it here](https://raw.githubusercontent.com/rohitg00/skillkit/main/docs/video/skillkit.mp4)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install a skill for ALL your agents at once
|
||||
skillkit install anthropics/skills --agent claude-code,cursor,windsurf
|
||||
|
||||
# Or translate existing skills between any agents
|
||||
skillkit translate my-skill --from claude --to cursor,codex,copilot
|
||||
|
||||
# Get smart recommendations based on your project
|
||||
skillkit recommend
|
||||
# > 92% match: vercel-react-best-practices
|
||||
# > 87% match: tailwind-v4-patterns
|
||||
# > 85% match: nextjs-app-router
|
||||
npx skillkit@latest init # Detect agents, create dirs
|
||||
skillkit recommend # Get smart suggestions
|
||||
skillkit install anthropics/skills # Install from marketplace
|
||||
skillkit sync # Deploy to your agents
|
||||
```
|
||||
|
||||
## Beautiful CLI Experience
|
||||
Four commands. Your agents now have skills for PDF processing, code review, and more.
|
||||
|
||||
SkillKit features a polished, interactive CLI with visual feedback:
|
||||
## What Can You Do?
|
||||
|
||||

|
||||
|
||||
- **Adaptive Logo** - Full ASCII art on wide terminals, compact on narrow
|
||||
- **Agent Icons** - Visual indicators: ⟁ Claude · ◫ Cursor · ◎ Codex · ✦ Gemini · ⬡ OpenCode
|
||||
- **Interactive Selection** - Multi-select skills and agents with visual feedback
|
||||
- **Progress Indicators** - Step trails, spinners, and progress bars
|
||||
- **Smart Defaults** - Remembers your last selected agents
|
||||
|
||||
## What Makes SkillKit Different
|
||||
|
||||
| Feature | Without SkillKit | With SkillKit |
|
||||
|---------|-----------------|---------------|
|
||||
| **Multi-Agent Support** | Manual rewrite for each agent | One command, all agents |
|
||||
| **Team Collaboration** | Email skills back and forth | Git-based bundles, remote sync |
|
||||
| **Skill Discovery** | Search GitHub manually | Smart recommendations for your stack |
|
||||
| **Format Translation** | Learn each agent's format | Automatic conversion (32 formats) |
|
||||
| **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 |
|
||||
|
||||
## 5-Minute Quick Start
|
||||
### Install skills from anywhere
|
||||
|
||||
```bash
|
||||
# Launch interactive TUI (no install required)
|
||||
npx skillkit@latest
|
||||
|
||||
# Or with specific commands:
|
||||
npx skillkit recommend # Get smart recommendations
|
||||
npx skillkit install anthropics/skills # Install official skills
|
||||
npx skillkit sync # Sync to your AI agent
|
||||
|
||||
# For frequent use, install globally:
|
||||
npm install -g skillkit
|
||||
skillkit # Launch TUI
|
||||
skillkit install anthropics/skills # GitHub
|
||||
skillkit install gitlab:team/skills # GitLab
|
||||
skillkit install ./my-local-skills # Local path
|
||||
```
|
||||
|
||||
## Core Features
|
||||
### Translate between agents
|
||||
|
||||
### Cross-Agent Translation
|
||||
|
||||
Use any skill with any agent. SkillKit automatically converts between formats:
|
||||
Write for Claude, deploy to Cursor:
|
||||
|
||||
```bash
|
||||
# Translate a Claude skill to Cursor format
|
||||
skillkit translate react-patterns --to cursor
|
||||
|
||||
# Translate all your skills to a new agent
|
||||
skillkit translate my-skill --to cursor
|
||||
skillkit translate --all --to windsurf
|
||||
|
||||
# Preview translation without writing
|
||||
skillkit translate my-skill --to codex --dry-run
|
||||
|
||||
# Batch translate from a custom source directory
|
||||
skillkit agent translate --source ./my-skills --to cursor
|
||||
|
||||
# Recursively translate nested agent directories
|
||||
skillkit agent translate --source ./kubernetes-skills --to cursor --recursive
|
||||
```
|
||||
|
||||
**Supported Agents (32):** Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Amp, Clawdbot, Droid, GitHub Copilot, Goose, Kilo, Kiro, Roo, Trae, Windsurf, Universal, Cline, CodeBuddy, CommandCode, Continue, Crush, Factory, MCPJam, Mux, Neovate, OpenHands, Pi, Qoder, Qwen, Vercel, Zencoder
|
||||
### Get smart recommendations
|
||||
|
||||
### Smart Recommendations
|
||||
|
||||
SkillKit analyzes your project and suggests the perfect skills:
|
||||
SkillKit reads your project, detects your stack, and suggests relevant skills:
|
||||
|
||||
```bash
|
||||
skillkit recommend
|
||||
|
||||
# Project: my-app (Next.js + TypeScript + Tailwind)
|
||||
#
|
||||
# Recommended Skills:
|
||||
# 92% vercel-react-best-practices
|
||||
# 87% tailwind-v4-patterns
|
||||
# 85% nextjs-app-router
|
||||
# 78% typescript-strict-mode
|
||||
# 92% vercel-react-best-practices
|
||||
# 87% tailwind-v4-patterns
|
||||
# 85% nextjs-app-router
|
||||
```
|
||||
|
||||
Filter by task, category, or minimum score:
|
||||
### Discover skills at runtime
|
||||
|
||||
Start an API server and let agents find skills on demand:
|
||||
|
||||
```bash
|
||||
skillkit recommend --search "auth" # Task-based search
|
||||
skillkit recommend --category security # Category filter
|
||||
skillkit recommend --min-score 80 # Quality threshold
|
||||
skillkit recommend --explain # Show WHY skills match
|
||||
skillkit recommend --reasoning # Use LLM-based search
|
||||
skillkit serve
|
||||
# Server running at http://localhost:3737
|
||||
|
||||
curl "http://localhost:3737/search?q=react+performance"
|
||||
```
|
||||
|
||||
### Hierarchical Skill Tree
|
||||
Or use MCP for native agent integration:
|
||||
|
||||
Browse skills organized in a navigable taxonomy:
|
||||
|
||||
```bash
|
||||
skillkit tree # Show full tree
|
||||
skillkit tree Frontend # Show Frontend subtree
|
||||
skillkit tree "Frontend > React" # Navigate to subcategory
|
||||
skillkit tree --generate # Generate tree from index
|
||||
skillkit tree --stats # Show tree statistics
|
||||
skillkit tree --depth 2 # Limit display depth
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skillkit": { "command": "npx", "args": ["@skillkit/mcp"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Categories:** Development, Frontend, Backend, Mobile, DevOps, Testing, Security, AI/ML, Database, Tooling, Documentation, Performance
|
||||
Or use Python:
|
||||
|
||||
### Session Memory System
|
||||
```bash
|
||||
pip install skillkit-client
|
||||
```
|
||||
|
||||
Your AI agents learn, but that knowledge dies with the session. SkillKit captures learnings and makes them persistent:
|
||||
```python
|
||||
from skillkit import SkillKitClient
|
||||
|
||||
async with SkillKitClient() as client:
|
||||
results = await client.search("react performance", limit=5)
|
||||
```
|
||||
|
||||
[REST API docs](https://agenstskills.com/docs/rest-api) · [MCP Server docs](https://agenstskills.com/docs/mcp-server) · [Python Client docs](https://agenstskills.com/docs/python-client) · [Interactive API explorer](https://agenstskills.com/api)
|
||||
|
||||
### Auto-generate agent instructions
|
||||
|
||||
Let SkillKit analyze your codebase and create CLAUDE.md, .cursorrules, etc.:
|
||||
|
||||
```bash
|
||||
skillkit primer --all-agents
|
||||
```
|
||||
|
||||
### Session memory
|
||||
|
||||
Your AI agents learn patterns during sessions, then forget everything. SkillKit captures those learnings:
|
||||
|
||||
```bash
|
||||
# Compress session observations into reusable learnings
|
||||
skillkit memory compress
|
||||
|
||||
# Search past learnings
|
||||
skillkit memory search "authentication patterns"
|
||||
|
||||
# Export a learning as a shareable skill
|
||||
skillkit memory export auth-insight --output auth-patterns.md
|
||||
|
||||
# Share memory across projects
|
||||
skillkit memory --global
|
||||
skillkit memory search "auth patterns"
|
||||
skillkit memory export auth-patterns
|
||||
```
|
||||
|
||||
### Skill Marketplace
|
||||
### Mesh network
|
||||
|
||||
Browse and install from curated skill repositories:
|
||||
Distribute agents across machines with encrypted P2P:
|
||||
|
||||
```bash
|
||||
# Browse all available skills
|
||||
skillkit marketplace
|
||||
|
||||
# Search for specific skills
|
||||
skillkit marketplace search "react hooks"
|
||||
|
||||
# Filter by tags
|
||||
skillkit marketplace --tags typescript,testing
|
||||
|
||||
# Refresh the skill index
|
||||
skillkit marketplace refresh
|
||||
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.
|
||||
|
||||
### Interactive TUI
|
||||
|
||||
Beautiful terminal interface for visual skill management:
|
||||
|
||||
```bash
|
||||
skillkit ui
|
||||
# or just
|
||||
skillkit
|
||||
```
|
||||
|
||||
**Navigation:** `h` Home | `m` Marketplace | `b` Browse | `v` Tree View | `r` Recommend | `t` Translate | `c` Context | `l` List | `s` Sync | `q` Quit
|
||||
`h` Home · `m` Marketplace · `r` Recommend · `t` Translate · `i` Installed · `s` Sync · `q` Quit
|
||||
|
||||
### Skill Testing Framework
|
||||
|
||||
Test your skills with built-in assertions:
|
||||
|
||||
```bash
|
||||
# Run all skill tests
|
||||
skillkit test
|
||||
|
||||
# Test specific skills
|
||||
skillkit test ./my-skill
|
||||
|
||||
# Run tests with specific tags
|
||||
skillkit test --tags unit,integration
|
||||
|
||||
# JSON output for CI
|
||||
skillkit test --json
|
||||
```
|
||||
|
||||
### Workflow Orchestration
|
||||
|
||||
Compose skills into multi-step workflows:
|
||||
|
||||
```bash
|
||||
# List available workflows
|
||||
skillkit workflow list
|
||||
|
||||
# Run a workflow
|
||||
skillkit workflow run feature-development
|
||||
|
||||
# Create new workflow
|
||||
skillkit workflow create my-workflow
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Generate CI/CD templates for automated skill management:
|
||||
|
||||
```bash
|
||||
# GitHub Actions
|
||||
skillkit cicd github-action
|
||||
|
||||
# GitLab CI
|
||||
skillkit cicd gitlab-ci
|
||||
|
||||
# Pre-commit hooks
|
||||
skillkit cicd pre-commit
|
||||
```
|
||||

|
||||
|
||||
## Supported Agents (32)
|
||||
|
||||
| Agent | Format | Skills Directory |
|
||||
|-------|--------|------------------|
|
||||
| Claude Code | SKILL.md | `.claude/skills/` |
|
||||
| Cursor | MDC (.mdc) | `.cursor/skills/` |
|
||||
| Codex | SKILL.md | `.codex/skills/` |
|
||||
| Gemini CLI | SKILL.md | `.gemini/skills/` |
|
||||
| OpenCode | SKILL.md | `.opencode/skills/` |
|
||||
| Antigravity | SKILL.md | `.antigravity/skills/` |
|
||||
| Amp | SKILL.md | `.amp/skills/` |
|
||||
| Clawdbot | SKILL.md | `skills/` or `~/.clawdbot/skills/` |
|
||||
| Droid (Factory) | SKILL.md | `.factory/skills/` |
|
||||
| GitHub Copilot | Markdown | `.github/skills/` |
|
||||
| Goose | SKILL.md | `.goose/skills/` |
|
||||
| Kilo Code | SKILL.md | `.kilocode/skills/` |
|
||||
| Kiro CLI | SKILL.md | `.kiro/skills/` |
|
||||
| Roo Code | SKILL.md | `.roo/skills/` |
|
||||
| Trae | SKILL.md | `.trae/skills/` |
|
||||
| Windsurf | Markdown | `.windsurf/skills/` |
|
||||
| Universal | SKILL.md | `skills/` |
|
||||
| Cline | SKILL.md | `.cline/skills/` |
|
||||
| CodeBuddy | SKILL.md | `.codebuddy/skills/` |
|
||||
| CommandCode | SKILL.md | `.commandcode/skills/` |
|
||||
| Continue | SKILL.md | `.continue/skills/` |
|
||||
| Crush | SKILL.md | `.crush/skills/` |
|
||||
| Factory | SKILL.md | `.factory/skills/` |
|
||||
| MCPJam | SKILL.md | `.mcpjam/skills/` |
|
||||
| Mux | SKILL.md | `.mux/skills/` |
|
||||
| Neovate | SKILL.md | `.neovate/skills/` |
|
||||
| OpenHands | SKILL.md | `.openhands/skills/` |
|
||||
| Pi | SKILL.md | `.pi/skills/` |
|
||||
| Qoder | SKILL.md | `.qoder/skills/` |
|
||||
| Qwen | SKILL.md | `.qwen/skills/` |
|
||||
| Vercel | SKILL.md | `.vercel/skills/` |
|
||||
| Zencoder | SKILL.md | `.zencoder/skills/` |
|
||||
| Agent | Format | Directory |
|
||||
|-------|--------|-----------|
|
||||
| **Claude Code** | SKILL.md | `.claude/skills/` |
|
||||
| **Cursor** | .mdc | `.cursor/skills/` |
|
||||
| **Codex** | SKILL.md | `.codex/skills/` |
|
||||
| **Gemini CLI** | SKILL.md | `.gemini/skills/` |
|
||||
| **OpenCode** | SKILL.md | `.opencode/skills/` |
|
||||
| **GitHub Copilot** | Markdown | `.github/skills/` |
|
||||
| **Windsurf** | Markdown | `.windsurf/skills/` |
|
||||
|
||||
## All Commands
|
||||
Plus 25 more: 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
|
||||
|
||||
### Skill Management
|
||||
[Full agent details](https://agenstskills.com/docs/agents)
|
||||
|
||||
## Commands
|
||||
|
||||
### Core
|
||||
|
||||
```bash
|
||||
skillkit install <source> # Install skills from GitHub/GitLab/Bitbucket/local
|
||||
skillkit remove <skills> # Remove installed skills
|
||||
skillkit update [skills] # Update skills from source
|
||||
skillkit list # List installed skills
|
||||
skillkit enable <skills> # Enable specific skills
|
||||
skillkit pause <skills> # Temporarily pause skills
|
||||
skillkit resume <skills> # Resume paused skills
|
||||
skillkit sync # Sync skills to agent config
|
||||
skillkit read <skills> # Read skill content for AI
|
||||
skillkit status # Show skill and agent status
|
||||
skillkit install <source> # Install skills
|
||||
skillkit remove <skills> # Remove skills
|
||||
skillkit translate <skill> --to # Translate between agents
|
||||
skillkit sync # Deploy to agent config
|
||||
skillkit recommend # Smart recommendations
|
||||
skillkit serve # Start REST API server
|
||||
```
|
||||
|
||||
### Discovery & Recommendations
|
||||
### Discovery
|
||||
|
||||
```bash
|
||||
skillkit recommend # Get smart recommendations
|
||||
skillkit recommend --explain # Show reasoning for matches
|
||||
skillkit recommend --reasoning # Use LLM-based discovery
|
||||
skillkit tree # Browse hierarchical taxonomy
|
||||
skillkit tree --generate # Generate tree from index
|
||||
skillkit marketplace # Browse skill marketplace
|
||||
skillkit marketplace search # Search marketplace
|
||||
skillkit find <query> # Quick skill search
|
||||
skillkit check # Check skill health and updates
|
||||
skillkit marketplace # Browse skills
|
||||
skillkit tree # Hierarchical taxonomy
|
||||
skillkit find <query> # Quick search
|
||||
```
|
||||
|
||||
### Translation & Context
|
||||
### Advanced
|
||||
|
||||
```bash
|
||||
skillkit translate # Translate between formats
|
||||
skillkit context init # Initialize project context
|
||||
skillkit context sync # Sync context to agents
|
||||
skillkit primer --all-agents # Generate agent instructions
|
||||
skillkit memory compress # Capture session learnings
|
||||
skillkit mesh init # Multi-machine distribution
|
||||
skillkit message send # Inter-agent messaging
|
||||
skillkit workflow run <name> # Run workflows
|
||||
skillkit test # Test skills
|
||||
skillkit cicd init # CI/CD templates
|
||||
```
|
||||
|
||||
### AI Instruction Generation (Primer)
|
||||
|
||||
Generate AI instruction files for all 32 supported agents based on your codebase analysis:
|
||||
|
||||
```bash
|
||||
skillkit primer # Analyze codebase, generate for detected agents
|
||||
skillkit primer --all-agents # Generate for all 32 agents
|
||||
skillkit primer --agent claude-code,cursor # Specific agents only
|
||||
skillkit primer --dry-run # Preview without writing files
|
||||
skillkit primer --analyze-only # Only show codebase analysis
|
||||
skillkit primer --output ./instructions # Write to custom directory
|
||||
skillkit primer --json # Output analysis as JSON (for scripting)
|
||||
skillkit primer --json --analyze-only # Machine-readable analysis
|
||||
```
|
||||
|
||||
Inspired by [primer](https://github.com/pierceboggan/primer) but extended for all SkillKit agents.
|
||||
|
||||
### Custom AI Sub-Agents
|
||||
|
||||
```bash
|
||||
skillkit agent list # List all installed agents
|
||||
skillkit agent show <name> # Show agent details
|
||||
skillkit agent create <name> # Create a new agent
|
||||
skillkit agent translate # Translate agents between formats
|
||||
--source ./path # Source directory or file
|
||||
--to cursor # Target agent format
|
||||
--recursive # Scan subdirectories recursively
|
||||
--dry-run # Preview without writing
|
||||
skillkit agent sync # Sync agents to target AI agent
|
||||
skillkit agent validate # Validate agent definitions
|
||||
```
|
||||
|
||||
### Memory System
|
||||
|
||||
```bash
|
||||
skillkit memory status # View memory status
|
||||
skillkit memory search # Search learnings
|
||||
skillkit memory compress # Compress observations
|
||||
skillkit memory export # Export as skill
|
||||
```
|
||||
|
||||
### Mesh Network
|
||||
|
||||
```bash
|
||||
skillkit mesh init # Initialize mesh network
|
||||
skillkit mesh add <address> # Add a host to mesh
|
||||
skillkit mesh remove <id> # Remove a host from mesh
|
||||
skillkit mesh list # List known hosts
|
||||
skillkit mesh discover # Discover hosts on LAN
|
||||
skillkit mesh health # Check host health
|
||||
skillkit mesh status # Show mesh status
|
||||
|
||||
# Security
|
||||
skillkit mesh security init # Setup encryption keys
|
||||
skillkit mesh security status # Show security status
|
||||
skillkit mesh peer trust <id> # Trust a peer
|
||||
skillkit mesh peer revoke <id># Revoke peer trust
|
||||
skillkit mesh peer list # List trusted peers
|
||||
```
|
||||
|
||||
### Inter-Agent Messaging
|
||||
|
||||
```bash
|
||||
skillkit message send # Send message to agent
|
||||
skillkit message inbox # View inbox
|
||||
skillkit message read <id> # Read a message
|
||||
skillkit message reply <id> # Reply to message
|
||||
skillkit message archive <id> # Archive message
|
||||
skillkit message sent # View sent messages
|
||||
skillkit message status # Messaging status
|
||||
```
|
||||
|
||||
### Quality & Testing
|
||||
|
||||
```bash
|
||||
skillkit test # Run skill tests
|
||||
skillkit validate # Validate skill format
|
||||
skillkit fix # Auto-fix skill issues
|
||||
skillkit audit # Audit skills for security/quality
|
||||
skillkit manifest # Generate skill manifest
|
||||
```
|
||||
|
||||
### Team Collaboration
|
||||
|
||||
```bash
|
||||
skillkit team init # Initialize team workspace
|
||||
skillkit team share # Share skills with team
|
||||
skillkit team import # Import team skills
|
||||
skillkit team sync # Sync team skills
|
||||
skillkit team list # List team members
|
||||
```
|
||||
|
||||
### Workflows & Automation
|
||||
|
||||
```bash
|
||||
skillkit workflow run # Execute workflow
|
||||
skillkit plan create # Create execution plan
|
||||
skillkit plan execute # Execute a plan
|
||||
skillkit cicd init # Generate CI/CD templates
|
||||
skillkit hook register # Register lifecycle hooks
|
||||
skillkit command generate # Generate slash commands
|
||||
```
|
||||
|
||||
### Plugins & Extensions
|
||||
|
||||
```bash
|
||||
skillkit plugin list # List available plugins
|
||||
skillkit plugin install # Install a plugin
|
||||
skillkit plugin enable # Enable a plugin
|
||||
skillkit methodology list # List methodologies
|
||||
skillkit methodology load # Load a methodology
|
||||
```
|
||||
|
||||
### Publishing & Sharing
|
||||
|
||||
```bash
|
||||
skillkit publish # Generate well-known hosting structure
|
||||
skillkit publish submit # Submit to SkillKit marketplace
|
||||
skillkit create # Create new skill
|
||||
skillkit init # Initialize in project
|
||||
```
|
||||
|
||||
#### Self-Hosting Skills (RFC 8615)
|
||||
|
||||
Generate a well-known URI structure to host skills on your own domain:
|
||||
|
||||
```bash
|
||||
# Generate hosting structure
|
||||
skillkit publish ./my-skills --output ./public
|
||||
|
||||
# Users install from your domain
|
||||
skillkit add https://your-domain.com
|
||||
```
|
||||
|
||||
This creates:
|
||||
```
|
||||
.well-known/skills/
|
||||
index.json # Skill manifest
|
||||
my-skill/SKILL.md # Skill files
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash
|
||||
skillkit settings # View/edit settings
|
||||
skillkit settings --set key=value # Update setting
|
||||
```
|
||||
[Full command reference](https://agenstskills.com/docs/commands)
|
||||
|
||||
## Creating Skills
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
skillkit create my-skill
|
||||
```
|
||||
|
||||
### Manual Creation
|
||||
|
||||
Create a `SKILL.md` file following the [Agent Skills specification](https://agenstskills.com):
|
||||
Or manually create a `SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does and when to use it
|
||||
description: What this skill does
|
||||
license: MIT
|
||||
metadata:
|
||||
author: your-name
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# My Skill
|
||||
@@ -519,169 +238,62 @@ Instructions for the AI agent.
|
||||
## Programmatic API
|
||||
|
||||
```typescript
|
||||
import {
|
||||
// Skill discovery
|
||||
findAllSkills,
|
||||
discoverSkills,
|
||||
detectAgent,
|
||||
getAdapter,
|
||||
import { translateSkill, analyzeProject, RecommendationEngine } from 'skillkit';
|
||||
|
||||
// Translation
|
||||
translateSkill,
|
||||
translateSkillFile,
|
||||
const skill = await translateSkill(content, 'cursor');
|
||||
|
||||
// Recommendations
|
||||
RecommendationEngine,
|
||||
ReasoningRecommendationEngine,
|
||||
analyzeProject,
|
||||
|
||||
// Tree & Taxonomy
|
||||
TreeGenerator,
|
||||
generateSkillTree,
|
||||
loadTree,
|
||||
buildSkillGraph,
|
||||
getRelatedSkills,
|
||||
|
||||
// Reasoning Engine
|
||||
ReasoningEngine,
|
||||
createReasoningEngine,
|
||||
|
||||
// Connectors (Tool-Agnostic Placeholders)
|
||||
detectPlaceholders,
|
||||
replacePlaceholders,
|
||||
suggestMappingsFromMcp,
|
||||
|
||||
// Execution Flow
|
||||
ExecutionManager,
|
||||
detectExecutionMode,
|
||||
|
||||
// Context
|
||||
ContextManager,
|
||||
syncToAllAgents,
|
||||
|
||||
// Memory
|
||||
createMemoryCompressor,
|
||||
createMemoryInjector,
|
||||
LearningStore,
|
||||
|
||||
// Marketplace
|
||||
createMarketplaceAggregator,
|
||||
|
||||
// Testing
|
||||
SkillTestRunner,
|
||||
|
||||
// Workflows
|
||||
WorkflowOrchestrator,
|
||||
} from 'skillkit';
|
||||
|
||||
// Example: Translate and install
|
||||
const skill = await translateSkill(skillContent, 'cursor');
|
||||
console.log(skill.content);
|
||||
|
||||
// Example: Get recommendations with reasoning
|
||||
const engine = new ReasoningRecommendationEngine();
|
||||
await engine.initReasoning();
|
||||
const profile = await analyzeProject('./my-project');
|
||||
const recs = await engine.recommendWithReasoning(profile, { reasoning: true });
|
||||
|
||||
// Example: Browse skill tree
|
||||
const tree = generateSkillTree(skills);
|
||||
console.log(tree.rootNode.children); // Categories
|
||||
|
||||
// Example: Detect execution mode
|
||||
const mode = detectExecutionMode();
|
||||
console.log(mode.mode); // 'standalone' or 'enhanced'
|
||||
console.log(mode.capabilities); // Available MCP capabilities
|
||||
const engine = new RecommendationEngine();
|
||||
const recs = await engine.recommend(profile);
|
||||
```
|
||||
|
||||
## Skill Sources & Attribution
|
||||
```typescript
|
||||
import { startServer } from '@skillkit/api';
|
||||
await startServer({ port: 3737, skills: [...] });
|
||||
```
|
||||
|
||||
SkillKit aggregates skills from trusted sources. We credit and link back to all original creators. Each source retains its original license.
|
||||
```typescript
|
||||
import { MemoryCache, RelevanceRanker } from '@skillkit/core';
|
||||
const cache = new MemoryCache({ maxSize: 500, ttlMs: 86_400_000 });
|
||||
const ranker = new RelevanceRanker();
|
||||
const results = ranker.rank(skills, 'react performance');
|
||||
```
|
||||
|
||||
### Official Partner Sources
|
||||
## Skill Sources
|
||||
|
||||
| Repository | Description | License |
|
||||
|------------|-------------|---------|
|
||||
| [anthropics/skills](https://github.com/anthropics/skills) | Official Claude Code skills from Anthropic | Apache 2.0 |
|
||||
| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | Next.js, React, and Vercel platform skills | MIT |
|
||||
| [expo/skills](https://github.com/expo/skills) | Mobile development with Expo and React Native | MIT |
|
||||
| [remotion-dev/skills](https://github.com/remotion-dev/skills) | Programmatic video creation with React | MIT |
|
||||
| [supabase/agent-skills](https://github.com/supabase/agent-skills) | Database, auth, and backend skills | Apache 2.0 |
|
||||
| [stripe/ai](https://github.com/stripe/ai) | Payment integration and Stripe API patterns | MIT |
|
||||
SkillKit aggregates skills from trusted sources. All original creators are credited with their licenses preserved.
|
||||
|
||||
### Community Contributors
|
||||
### Official Partners
|
||||
|
||||
| Repository | Description | License |
|
||||
|------------|-------------|---------|
|
||||
| [trailofbits/skills](https://github.com/trailofbits/skills) | Security analysis and vulnerability detection | Apache 2.0 |
|
||||
| [obra/superpowers](https://github.com/obra/superpowers) | Test-driven development and workflow automation | MIT |
|
||||
| [wshobson/agents](https://github.com/wshobson/agents) | Development patterns and agent configurations (48 agents) | MIT |
|
||||
| [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) | Curated collection of Claude Code skills | MIT |
|
||||
| [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Community-curated skill collection | MIT |
|
||||
| [langgenius/dify](https://github.com/langgenius/dify) | AI application development platform patterns | Apache 2.0 |
|
||||
| [better-auth/skills](https://github.com/better-auth/skills) | Authentication and authorization patterns | MIT |
|
||||
| [onmax/nuxt-skills](https://github.com/onmax/nuxt-skills) | Vue.js and Nuxt framework skills | MIT |
|
||||
| [elysiajs/skills](https://github.com/elysiajs/skills) | Bun runtime and ElysiaJS framework | MIT |
|
||||
| [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) | NestJS backend framework patterns | MIT |
|
||||
| [cloudai-x/threejs-skills](https://github.com/cloudai-x/threejs-skills) | 3D graphics and WebGL development | MIT |
|
||||
| [dimillian/skills](https://github.com/dimillian/skills) | iOS and SwiftUI development patterns | MIT |
|
||||
| [waynesutton/convexskills](https://github.com/waynesutton/convexskills) | Convex backend development | MIT |
|
||||
| [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) | Obsidian plugin and vault management | MIT |
|
||||
| [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) | UI component libraries (Shadcn/Radix) | MIT |
|
||||
| [openrouterteam/agent-skills](https://github.com/openrouterteam/agent-skills) | OpenRouter API integration patterns | MIT |
|
||||
| Repository | Description |
|
||||
|------------|-------------|
|
||||
| [anthropics/skills](https://github.com/anthropics/skills) | Official Claude Code skills |
|
||||
| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | Next.js and React skills |
|
||||
| [expo/skills](https://github.com/expo/skills) | Mobile development with Expo |
|
||||
| [remotion-dev/skills](https://github.com/remotion-dev/skills) | Programmatic video creation |
|
||||
| [supabase/agent-skills](https://github.com/supabase/agent-skills) | Database and auth skills |
|
||||
| [stripe/ai](https://github.com/stripe/ai) | Payment integration patterns |
|
||||
|
||||
**Want to add your skills?** [Submit your repository](https://github.com/rohitg00/skillkit/issues/new?template=add-source.md) to be included in SkillKit
|
||||
### Community
|
||||
|
||||
## Installation Options
|
||||
[trailofbits/skills](https://github.com/trailofbits/skills) · [obra/superpowers](https://github.com/obra/superpowers) · [wshobson/agents](https://github.com/wshobson/agents) · [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) · [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) · [langgenius/dify](https://github.com/langgenius/dify) · [better-auth/skills](https://github.com/better-auth/skills) · [onmax/nuxt-skills](https://github.com/onmax/nuxt-skills) · [elysiajs/skills](https://github.com/elysiajs/skills) · [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) · [cloudai-x/threejs-skills](https://github.com/cloudai-x/threejs-skills) · [dimillian/skills](https://github.com/dimillian/skills) · [waynesutton/convexskills](https://github.com/waynesutton/convexskills) · [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) · [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) · [openrouterteam/agent-skills](https://github.com/openrouterteam/agent-skills)
|
||||
|
||||
**Want to add your skills?** [Submit your repository](https://github.com/rohitg00/skillkit/issues/new?template=add-source.md)
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# npm (recommended)
|
||||
npm install -g skillkit
|
||||
|
||||
# pnpm
|
||||
pnpm add -g skillkit
|
||||
|
||||
# yarn
|
||||
yarn global add skillkit
|
||||
|
||||
# bun
|
||||
bun add -g skillkit
|
||||
|
||||
# npx (no install)
|
||||
npx skillkit <command>
|
||||
|
||||
# GitHub Packages (alternative registry)
|
||||
npm install -g @rohitg00/skillkit --registry=https://npm.pkg.github.com
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `skillkit.yaml` in your project:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
agent: cursor # Override auto-detection
|
||||
autoSync: true # Auto-sync on changes
|
||||
enabledSkills:
|
||||
- pdf
|
||||
- xlsx
|
||||
disabledSkills:
|
||||
- deprecated-skill
|
||||
npm install -g skillkit # npm
|
||||
pnpm add -g skillkit # pnpm
|
||||
yarn global add skillkit # yarn
|
||||
bun add -g skillkit # bun
|
||||
npx skillkit <command> # no install
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Apache License 2.0 - see [LICENSE](LICENSE) for details.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md).
|
||||
Apache License 2.0 — see [LICENSE](LICENSE).
|
||||
|
||||
## Links
|
||||
|
||||
- [Documentation](https://agenstskills.com/docs)
|
||||
- [Website](https://agenstskills.com)
|
||||
- [Agent Skills Specification](https://agenstskills.com)
|
||||
- [GitHub Repository](https://github.com/rohitg00/skillkit)
|
||||
- [NPM Package](https://www.npmjs.com/package/skillkit)
|
||||
- [GitHub Package](https://github.com/rohitg00/skillkit/pkgs/npm/skillkit)
|
||||
[Documentation](https://agenstskills.com/docs) · [Website](https://agenstskills.com) · [API Explorer](https://agenstskills.com/api) · [npm](https://www.npmjs.com/package/skillkit) · [GitHub](https://github.com/rohitg00/skillkit)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit",
|
||||
"version": "1.9.0",
|
||||
"version": "1.13.0",
|
||||
"description": "Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 13 more",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
@@ -53,6 +53,7 @@
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"@skillkit/api": "workspace:*",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@skillkit/cli": "workspace:*",
|
||||
|
||||
@@ -98,6 +98,11 @@ import {
|
||||
GuidelineCreateCommand,
|
||||
GuidelineRemoveCommand,
|
||||
TreeCommand,
|
||||
QuickCommand,
|
||||
SkillMdValidateCommand,
|
||||
SkillMdInitCommand,
|
||||
SkillMdCheckCommand,
|
||||
ServeCommand,
|
||||
} from '@skillkit/cli';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
@@ -220,4 +225,11 @@ cli.register(GuidelineRemoveCommand);
|
||||
|
||||
cli.register(TreeCommand);
|
||||
|
||||
cli.register(QuickCommand);
|
||||
cli.register(SkillMdValidateCommand);
|
||||
cli.register(SkillMdInitCommand);
|
||||
cli.register(SkillMdCheckCommand);
|
||||
|
||||
cli.register(ServeCommand);
|
||||
|
||||
cli.runExit(process.argv.slice(2));
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
[build-system]
|
||||
requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "skillkit-client"
|
||||
version = "0.1.0"
|
||||
description = "Python client for the SkillKit REST API"
|
||||
readme = "README.md"
|
||||
license = "Apache-2.0"
|
||||
requires-python = ">=3.9"
|
||||
authors = [
|
||||
{ name = "Rohit Ghumare", email = "ghumare64@gmail.com" },
|
||||
]
|
||||
keywords = ["skillkit", "ai", "agents", "skills", "discovery"]
|
||||
classifiers = [
|
||||
"Development Status :: 3 - Alpha",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: Apache Software License",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.9",
|
||||
"Programming Language :: Python :: 3.10",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
"Topic :: Software Development :: Libraries",
|
||||
]
|
||||
dependencies = [
|
||||
"httpx>=0.27",
|
||||
"pydantic>=2.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
"pytest>=7.0",
|
||||
"pytest-asyncio>=0.23",
|
||||
"respx>=0.21",
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/rohitg00/skillkit"
|
||||
Documentation = "https://agenstskills.com"
|
||||
Repository = "https://github.com/rohitg00/skillkit"
|
||||
@@ -0,0 +1,12 @@
|
||||
from skillkit.client import SkillKitClient
|
||||
from skillkit.models import Skill, SearchResponse, HealthResponse, CacheStats, Category
|
||||
|
||||
__all__ = [
|
||||
"SkillKitClient",
|
||||
"Skill",
|
||||
"SearchResponse",
|
||||
"HealthResponse",
|
||||
"CacheStats",
|
||||
"Category",
|
||||
]
|
||||
__version__ = "0.1.0"
|
||||
@@ -0,0 +1,140 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Optional
|
||||
from urllib.parse import quote
|
||||
|
||||
import httpx
|
||||
|
||||
from skillkit.models import (
|
||||
CacheStats,
|
||||
CategoriesResponse,
|
||||
Category,
|
||||
HealthResponse,
|
||||
SearchResponse,
|
||||
Skill,
|
||||
TrendingResponse,
|
||||
)
|
||||
|
||||
|
||||
class SkillKitClient:
|
||||
def __init__(self, base_url: str = "http://localhost:3737", timeout: float = 30.0):
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.timeout = timeout
|
||||
self._client: Optional[httpx.AsyncClient] = None
|
||||
|
||||
async def __aenter__(self) -> "SkillKitClient":
|
||||
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *args: object) -> None:
|
||||
if self._client:
|
||||
await self._client.aclose()
|
||||
self._client = None
|
||||
|
||||
def _get_client(self) -> httpx.AsyncClient:
|
||||
if self._client is None:
|
||||
self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout)
|
||||
return self._client
|
||||
|
||||
async def health(self) -> HealthResponse:
|
||||
client = self._get_client()
|
||||
response = await client.get("/health")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return HealthResponse(
|
||||
status=data["status"],
|
||||
version=data["version"],
|
||||
skill_count=data.get("skillCount", 0),
|
||||
uptime=data.get("uptime", 0),
|
||||
)
|
||||
|
||||
async def search(
|
||||
self,
|
||||
query: str,
|
||||
limit: int = 20,
|
||||
include_content: bool = False,
|
||||
) -> SearchResponse:
|
||||
client = self._get_client()
|
||||
params = {"q": query, "limit": str(limit)}
|
||||
if include_content:
|
||||
params["include_content"] = "true"
|
||||
response = await client.get("/search", params=params)
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return SearchResponse(
|
||||
skills=[Skill(**s) for s in data["skills"]],
|
||||
total=data["total"],
|
||||
query=data["query"],
|
||||
limit=data["limit"],
|
||||
)
|
||||
|
||||
async def search_with_filters(
|
||||
self,
|
||||
query: str,
|
||||
limit: int = 20,
|
||||
include_content: bool = False,
|
||||
tags: Optional[list[str]] = None,
|
||||
category: Optional[str] = None,
|
||||
source: Optional[str] = None,
|
||||
) -> SearchResponse:
|
||||
client = self._get_client()
|
||||
body: dict = {"query": query, "limit": limit, "include_content": include_content}
|
||||
filters: dict = {}
|
||||
if tags:
|
||||
filters["tags"] = tags
|
||||
if category:
|
||||
filters["category"] = category
|
||||
if source:
|
||||
filters["source"] = source
|
||||
if filters:
|
||||
body["filters"] = filters
|
||||
response = await client.post("/search", json=body)
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return SearchResponse(
|
||||
skills=[Skill(**s) for s in data["skills"]],
|
||||
total=data["total"],
|
||||
query=data["query"],
|
||||
limit=data["limit"],
|
||||
)
|
||||
|
||||
async def get_skill(self, source: str, skill_id: str) -> Skill:
|
||||
client = self._get_client()
|
||||
parts = source.split("/", 1)
|
||||
owner = quote(parts[0], safe="")
|
||||
repo = quote(parts[1], safe="") if len(parts) > 1 else owner
|
||||
response = await client.get(f"/skills/{owner}/{repo}/{quote(skill_id, safe='')}")
|
||||
response.raise_for_status()
|
||||
return Skill(**response.json())
|
||||
|
||||
async def trending(self, limit: int = 20) -> list[Skill]:
|
||||
client = self._get_client()
|
||||
response = await client.get("/trending", params={"limit": str(limit)})
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return [Skill(**s) for s in data["skills"]]
|
||||
|
||||
async def categories(self) -> list[Category]:
|
||||
client = self._get_client()
|
||||
response = await client.get("/categories")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return [Category(**c) for c in data["categories"]]
|
||||
|
||||
async def cache_stats(self) -> CacheStats:
|
||||
client = self._get_client()
|
||||
response = await client.get("/cache/stats")
|
||||
response.raise_for_status()
|
||||
data = response.json()
|
||||
return CacheStats(
|
||||
hits=data["hits"],
|
||||
misses=data["misses"],
|
||||
size=data["size"],
|
||||
max_size=data.get("maxSize", 0),
|
||||
hit_rate=data.get("hitRate", 0.0),
|
||||
)
|
||||
|
||||
async def close(self) -> None:
|
||||
if self._client:
|
||||
await self._client.aclose()
|
||||
self._client = None
|
||||
@@ -0,0 +1,51 @@
|
||||
from typing import Optional
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class Skill(BaseModel):
|
||||
name: str
|
||||
description: Optional[str] = None
|
||||
source: str
|
||||
repo: Optional[str] = None
|
||||
tags: Optional[list[str]] = None
|
||||
category: Optional[str] = None
|
||||
content: Optional[str] = None
|
||||
stars: Optional[int] = None
|
||||
installs: Optional[int] = None
|
||||
|
||||
|
||||
class SearchResponse(BaseModel):
|
||||
skills: list[Skill]
|
||||
total: int
|
||||
query: str
|
||||
limit: int
|
||||
|
||||
|
||||
class HealthResponse(BaseModel):
|
||||
status: str
|
||||
version: str
|
||||
skill_count: int = 0
|
||||
uptime: int = 0
|
||||
|
||||
|
||||
class CacheStats(BaseModel):
|
||||
hits: int
|
||||
misses: int
|
||||
size: int
|
||||
max_size: int = 0
|
||||
hit_rate: float = 0.0
|
||||
|
||||
|
||||
class Category(BaseModel):
|
||||
name: str
|
||||
count: int
|
||||
|
||||
|
||||
class CategoriesResponse(BaseModel):
|
||||
categories: list[Category]
|
||||
total: int
|
||||
|
||||
|
||||
class TrendingResponse(BaseModel):
|
||||
skills: list[Skill]
|
||||
limit: int
|
||||
@@ -0,0 +1,99 @@
|
||||
import pytest
|
||||
import httpx
|
||||
import respx
|
||||
|
||||
from skillkit import SkillKitClient
|
||||
|
||||
|
||||
BASE_URL = "http://localhost:3737"
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def mock_api():
|
||||
with respx.mock(base_url=BASE_URL) as respx_mock:
|
||||
yield respx_mock
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_health(mock_api):
|
||||
mock_api.get("/health").respond(
|
||||
json={"status": "ok", "version": "1.11.0", "skillCount": 100, "uptime": 60}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
health = await client.health()
|
||||
assert health.status == "ok"
|
||||
assert health.version == "1.11.0"
|
||||
assert health.skill_count == 100
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search(mock_api):
|
||||
mock_api.get("/search").respond(
|
||||
json={
|
||||
"skills": [{"name": "react-perf", "source": "owner/repo"}],
|
||||
"total": 1,
|
||||
"query": "react",
|
||||
"limit": 20,
|
||||
}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
result = await client.search("react")
|
||||
assert result.total == 1
|
||||
assert result.skills[0].name == "react-perf"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_search_with_filters(mock_api):
|
||||
mock_api.post("/search").respond(
|
||||
json={
|
||||
"skills": [{"name": "nextjs-auth", "source": "other/repo"}],
|
||||
"total": 1,
|
||||
"query": "auth",
|
||||
"limit": 20,
|
||||
}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
result = await client.search_with_filters("auth", tags=["nextjs"])
|
||||
assert result.total == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_get_skill(mock_api):
|
||||
mock_api.get("/skills/owner/repo/react-perf").respond(
|
||||
json={"name": "react-perf", "description": "React performance", "source": "owner/repo"}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
skill = await client.get_skill("owner/repo", "react-perf")
|
||||
assert skill.name == "react-perf"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_trending(mock_api):
|
||||
mock_api.get("/trending").respond(
|
||||
json={"skills": [{"name": "a", "source": "x/y"}], "limit": 20}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
trending = await client.trending()
|
||||
assert len(trending) == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_categories(mock_api):
|
||||
mock_api.get("/categories").respond(
|
||||
json={"categories": [{"name": "react", "count": 5}], "total": 1}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
cats = await client.categories()
|
||||
assert len(cats) == 1
|
||||
assert cats[0].name == "react"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_cache_stats(mock_api):
|
||||
mock_api.get("/cache/stats").respond(
|
||||
json={"hits": 10, "misses": 5, "size": 8, "maxSize": 500, "hitRate": 0.667}
|
||||
)
|
||||
async with SkillKitClient(BASE_URL) as client:
|
||||
stats = await client.cache_stats()
|
||||
assert stats.hits == 10
|
||||
assert stats.size == 8
|
||||
@@ -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
|
||||
|
||||
@@ -170,11 +170,19 @@ owner/repo@v1.2.3
|
||||
```bash
|
||||
skillkit memory status # View memory status
|
||||
skillkit memory search <query> # Search learnings
|
||||
skillkit memory compress # Compress observations
|
||||
skillkit memory export <name> # Export as skill
|
||||
skillkit memory compress # Compress observations to learnings
|
||||
skillkit memory export <name> # Export learnings as skill
|
||||
skillkit memory sync-claude # Update CLAUDE.md with learnings
|
||||
skillkit memory index # View memory index (Layer 1)
|
||||
skillkit memory --global # Use global memory
|
||||
```
|
||||
|
||||
| Option | Purpose |
|
||||
|--------|---------|
|
||||
| `--global` | Use global memory instead of project |
|
||||
| `--limit` | Limit number of results |
|
||||
| `--tags` | Filter by tags |
|
||||
|
||||
## Translation Commands
|
||||
|
||||
```bash
|
||||
@@ -226,6 +234,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
|
||||
|
||||
@@ -1,148 +1,153 @@
|
||||
---
|
||||
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.8.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
|
||||
```
|
||||
|
||||
# Or install globally for frequent use
|
||||
That's it. No global install needed. Or if you prefer:
|
||||
|
||||
```bash
|
||||
npm install -g skillkit
|
||||
skillkit init
|
||||
skillkit install anthropics/skills
|
||||
skillkit sync
|
||||
```
|
||||
|
||||
## Core Features
|
||||
Four commands. Your agents now have skills for PDF processing, code review, and more.
|
||||
|
||||
| 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 |
|
||||
| **TypeScript API** | Full programmatic access to all features |
|
||||
| **Interactive TUI** | Beautiful terminal interface with real-time updates |
|
||||
## What Can You Do?
|
||||
|
||||
## Advanced Capabilities
|
||||
|
||||
### Session Memory System
|
||||
|
||||
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)
|
||||
### Get smart recommendations
|
||||
|
||||
SkillKit reads your `package.json`, detects your stack, and suggests relevant skills:
|
||||
|
||||
```bash
|
||||
skillkit recommend
|
||||
# 92% vercel-react-best-practices
|
||||
# 87% tailwind-v4-patterns
|
||||
# 85% nextjs-app-router
|
||||
```
|
||||
|
||||
### Discover skills at runtime
|
||||
|
||||
Start an API server and let agents find skills on demand:
|
||||
|
||||
```bash
|
||||
skillkit serve
|
||||
# Server running at http://localhost:3737
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3737/search?q=react+performance"
|
||||
```
|
||||
|
||||
Or use MCP for native agent integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skillkit": { "command": "npx", "args": ["@skillkit/mcp"] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[REST API](/docs/rest-api) | [MCP Server](/docs/mcp-server) | [Python Client](/docs/python-client)
|
||||
|
||||
## How It Works
|
||||
|
||||
SkillKit sits between your skills and your agents. It handles format translation, discovery, and synchronization automatically.
|
||||
|
||||
| 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 |
|
||||
|
||||
## Supported Agents
|
||||
|
||||
32 agents and counting:
|
||||
|
||||
**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
|
||||
|
||||
[Full agent details](/docs/agents)
|
||||
|
||||
## 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
|
||||
|
||||
Run agents across multiple machines with encrypted P2P communication.
|
||||
Distribute agents across machines with encrypted P2P:
|
||||
|
||||
```bash
|
||||
skillkit mesh init # Initialize mesh node
|
||||
skillkit mesh discover # Find peers on LAN
|
||||
skillkit mesh security init # Setup Ed25519 encryption
|
||||
skillkit mesh init
|
||||
skillkit mesh discover
|
||||
```
|
||||
|
||||
[Learn more →](/docs/mesh)
|
||||
### Team Collaboration
|
||||
|
||||
### Inter-Agent Messaging
|
||||
|
||||
Send messages between AI agents across your mesh network.
|
||||
Share skills via a Git-committable `.skills` manifest:
|
||||
|
||||
```bash
|
||||
skillkit message send # Send to another agent
|
||||
skillkit message inbox # Check your inbox
|
||||
skillkit manifest init
|
||||
skillkit manifest add anthropics/skills
|
||||
git commit -m "add team skills"
|
||||
```
|
||||
|
||||
[Learn more →](/docs/messaging)
|
||||
Team members run `skillkit manifest install` and they're in sync.
|
||||
|
||||
## Architecture
|
||||
## Next Steps
|
||||
|
||||
| Tier | Components |
|
||||
|------|------------|
|
||||
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/React), Documentation |
|
||||
| **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) |
|
||||
- [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
|
||||
|
||||
## Supported Agents (32)
|
||||
|
||||
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
|
||||
|
||||
[Full agent details →](/docs/agents)
|
||||
|
||||
## Popular Skill Sources
|
||||
|
||||
| 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 |
|
||||
|
||||
## Get Started
|
||||
|
||||
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
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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 <command>
|
||||
```
|
||||
|
||||
## GitHub Packages
|
||||
Both `skillkit` and `sk` work as command aliases.
|
||||
|
||||
```bash
|
||||
npm install -g @rohitg00/skillkit --registry=https://npm.pkg.github.com
|
||||
```
|
||||
|
||||
## 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)
|
||||
|
||||
## First Run Experience
|
||||
|
||||
When you run SkillKit for the first time, it initiates an interactive onboarding that:
|
||||
|
||||
1. Detects your current AI agent automatically
|
||||
2. Creates necessary project directories
|
||||
3. Gathers user preferences for future sessions
|
||||
4. Displays contextual guidance
|
||||
|
||||
Preferences are stored in `~/.skillkit/preferences.json`.
|
||||
|
||||
## Initialize a Project
|
||||
## Initialize a project
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
skillkit init
|
||||
```
|
||||
|
||||
### Init Command Options
|
||||
The init command:
|
||||
|
||||
| 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 |
|
||||
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
|
||||
|
||||
### What Init Creates
|
||||
### Specify an agent directly
|
||||
|
||||
| Agent | Skills Directory | Config File |
|
||||
|-------|-----------------|-------------|
|
||||
```bash
|
||||
skillkit init --agent cursor
|
||||
skillkit init --list # Show all 32 supported agents
|
||||
skillkit init --quiet # Skip logo and prompts (for CI)
|
||||
```
|
||||
|
||||
### What gets created
|
||||
|
||||
| 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
|
||||
Preferences are stored in `~/.skillkit/preferences.json`.
|
||||
|
||||
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
|
||||
|
||||
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)
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: MCP Server
|
||||
description: Agent-native skill discovery via Model Context Protocol
|
||||
---
|
||||
|
||||
# MCP Server
|
||||
|
||||
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 this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skillkit": {
|
||||
"command": "npx",
|
||||
"args": ["@skillkit/mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart Claude Desktop. Done.
|
||||
|
||||
### Cursor
|
||||
|
||||
Add to `.cursor/mcp.json` in your project:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skillkit": {
|
||||
"command": "npx",
|
||||
"args": ["@skillkit/mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Any MCP client
|
||||
|
||||
The server uses stdio transport. Works with any MCP-compatible client:
|
||||
|
||||
```bash
|
||||
npx @skillkit/mcp
|
||||
```
|
||||
|
||||
## What your agent can do
|
||||
|
||||
Once connected, your agent gets four tools:
|
||||
|
||||
### Search skills
|
||||
|
||||
Ask your agent: *"Find skills for React performance optimization"*
|
||||
|
||||
Behind the scenes, it calls `search_skills` with your query and returns ranked results. You can filter by tags, category, or source repository.
|
||||
|
||||
```
|
||||
> Search for authentication skills tagged with "security"
|
||||
```
|
||||
|
||||
The agent searches across the full catalog, ranks results by relevance, and shows you the best matches.
|
||||
|
||||
### Get a specific skill
|
||||
|
||||
Ask: *"Get the pdf-processing skill from anthropics/skills"*
|
||||
|
||||
The agent calls `get_skill` and returns the full skill details — description, tags, content, and references.
|
||||
|
||||
### Get recommendations
|
||||
|
||||
Ask: *"What skills would you recommend for my TypeScript React project?"*
|
||||
|
||||
The agent calls `recommend_skills` with your stack context (languages, frameworks, libraries) and returns personalized suggestions ranked by relevance.
|
||||
|
||||
### Browse categories
|
||||
|
||||
Ask: *"What skill categories are available?"*
|
||||
|
||||
The agent calls `list_categories` and returns all categories with counts, so you know what's out there.
|
||||
|
||||
## Resources
|
||||
|
||||
The server also exposes two read-only resources:
|
||||
|
||||
- **`skills://trending`** — Top 20 skills by relevance score
|
||||
- **`skills://categories`** — All categories with counts
|
||||
|
||||
Agents can read these without making a tool call.
|
||||
|
||||
## How it works
|
||||
|
||||
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
|
||||
|
||||
Same ranking, same data, same quality — just native to your agent instead of going through HTTP.
|
||||
@@ -5,25 +5,51 @@ description: Persistent learning across AI agent sessions
|
||||
|
||||
# Memory System
|
||||
|
||||
Capture learnings from AI sessions and convert them into reusable skills.
|
||||
Capture learnings from AI sessions and convert them into reusable skills. SkillKit's memory system provides automatic observation capture, intelligent compression, and token-optimized retrieval.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
skillkit memory status # View status
|
||||
skillkit memory search <q> # Search learnings
|
||||
skillkit memory compress # Compress observations
|
||||
skillkit memory compress # Compress observations to learnings
|
||||
skillkit memory export <name> # Export as skill
|
||||
skillkit memory --global # Global memory
|
||||
skillkit memory sync-claude # Update CLAUDE.md with learnings
|
||||
skillkit memory index # View memory index (Layer 1)
|
||||
skillkit memory --global # Global memory operations
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Observations** - Track patterns during sessions
|
||||
2. **Compression** - Distill into reusable knowledge
|
||||
3. **Injection** - Load into new sessions
|
||||
### Observation → Learning Pipeline
|
||||
|
||||
1. **Observations** - Track patterns during sessions (tool use, errors, solutions)
|
||||
2. **Compression** - Distill observations into reusable learnings
|
||||
3. **Injection** - Load relevant learnings into new sessions
|
||||
4. **Export** - Convert to shareable skills
|
||||
|
||||
### Lifecycle Hooks
|
||||
|
||||
SkillKit integrates with Claude Code's lifecycle hooks for automatic memory capture:
|
||||
|
||||
| Hook | Trigger | Action |
|
||||
|------|---------|--------|
|
||||
| **SessionStart** | Session begins | Inject relevant learnings |
|
||||
| **PostToolUse** | Tool completes | Capture outcomes as observations |
|
||||
| **SessionEnd** | Session closes | Compress observations to learnings |
|
||||
|
||||
### Progressive Disclosure (Token Optimization)
|
||||
|
||||
Memory retrieval uses a 3-layer system to minimize token usage:
|
||||
|
||||
| Layer | Content | ~Tokens |
|
||||
|-------|---------|---------|
|
||||
| **Index** | Titles, tags, timestamps | 50-100 |
|
||||
| **Timeline** | Context, excerpts, activity | ~200 |
|
||||
| **Details** | Full content, metadata | 500-1000 |
|
||||
|
||||
The system starts with Layer 1 and progressively fetches deeper layers based on relevance and token budget.
|
||||
|
||||
## Storage
|
||||
|
||||
```
|
||||
@@ -31,17 +57,123 @@ skillkit memory --global # Global memory
|
||||
├── observations/ # Raw session data
|
||||
├── learnings/ # Compressed knowledge
|
||||
└── index.json # Memory index
|
||||
|
||||
<project>/.skillkit/memory/
|
||||
├── observations/ # Project-specific observations
|
||||
├── learnings/ # Project learnings
|
||||
└── index.json # Project memory index
|
||||
```
|
||||
|
||||
## Auto-CLAUDE.md Updates
|
||||
|
||||
Sync your most effective learnings to CLAUDE.md:
|
||||
|
||||
```bash
|
||||
skillkit memory sync-claude
|
||||
```
|
||||
|
||||
This populates the `## LEARNED` section with high-effectiveness insights, giving your agent persistent context across sessions.
|
||||
|
||||
## Programmatic API
|
||||
|
||||
### Memory Compression
|
||||
|
||||
```typescript
|
||||
import { MemoryCompressor, LearningStore } from '@skillkit/core'
|
||||
|
||||
const compressor = new MemoryCompressor()
|
||||
const learning = await compressor.compress(observations)
|
||||
const compressor = new MemoryCompressor(projectPath)
|
||||
const { learnings } = await compressor.compress(observations)
|
||||
|
||||
const store = new LearningStore()
|
||||
const store = new LearningStore('project', projectPath)
|
||||
await store.add(learning)
|
||||
const results = await store.search('authentication')
|
||||
```
|
||||
|
||||
### Lifecycle Hooks
|
||||
|
||||
```typescript
|
||||
import { MemoryHookManager } from '@skillkit/core'
|
||||
|
||||
const manager = new MemoryHookManager(projectPath)
|
||||
|
||||
// Session start - inject relevant learnings
|
||||
const startResult = await manager.onSessionStart()
|
||||
|
||||
// After tool use - capture outcomes
|
||||
await manager.onToolUse({
|
||||
tool_name: 'Write',
|
||||
tool_input: { file_path: '/src/auth.ts' },
|
||||
tool_result: 'File written successfully',
|
||||
duration_ms: 150
|
||||
})
|
||||
|
||||
// Session end - compress to learnings
|
||||
const endResult = await manager.onSessionEnd()
|
||||
```
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
```typescript
|
||||
import { ProgressiveDisclosureManager } from '@skillkit/core'
|
||||
|
||||
const pdm = new ProgressiveDisclosureManager(projectPath)
|
||||
|
||||
// Layer 1: Index (~50 tokens each)
|
||||
const index = pdm.getIndex({ includeGlobal: true })
|
||||
|
||||
// Layer 2: Timeline (~200 tokens each)
|
||||
const timeline = pdm.getTimeline(['id1', 'id2'])
|
||||
|
||||
// Layer 3: Full details (~600 tokens each)
|
||||
const details = pdm.getDetails(['id1'])
|
||||
|
||||
// Smart retrieval with token budget
|
||||
const result = pdm.smartRetrieve('authentication patterns', 2000)
|
||||
// Returns optimal layer based on budget
|
||||
```
|
||||
|
||||
### CLAUDE.md Updater
|
||||
|
||||
```typescript
|
||||
import { ClaudeMdUpdater } from '@skillkit/core'
|
||||
|
||||
const updater = new ClaudeMdUpdater(projectPath)
|
||||
|
||||
// Preview what would be updated
|
||||
const preview = updater.preview({ minEffectiveness: 70 })
|
||||
|
||||
// Update CLAUDE.md
|
||||
const result = updater.update({
|
||||
minEffectiveness: 60,
|
||||
maxLearnings: 20,
|
||||
preserveManualEntries: true
|
||||
})
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure memory behavior in `.skillkit/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"memory": {
|
||||
"enabled": true,
|
||||
"autoInjectOnSessionStart": true,
|
||||
"autoCaptureToolUse": true,
|
||||
"autoCompressOnSessionEnd": true,
|
||||
"minRelevanceForCapture": 30,
|
||||
"maxTokensForInjection": 2000,
|
||||
"compressionThreshold": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Claude Code Integration
|
||||
|
||||
Generate hooks configuration for Claude Code:
|
||||
|
||||
```typescript
|
||||
const manager = new MemoryHookManager(projectPath)
|
||||
const config = manager.generateClaudeCodeHooksConfig()
|
||||
// Outputs hooks.json format for Claude Code integration
|
||||
```
|
||||
|
||||
@@ -20,6 +20,9 @@
|
||||
"commands",
|
||||
"configuration",
|
||||
"api-reference",
|
||||
"rest-api",
|
||||
"mcp-server",
|
||||
"python-client",
|
||||
"cicd",
|
||||
"teams",
|
||||
"custom-agents",
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Python Client
|
||||
description: Async Python SDK for skill discovery
|
||||
---
|
||||
|
||||
# Python Client
|
||||
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pip install skillkit-client
|
||||
```
|
||||
|
||||
Requires Python 3.10+.
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
from skillkit import SkillKitClient
|
||||
|
||||
async with SkillKitClient() as client:
|
||||
results = await client.search("react performance", limit=5)
|
||||
for skill in results.skills:
|
||||
print(f"{skill.name}: {skill.description}")
|
||||
```
|
||||
|
||||
The client connects to `http://localhost:3737` by default. Make sure the API server is running:
|
||||
|
||||
```bash
|
||||
skillkit serve
|
||||
```
|
||||
|
||||
## Search with filters
|
||||
|
||||
```python
|
||||
results = await client.search_with_filters(
|
||||
"authentication",
|
||||
tags=["security"],
|
||||
category="backend",
|
||||
limit=10,
|
||||
)
|
||||
```
|
||||
|
||||
## Get a specific skill
|
||||
|
||||
```python
|
||||
skill = await client.get_skill("anthropics/skills", "pdf-processing")
|
||||
print(skill.name, skill.description, skill.tags)
|
||||
```
|
||||
|
||||
## Trending and categories
|
||||
|
||||
```python
|
||||
trending = await client.trending(limit=10)
|
||||
categories = await client.categories()
|
||||
|
||||
for skill in trending:
|
||||
print(f"{skill.name} ({skill.source})")
|
||||
|
||||
for cat in categories:
|
||||
print(f"{cat.name}: {cat.count} skills")
|
||||
```
|
||||
|
||||
## Health and cache
|
||||
|
||||
```python
|
||||
health = await client.health()
|
||||
print(f"v{health.version} — {health.skill_count} skills loaded")
|
||||
|
||||
stats = await client.cache_stats()
|
||||
print(f"Cache hit rate: {stats.hit_rate:.0%}")
|
||||
```
|
||||
|
||||
## Connect to a remote server
|
||||
|
||||
```python
|
||||
async with SkillKitClient("https://my-server.example.com:3737") as client:
|
||||
results = await client.search("deployment")
|
||||
```
|
||||
|
||||
## Models
|
||||
|
||||
The client returns typed dataclasses:
|
||||
|
||||
```python
|
||||
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)
|
||||
```
|
||||
|
||||
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 talks to the SkillKit REST API. You need a running server:
|
||||
|
||||
```bash
|
||||
skillkit serve
|
||||
```
|
||||
|
||||
Then run your Python script in another terminal. The client handles connection management, retries, and cleanup automatically when used with `async with`.
|
||||
@@ -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:
|
||||
## 1. Init
|
||||
|
||||
```bash
|
||||
npx skillkit@latest
|
||||
npx skillkit@latest init
|
||||
```
|
||||
|
||||
Or install globally for frequent use:
|
||||
SkillKit detects your AI agent, creates the skills directory, and saves your preferences.
|
||||
|
||||
```bash
|
||||
npm install -g skillkit
|
||||
skillkit --version
|
||||
```
|
||||
|
||||
## 2. Initialize Your Project
|
||||
|
||||
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?
|
||||
|
||||
### Translate between agents
|
||||
|
||||
Already have Claude skills? Deploy them to Cursor:
|
||||
|
||||
```bash
|
||||
skillkit translate my-skill --to cursor
|
||||
```
|
||||
|
||||
### Auto-generate agent instructions
|
||||
|
||||
Let SkillKit analyze your codebase and create CLAUDE.md, .cursorrules, etc.:
|
||||
|
||||
```bash
|
||||
skillkit primer --all-agents
|
||||
```
|
||||
|
||||
### Launch the TUI
|
||||
|
||||
```bash
|
||||
skillkit ui
|
||||
# or just
|
||||
skillkit
|
||||
```
|
||||
|
||||
**Navigation:** `h` Home | `m` Marketplace | `r` Recommend | `i` Installed | `s` Sync | `q` Quit
|
||||
`h` Home | `m` Marketplace | `r` Recommend | `i` Installed | `s` Sync | `q` Quit
|
||||
|
||||
## Complete Example
|
||||
### Start the discovery server
|
||||
|
||||
Let agents find skills at runtime:
|
||||
|
||||
```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 serve
|
||||
```
|
||||
|
||||
## 7. Advanced Features
|
||||
[REST API](/docs/rest-api) | [MCP Server](/docs/mcp-server)
|
||||
|
||||
### Auto-Generate Instructions (Primer)
|
||||
|
||||
Let SkillKit analyze your codebase and generate optimized instructions:
|
||||
### Share with your team
|
||||
|
||||
```bash
|
||||
skillkit primer # Analyze and generate
|
||||
skillkit primer --all-agents # Generate for all 32 agents
|
||||
```
|
||||
|
||||
[Learn more about Primer →](/docs/primer)
|
||||
|
||||
### Session Memory
|
||||
|
||||
Capture learnings from your AI sessions:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
[Learn more about Mesh →](/docs/mesh)
|
||||
|
||||
### Inter-Agent Messaging
|
||||
|
||||
Send messages between AI agents:
|
||||
|
||||
```bash
|
||||
skillkit message send # Send to another agent
|
||||
skillkit message inbox # Check your inbox
|
||||
skillkit message reply <id> # Reply to message
|
||||
```
|
||||
|
||||
[Learn more about Messaging →](/docs/messaging)
|
||||
|
||||
## Team Collaboration
|
||||
|
||||
Share skills with your team using manifest files:
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
[Learn more about Workflows →](/docs/workflows)
|
||||
## Next steps
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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)
|
||||
- [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
|
||||
|
||||
@@ -0,0 +1,205 @@
|
||||
---
|
||||
title: REST API
|
||||
description: Runtime skill discovery via HTTP
|
||||
---
|
||||
|
||||
# REST 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.
|
||||
|
||||
## Start the server
|
||||
|
||||
```bash
|
||||
skillkit serve
|
||||
```
|
||||
|
||||
That's it. The API is now running at `http://localhost:3737`.
|
||||
|
||||
## Search for skills
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3737/search?q=react+performance"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"name": "react-performance",
|
||||
"description": "React app performance optimization",
|
||||
"source": "anthropics/skills",
|
||||
"tags": ["react", "performance"],
|
||||
"score": 87
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"query": "react performance",
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
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",
|
||||
"filters": { "tags": ["security"], "category": "backend" }
|
||||
}'
|
||||
```
|
||||
|
||||
### 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 a specific skill
|
||||
|
||||
```bash
|
||||
curl http://localhost:3737/skills/anthropics/skills/pdf-processing
|
||||
```
|
||||
|
||||
The path follows the pattern `/skills/:owner/:repo/:skill-name`.
|
||||
|
||||
## Browse trending skills
|
||||
|
||||
```bash
|
||||
curl http://localhost:3737/trending?limit=10
|
||||
```
|
||||
|
||||
Returns the top skills ranked by relevance score across all sources.
|
||||
|
||||
## List categories
|
||||
|
||||
```bash
|
||||
curl http://localhost:3737/categories
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"categories": [
|
||||
{ "name": "react", "count": 156 },
|
||||
{ "name": "typescript", "count": 134 },
|
||||
{ "name": "testing", "count": 89 }
|
||||
],
|
||||
"total": 89
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Server options
|
||||
|
||||
```bash
|
||||
skillkit serve --port 8080 --host localhost --cors "http://localhost:3000"
|
||||
```
|
||||
|
||||
| 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
|
||||
|
||||
60 requests per minute per IP. Response headers tell you where you stand:
|
||||
|
||||
| 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
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"hits": 142,
|
||||
"misses": 38,
|
||||
"size": 45,
|
||||
"maxSize": 500,
|
||||
"hitRate": 0.789
|
||||
}
|
||||
```
|
||||
|
||||
## Health check
|
||||
|
||||
```bash
|
||||
curl http://localhost:3737/health
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "1.12.0",
|
||||
"skillCount": 15062,
|
||||
"uptime": 3600
|
||||
}
|
||||
```
|
||||
|
||||
## Use it programmatically
|
||||
|
||||
```typescript
|
||||
import { createApp, startServer } from '@skillkit/api';
|
||||
|
||||
const { server, app, cache } = await startServer({
|
||||
port: 3737,
|
||||
skills: mySkillsArray,
|
||||
});
|
||||
```
|
||||
|
||||
Or get just the Hono app for testing:
|
||||
|
||||
```typescript
|
||||
const { app, cache } = createApp({
|
||||
skills: mySkillsArray,
|
||||
cacheTtlMs: 3_600_000,
|
||||
});
|
||||
```
|
||||
|
||||
## Interactive 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.
|
||||
|
||||
The hosted version is available at [agenstskills.com/api](https://agenstskills.com/api).
|
||||
|
||||
## All 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 |
|
||||
| GET | `/docs` | Swagger UI |
|
||||
| GET | `/openapi.json` | OpenAPI spec |
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit-docs",
|
||||
"version": "1.9.0",
|
||||
"version": "1.12.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "next build",
|
||||
|
||||
+39
-4
@@ -12,6 +12,9 @@ import { Attribution } from './components/Attribution';
|
||||
import { AdvancedFeatures } from './components/AdvancedFeatures';
|
||||
import { UseCases } from './components/UseCases';
|
||||
import { TeamEnterprise } from './components/TeamEnterprise';
|
||||
import { BadgeGenerator } from './components/BadgeGenerator';
|
||||
import { CompatibilityMatrix } from './components/CompatibilityMatrix';
|
||||
import { useStats } from './hooks/useStats';
|
||||
|
||||
const GITHUB_ICON = (
|
||||
<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
|
||||
@@ -34,6 +37,8 @@ function scrollToSection(e: React.MouseEvent, sectionId: string): void {
|
||||
}
|
||||
|
||||
export default function App(): React.ReactElement {
|
||||
const stats = useStats();
|
||||
|
||||
return (
|
||||
<div className="min-h-screen text-zinc-100 font-sans selection:bg-white selection:text-black" style={{ backgroundColor: '#000000' }}>
|
||||
<nav className="fixed top-0 left-0 right-0 z-50 border-b border-zinc-800 backdrop-blur-md" style={{ backgroundColor: 'rgba(0,0,0,0.9)' }}>
|
||||
@@ -58,6 +63,20 @@ export default function App(): React.ReactElement {
|
||||
>
|
||||
Stack
|
||||
</a>
|
||||
<a
|
||||
href="#matrix"
|
||||
onClick={(e) => scrollToSection(e, 'matrix')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Matrix
|
||||
</a>
|
||||
<a
|
||||
href="#badge"
|
||||
onClick={(e) => scrollToSection(e, 'badge')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Badge
|
||||
</a>
|
||||
<a
|
||||
href="#advanced"
|
||||
onClick={(e) => scrollToSection(e, 'advanced')}
|
||||
@@ -81,6 +100,12 @@ export default function App(): React.ReactElement {
|
||||
</a>
|
||||
</div>
|
||||
<div className="flex items-center gap-3 sm:gap-4">
|
||||
<a
|
||||
href="/api"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
|
||||
>
|
||||
API
|
||||
</a>
|
||||
<a
|
||||
href="https://agenstskills.com/docs"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
|
||||
@@ -102,7 +127,7 @@ export default function App(): React.ReactElement {
|
||||
</nav>
|
||||
|
||||
<main className="pt-14">
|
||||
<Hero />
|
||||
<Hero version={stats.version} />
|
||||
|
||||
<div className="border-b border-zinc-800/50 py-2.5" style={{ background: 'linear-gradient(to bottom, rgba(9,9,11,0.95), rgba(0,0,0,1))' }}>
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
@@ -114,7 +139,7 @@ export default function App(): React.ReactElement {
|
||||
className="flex items-center gap-1.5 text-zinc-500 hover:text-white transition-colors group"
|
||||
>
|
||||
<span className="text-zinc-600 group-hover:text-zinc-400">v</span>
|
||||
<span className="text-white font-medium">1.8.0</span>
|
||||
<span className="text-white font-medium">{stats.version}</span>
|
||||
</a>
|
||||
<span className="text-zinc-800">·</span>
|
||||
<a
|
||||
@@ -126,7 +151,7 @@ export default function App(): React.ReactElement {
|
||||
<svg className="w-3 h-3 text-zinc-600 group-hover:text-zinc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
|
||||
</svg>
|
||||
<span className="text-white font-medium">2.4k</span>
|
||||
<span className="text-white font-medium">{stats.downloads}</span>
|
||||
</a>
|
||||
<span className="text-zinc-800">·</span>
|
||||
<a
|
||||
@@ -138,7 +163,7 @@ export default function App(): React.ReactElement {
|
||||
<svg className="w-3 h-3 text-zinc-600 group-hover:text-yellow-500" fill="currentColor" viewBox="0 0 24 24">
|
||||
<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" />
|
||||
</svg>
|
||||
<span className="text-white font-medium">66</span>
|
||||
<span className="text-white font-medium">{stats.stars}</span>
|
||||
</a>
|
||||
<span className="text-zinc-800 hidden sm:inline">·</span>
|
||||
<a
|
||||
@@ -169,6 +194,16 @@ export default function App(): React.ReactElement {
|
||||
<StackBuilder />
|
||||
</section>
|
||||
|
||||
{/* Compatibility Matrix */}
|
||||
<section id="matrix" style={{ scrollMarginTop: '4rem' }}>
|
||||
<CompatibilityMatrix />
|
||||
</section>
|
||||
|
||||
{/* Badge Generator */}
|
||||
<section id="badge" style={{ scrollMarginTop: '4rem' }}>
|
||||
<BadgeGenerator />
|
||||
</section>
|
||||
|
||||
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
|
||||
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
|
||||
<AdvancedFeatures />
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
import React, { useState, useMemo } from 'react';
|
||||
|
||||
const SKILLKIT_LOGO_SVG_BASE64 =
|
||||
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
|
||||
|
||||
const SUGGESTED_SKILLS = [
|
||||
'react', 'typescript', 'nextjs', 'python', 'docker',
|
||||
'kubernetes', 'tailwind', 'graphql', 'prisma', 'langchain',
|
||||
'openai', 'rust', 'go', 'vue', 'svelte',
|
||||
'security', 'testing', 'cicd', 'aws', 'terraform',
|
||||
];
|
||||
|
||||
function encodeBadgeSegment(text: string): string {
|
||||
return encodeURIComponent(text).replace(/-/g, '--');
|
||||
}
|
||||
|
||||
function buildBadgeUrl(skills: string[]): string {
|
||||
if (skills.length === 0) {
|
||||
return `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
|
||||
}
|
||||
|
||||
const maxDisplay = 5;
|
||||
const displayNames = skills.slice(0, maxDisplay);
|
||||
const suffix = skills.length > maxDisplay ? ` +${skills.length - maxDisplay} more` : '';
|
||||
const label = `SkillKit ${skills.length} skills`;
|
||||
const message = displayNames.join(' | ') + suffix;
|
||||
|
||||
return `https://img.shields.io/badge/${encodeBadgeSegment(label)}-${encodeBadgeSegment(message)}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
|
||||
}
|
||||
|
||||
export function BadgeGenerator(): React.ReactElement {
|
||||
const [skills, setSkills] = useState<string[]>(['react', 'typescript', 'nextjs']);
|
||||
const [inputValue, setInputValue] = useState('');
|
||||
const [copiedType, setCopiedType] = useState<string | null>(null);
|
||||
|
||||
const badgeUrl = useMemo(() => buildBadgeUrl(skills), [skills]);
|
||||
|
||||
const markdown = `[](https://agenstskills.com)`;
|
||||
const html = `<a href="https://agenstskills.com"><img src="${badgeUrl}" alt="SkillKit Stack" /></a>`;
|
||||
|
||||
function addSkill(skill: string): void {
|
||||
const trimmed = skill.trim().toLowerCase();
|
||||
if (trimmed && !skills.includes(trimmed)) {
|
||||
setSkills([...skills, trimmed]);
|
||||
}
|
||||
setInputValue('');
|
||||
}
|
||||
|
||||
function removeSkill(skill: string): void {
|
||||
setSkills(skills.filter(s => s !== skill));
|
||||
}
|
||||
|
||||
function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>): void {
|
||||
if (e.key === 'Enter' && inputValue.trim()) {
|
||||
e.preventDefault();
|
||||
addSkill(inputValue);
|
||||
}
|
||||
}
|
||||
|
||||
async function copyToClipboard(text: string, type: string): Promise<void> {
|
||||
try {
|
||||
await navigator.clipboard.writeText(text);
|
||||
setCopiedType(type);
|
||||
setTimeout(() => setCopiedType(null), 2000);
|
||||
} catch {
|
||||
// silently ignore
|
||||
}
|
||||
}
|
||||
|
||||
const availableSuggestions = SUGGESTED_SKILLS.filter(s => !skills.includes(s));
|
||||
|
||||
return (
|
||||
<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="mb-6">
|
||||
<h2 className="text-xl font-bold text-white mb-1 font-mono">Badge Generator</h2>
|
||||
<p className="text-zinc-500 font-mono text-xs">
|
||||
Create a shareable badge for your skill stack. Add it to your README.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div className="flex flex-col lg:flex-row gap-6">
|
||||
<div className="flex-1 space-y-4">
|
||||
<div className="relative">
|
||||
<input
|
||||
type="text"
|
||||
value={inputValue}
|
||||
onChange={(e) => setInputValue(e.target.value)}
|
||||
onKeyDown={handleKeyDown}
|
||||
placeholder="Type a skill name and press Enter..."
|
||||
className="w-full bg-zinc-900 border border-zinc-700 text-white px-4 py-3 focus:ring-2 focus:ring-white focus:border-transparent outline-none font-mono text-sm placeholder-zinc-600"
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div className="space-y-2">
|
||||
<span className="text-zinc-500 text-xs font-mono block">Quick add:</span>
|
||||
<div className="flex flex-wrap gap-1.5">
|
||||
{availableSuggestions.slice(0, 12).map(skill => (
|
||||
<button
|
||||
key={skill}
|
||||
onClick={() => addSkill(skill)}
|
||||
className="text-[10px] sm:text-xs bg-zinc-900 text-zinc-400 px-2 sm:px-3 py-1 sm:py-1.5 border border-zinc-700 hover:border-zinc-500 hover:text-white transition-colors font-mono"
|
||||
>
|
||||
+ {skill}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{skills.length > 0 && (
|
||||
<div className="space-y-2">
|
||||
<div className="flex items-center justify-between">
|
||||
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">
|
||||
Skills in Badge ({skills.length})
|
||||
</div>
|
||||
<button
|
||||
onClick={() => setSkills([])}
|
||||
className="text-zinc-500 hover:text-red-400 font-mono text-xs transition-colors"
|
||||
>
|
||||
Clear All
|
||||
</button>
|
||||
</div>
|
||||
<div className="flex flex-wrap gap-2">
|
||||
{skills.map(skill => (
|
||||
<div
|
||||
key={skill}
|
||||
className="flex items-center gap-1.5 bg-zinc-900/50 border border-zinc-800 px-3 py-1.5 group"
|
||||
>
|
||||
<span className="font-mono text-sm text-white">{skill}</span>
|
||||
<button
|
||||
onClick={() => removeSkill(skill)}
|
||||
aria-label={`Remove ${skill}`}
|
||||
className="text-zinc-600 hover:text-red-400 transition-colors opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
|
||||
>
|
||||
<svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div className="lg:w-80 lg:flex-shrink-0">
|
||||
<div className="lg:sticky lg:top-20 bg-zinc-900/30 border border-zinc-800 p-4 space-y-4">
|
||||
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">Preview</div>
|
||||
|
||||
<div className="flex justify-center py-3 bg-black/50 border border-zinc-800">
|
||||
{skills.length > 0 ? (
|
||||
<img
|
||||
src={badgeUrl}
|
||||
alt="SkillKit Stack Badge"
|
||||
className="h-5"
|
||||
/>
|
||||
) : (
|
||||
<span className="text-zinc-600 text-xs font-mono">Add skills to preview</span>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs font-mono text-zinc-500">Markdown</div>
|
||||
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
|
||||
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
|
||||
{markdown}
|
||||
</code>
|
||||
</pre>
|
||||
<button
|
||||
onClick={() => copyToClipboard(markdown, 'markdown')}
|
||||
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
|
||||
>
|
||||
{copiedType === 'markdown' ? 'Copied!' : 'Copy Markdown'}
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs font-mono text-zinc-500">HTML</div>
|
||||
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
|
||||
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
|
||||
{html}
|
||||
</code>
|
||||
</pre>
|
||||
<button
|
||||
onClick={() => copyToClipboard(html, 'html')}
|
||||
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
|
||||
>
|
||||
{copiedType === 'html' ? 'Copied!' : 'Copy HTML'}
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div className="text-[10px] font-mono text-zinc-600 text-center pt-2 border-t border-zinc-800">
|
||||
Powered by shields.io
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -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>
|
||||
|
||||
@@ -0,0 +1,351 @@
|
||||
import React, { useState, useMemo } from 'react';
|
||||
|
||||
type Support = 'full' | 'partial' | 'none';
|
||||
|
||||
interface AgentDef {
|
||||
id: string;
|
||||
name: string;
|
||||
icon: string;
|
||||
group: string;
|
||||
}
|
||||
|
||||
interface CategoryDef {
|
||||
id: string;
|
||||
name: string;
|
||||
icon: string;
|
||||
}
|
||||
|
||||
const AGENTS: AgentDef[] = [
|
||||
{ id: 'claude-code', name: 'Claude Code', icon: '\u27C1', group: 'Tier 1' },
|
||||
{ id: 'cursor', name: 'Cursor', icon: '\u25EB', group: 'Tier 1' },
|
||||
{ id: 'codex', name: 'Codex', icon: '\u25CE', group: 'Tier 1' },
|
||||
{ id: 'gemini-cli', name: 'Gemini CLI', icon: '\u2726', group: 'Tier 1' },
|
||||
{ id: 'opencode', name: 'OpenCode', icon: '\u2B21', group: 'Tier 1' },
|
||||
{ id: 'windsurf', name: 'Windsurf', icon: '\u25C7', group: 'Tier 1' },
|
||||
{ id: 'github-copilot', name: 'Copilot', icon: '\u2318', group: 'Tier 1' },
|
||||
{ id: 'goose', name: 'Goose', icon: '\u25CA', group: 'Tier 2' },
|
||||
{ id: 'kilo', name: 'Kilo', icon: '\u25B3', group: 'Tier 2' },
|
||||
{ id: 'kiro-cli', name: 'Kiro CLI', icon: '\u25BD', group: 'Tier 2' },
|
||||
{ id: 'roo', name: 'Roo', icon: '\u25C6', group: 'Tier 2' },
|
||||
{ id: 'trae', name: 'Trae', icon: '\u25A0', group: 'Tier 2' },
|
||||
{ id: 'amp', name: 'AMP', icon: '\u26A1', group: 'Tier 2' },
|
||||
{ id: 'cline', name: 'Cline', icon: '\u25CF', group: 'Tier 3' },
|
||||
{ id: 'continue', name: 'Continue', icon: '\u25B6', group: 'Tier 3' },
|
||||
{ id: 'antigravity', name: 'Antigravity', icon: '\u2191', group: 'Tier 3' },
|
||||
];
|
||||
|
||||
const CATEGORIES: CategoryDef[] = [
|
||||
{ id: 'security', name: 'Security', icon: '\u25D0' },
|
||||
{ id: 'testing', name: 'Testing', icon: '\u25D2' },
|
||||
{ id: 'react-frontend', name: 'React/Frontend', icon: '\u269B' },
|
||||
{ id: 'backend', name: 'Backend', icon: '\u2393' },
|
||||
{ id: 'devops', name: 'DevOps', icon: '\u25D1' },
|
||||
{ id: 'python', name: 'Python', icon: '\u25C9' },
|
||||
{ id: 'go', name: 'Go', icon: '\u25C8' },
|
||||
{ id: 'typescript', name: 'TypeScript', icon: '\u25C8' },
|
||||
{ id: 'database', name: 'Database', icon: '\u25A3' },
|
||||
{ id: 'performance', name: 'Performance', icon: '\u25CE' },
|
||||
{ id: 'documentation', name: 'Documentation', icon: '\u25A1' },
|
||||
{ id: 'ai-ml', name: 'AI/ML', icon: '\u25CE' },
|
||||
];
|
||||
|
||||
const MATRIX: Record<string, Record<string, Support>> = {
|
||||
'security': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'partial', 'antigravity': 'partial',
|
||||
},
|
||||
'testing': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
|
||||
},
|
||||
'react-frontend': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'partial', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'none',
|
||||
},
|
||||
'backend': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
|
||||
},
|
||||
'devops': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
|
||||
'kilo': 'partial', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
|
||||
'amp': 'full', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
|
||||
},
|
||||
'python': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
|
||||
},
|
||||
'go': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
|
||||
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
|
||||
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
|
||||
},
|
||||
'typescript': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
|
||||
},
|
||||
'database': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
|
||||
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
|
||||
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
|
||||
},
|
||||
'performance': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
|
||||
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
|
||||
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
|
||||
},
|
||||
'documentation': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
|
||||
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
|
||||
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
|
||||
},
|
||||
'ai-ml': {
|
||||
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
|
||||
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
|
||||
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
|
||||
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
|
||||
},
|
||||
};
|
||||
|
||||
const SUPPORT_CONFIG: Record<Support, { color: string; bg: string; label: string }> = {
|
||||
full: { color: 'text-green-400', bg: 'bg-green-400/10', label: 'Full' },
|
||||
partial: { color: 'text-yellow-400', bg: 'bg-yellow-400/10', label: 'Partial' },
|
||||
none: { color: 'text-red-400', bg: 'bg-red-400/10', label: 'None' },
|
||||
};
|
||||
|
||||
const SUPPORT_SCORE: Record<Support, number> = { full: 2, partial: 1, none: 0 };
|
||||
|
||||
function SupportCell({ support }: { support: Support }): React.ReactElement {
|
||||
const config = SUPPORT_CONFIG[support];
|
||||
return (
|
||||
<td className="px-1 py-2 text-center">
|
||||
<div className={`inline-flex items-center justify-center w-5 h-5 rounded-full ${config.bg}`}>
|
||||
<span className={`text-[10px] font-bold ${config.color}`}>
|
||||
{support === 'full' ? '\u2713' : support === 'partial' ? '\u25CB' : '\u2715'}
|
||||
</span>
|
||||
</div>
|
||||
</td>
|
||||
);
|
||||
}
|
||||
|
||||
function getAgentScore(agentId: string): number {
|
||||
return Object.values(MATRIX).reduce((sum, row) => sum + SUPPORT_SCORE[row[agentId] || 'none'], 0);
|
||||
}
|
||||
|
||||
function getMaxScore(): number {
|
||||
return CATEGORIES.length * 2;
|
||||
}
|
||||
|
||||
export function CompatibilityMatrix(): React.ReactElement {
|
||||
const [filter, setFilter] = useState('');
|
||||
const [groupFilter, setGroupFilter] = useState<string | null>(null);
|
||||
|
||||
const groups = useMemo(() => {
|
||||
const seen = new Set<string>();
|
||||
return AGENTS.reduce<string[]>((acc, a) => {
|
||||
if (!seen.has(a.group)) {
|
||||
seen.add(a.group);
|
||||
acc.push(a.group);
|
||||
}
|
||||
return acc;
|
||||
}, []);
|
||||
}, []);
|
||||
|
||||
const { filteredAgents, filteredCategories } = useMemo(() => {
|
||||
let agents = AGENTS;
|
||||
if (groupFilter) {
|
||||
agents = agents.filter(a => a.group === groupFilter);
|
||||
}
|
||||
|
||||
if (!filter.trim()) {
|
||||
return { filteredAgents: agents, filteredCategories: CATEGORIES };
|
||||
}
|
||||
|
||||
const q = filter.toLowerCase();
|
||||
|
||||
const matchedAgents = agents.filter(a =>
|
||||
a.name.toLowerCase().includes(q) || a.id.toLowerCase().includes(q)
|
||||
);
|
||||
const matchedCategories = CATEGORIES.filter(c =>
|
||||
c.name.toLowerCase().includes(q) || c.id.toLowerCase().includes(q)
|
||||
);
|
||||
|
||||
return {
|
||||
filteredAgents: matchedAgents.length > 0 ? matchedAgents : (matchedCategories.length > 0 ? agents : []),
|
||||
filteredCategories: matchedCategories.length > 0 ? matchedCategories : (matchedAgents.length > 0 ? CATEGORIES : []),
|
||||
};
|
||||
}, [filter, groupFilter]);
|
||||
|
||||
const maxScore = getMaxScore();
|
||||
|
||||
return (
|
||||
<section className="py-12 border-b border-zinc-800" style={{ backgroundColor: '#09090b' }}>
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
<div className="flex flex-col sm:flex-row sm:items-center justify-between gap-2 mb-6">
|
||||
<div>
|
||||
<h2 className="text-lg sm:text-xl font-bold text-white mb-1 font-mono">Compatibility Matrix</h2>
|
||||
<p className="text-zinc-500 font-mono text-[10px] sm:text-xs">
|
||||
Skill support across 16 agents and 12 categories.
|
||||
</p>
|
||||
</div>
|
||||
<div className="flex items-center gap-2">
|
||||
<span className="w-2 h-2 bg-green-500 rounded-full"></span>
|
||||
<span className="text-[10px] sm:text-xs font-mono text-zinc-500">Updated Feb 2026</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="flex flex-col sm:flex-row gap-2 sm:gap-3 mb-6">
|
||||
<div className="relative flex-1">
|
||||
<svg className="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-zinc-600" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
|
||||
</svg>
|
||||
<input
|
||||
type="text"
|
||||
value={filter}
|
||||
onChange={(e) => setFilter(e.target.value)}
|
||||
placeholder="Filter agents or categories..."
|
||||
className="w-full bg-black border border-zinc-800 text-zinc-300 placeholder-zinc-700 font-mono text-xs px-8 py-2 focus:outline-none focus:border-zinc-600 transition-colors"
|
||||
/>
|
||||
{filter && (
|
||||
<button
|
||||
onClick={() => setFilter('')}
|
||||
className="absolute right-2.5 top-1/2 -translate-y-1/2 text-zinc-600 hover:text-zinc-400 transition-colors"
|
||||
>
|
||||
<svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
|
||||
</svg>
|
||||
</button>
|
||||
)}
|
||||
</div>
|
||||
<div className="flex gap-1.5">
|
||||
<button
|
||||
onClick={() => setGroupFilter(null)}
|
||||
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
|
||||
groupFilter === null
|
||||
? 'bg-white text-black'
|
||||
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
|
||||
}`}
|
||||
>
|
||||
All
|
||||
</button>
|
||||
{groups.map(g => (
|
||||
<button
|
||||
key={g}
|
||||
onClick={() => setGroupFilter(groupFilter === g ? null : g)}
|
||||
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
|
||||
groupFilter === g
|
||||
? 'bg-white text-black'
|
||||
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
|
||||
}`}
|
||||
>
|
||||
{g}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="flex items-center gap-4 mb-4">
|
||||
{Object.entries(SUPPORT_CONFIG).map(([key, config]) => (
|
||||
<div key={key} className="flex items-center gap-1.5">
|
||||
<div className={`w-3 h-3 rounded-full ${config.bg} flex items-center justify-center`}>
|
||||
<span className={`text-[8px] font-bold ${config.color}`}>
|
||||
{key === 'full' ? '\u2713' : key === 'partial' ? '\u25CB' : '\u2715'}
|
||||
</span>
|
||||
</div>
|
||||
<span className="text-[10px] font-mono text-zinc-500">{config.label}</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
<div className="overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0">
|
||||
<div className="min-w-[700px]">
|
||||
<table className="w-full border-collapse font-mono text-[10px]">
|
||||
<thead>
|
||||
<tr className="border-b border-zinc-800">
|
||||
<th className="text-left text-zinc-500 uppercase tracking-wider py-2 pr-3 sticky left-0 bg-[#09090b] z-10 min-w-[120px]">
|
||||
Category
|
||||
</th>
|
||||
{filteredAgents.map(agent => (
|
||||
<th key={agent.id} className="px-1 py-2 text-center">
|
||||
<div className="flex flex-col items-center gap-0.5">
|
||||
<span className="text-sm">{agent.icon}</span>
|
||||
<span className="text-zinc-400 whitespace-nowrap max-w-[50px] truncate" title={agent.name}>
|
||||
{agent.name.length > 7 ? agent.name.slice(0, 7) : agent.name}
|
||||
</span>
|
||||
</div>
|
||||
</th>
|
||||
))}
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{filteredCategories.map(category => (
|
||||
<tr key={category.id} className="border-b border-zinc-800/50 hover:bg-zinc-900/50 transition-colors">
|
||||
<td className="py-2 pr-3 sticky left-0 bg-[#09090b] z-10">
|
||||
<div className="flex items-center gap-1.5">
|
||||
<span className="text-zinc-600">{category.icon}</span>
|
||||
<span className="text-zinc-300 whitespace-nowrap">{category.name}</span>
|
||||
</div>
|
||||
</td>
|
||||
{filteredAgents.map(agent => (
|
||||
<SupportCell
|
||||
key={agent.id}
|
||||
support={MATRIX[category.id]?.[agent.id] || 'none'}
|
||||
/>
|
||||
))}
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
<tfoot>
|
||||
<tr className="border-t border-zinc-700">
|
||||
<td className="py-3 pr-3 sticky left-0 bg-[#09090b] z-10">
|
||||
<span className="text-zinc-400 font-bold uppercase tracking-wider">Score</span>
|
||||
</td>
|
||||
{filteredAgents.map(agent => {
|
||||
const score = getAgentScore(agent.id);
|
||||
const pct = Math.round((score / maxScore) * 100);
|
||||
const color = pct >= 80 ? 'text-green-400' : pct >= 50 ? 'text-yellow-400' : 'text-red-400';
|
||||
return (
|
||||
<td key={agent.id} className="px-1 py-3 text-center">
|
||||
<div className={`font-bold text-xs ${color}`}>{pct}%</div>
|
||||
<div className="text-zinc-600 text-[9px]">{score}/{maxScore}</div>
|
||||
</td>
|
||||
);
|
||||
})}
|
||||
</tr>
|
||||
</tfoot>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{filteredAgents.length === 0 && (
|
||||
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
|
||||
No agents match your filter.
|
||||
</div>
|
||||
)}
|
||||
|
||||
{filteredCategories.length === 0 && filteredAgents.length > 0 && (
|
||||
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
|
||||
No categories match your filter.
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -9,7 +9,7 @@ interface Feature {
|
||||
const FEATURES: Feature[] = [
|
||||
{
|
||||
title: 'Smart Recommendations',
|
||||
description: 'AI analyzes your codebase and suggests perfect skills.',
|
||||
description: 'AI analyzes your codebase and recommends from 15,000+ skills.',
|
||||
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="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
|
||||
@@ -18,7 +18,7 @@ const FEATURES: Feature[] = [
|
||||
},
|
||||
{
|
||||
title: 'Auto Translation',
|
||||
description: 'Write once, deploy to 32 agents. Zero manual conversion.',
|
||||
description: 'The npm for agent skills. Write once, auto-translate to 32 formats.',
|
||||
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="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
|
||||
@@ -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 {
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import { Button } from './Button';
|
||||
|
||||
interface HeroProps {
|
||||
version: string;
|
||||
}
|
||||
|
||||
const ASCII_LOGO = `
|
||||
███████╗██╗ ██╗██╗██╗ ██╗ ██╗ ██╗██╗████████╗
|
||||
██╔════╝██║ ██╔╝██║██║ ██║ ██║ ██╔╝██║╚══██╔══╝
|
||||
@@ -16,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 = `
|
||||
@@ -55,7 +58,7 @@ const COPY_ICON = (
|
||||
</svg>
|
||||
);
|
||||
|
||||
export function Hero(): React.ReactElement {
|
||||
export function Hero({ version }: HeroProps): React.ReactElement {
|
||||
const [copied, setCopied] = useState(false);
|
||||
const [visibleLines, setVisibleLines] = useState(0);
|
||||
const [typingIndex, setTypingIndex] = useState(0);
|
||||
@@ -126,18 +129,18 @@ export function Hero(): React.ReactElement {
|
||||
<div className="animate-fade-in">
|
||||
<div className="inline-flex items-center space-x-2 border border-zinc-800 bg-zinc-900/50 px-2 py-0.5 mb-3 backdrop-blur-sm">
|
||||
<span className="flex h-1.5 w-1.5 bg-white rounded-full"></span>
|
||||
<span className="text-xs font-mono text-zinc-400">v1.8.0</span>
|
||||
<span className="text-xs font-mono text-zinc-400">v{version}</span>
|
||||
</div>
|
||||
|
||||
<h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold tracking-tight text-white mb-3 font-mono">
|
||||
Write Once.<br />
|
||||
<span className="text-zinc-500">Deploy to 32 Agents.</span>
|
||||
One Skill.<br />
|
||||
<span className="text-zinc-500">32 Agents. Zero Rewrites.</span>
|
||||
</h1>
|
||||
|
||||
<p className="text-sm text-zinc-400 mb-5 max-w-lg font-mono leading-relaxed">
|
||||
The universal skill platform for AI coding agents. Auto-generate instructions
|
||||
with Primer, persist learnings with Memory, distribute across Mesh networks.
|
||||
One CLI for Claude, Cursor, Windsurf, Copilot, and 28 more.
|
||||
The package manager for AI agent skills. Install from 15,000+ skills,
|
||||
auto-translate between formats, persist learnings with Memory.
|
||||
Works with Claude, Cursor, Windsurf, Copilot, and 28 more.
|
||||
</p>
|
||||
|
||||
<div className="flex flex-wrap items-center gap-3 mb-4">
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
import { useState, useEffect } from 'react';
|
||||
|
||||
interface Stats {
|
||||
version: string;
|
||||
downloads: string;
|
||||
stars: number;
|
||||
loading: boolean;
|
||||
}
|
||||
|
||||
const CACHE_KEY = 'skillkit_stats_cache';
|
||||
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
|
||||
|
||||
interface CachedStats {
|
||||
data: Omit<Stats, 'loading'>;
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
function formatDownloads(count: number): string {
|
||||
if (count >= 1000000) {
|
||||
return `${(count / 1000000).toFixed(1)}M`;
|
||||
}
|
||||
if (count >= 1000) {
|
||||
return `${(count / 1000).toFixed(1)}k`;
|
||||
}
|
||||
return count.toString();
|
||||
}
|
||||
|
||||
function getCachedStats(): CachedStats | null {
|
||||
try {
|
||||
const cached = localStorage.getItem(CACHE_KEY);
|
||||
if (cached) {
|
||||
const parsed: CachedStats = JSON.parse(cached);
|
||||
if (Date.now() - parsed.timestamp < CACHE_TTL) {
|
||||
return parsed;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Ignore localStorage errors
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function setCachedStats(data: Omit<Stats, 'loading'>): void {
|
||||
try {
|
||||
const cached: CachedStats = {
|
||||
data,
|
||||
timestamp: Date.now(),
|
||||
};
|
||||
localStorage.setItem(CACHE_KEY, JSON.stringify(cached));
|
||||
} catch {
|
||||
// Ignore localStorage errors
|
||||
}
|
||||
}
|
||||
|
||||
export function useStats(): Stats {
|
||||
const [stats, setStats] = useState<Stats>({
|
||||
version: '1.9.0',
|
||||
downloads: '2.4k',
|
||||
stars: 66,
|
||||
loading: true,
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
const cached = getCachedStats();
|
||||
if (cached) {
|
||||
setStats({ ...cached.data, loading: false });
|
||||
return;
|
||||
}
|
||||
|
||||
async function fetchStats(): Promise<void> {
|
||||
try {
|
||||
const [npmResponse, githubResponse] = await Promise.allSettled([
|
||||
fetch('https://api.npmjs.org/downloads/point/last-month/skillkit'),
|
||||
fetch('https://api.github.com/repos/rohitg00/skillkit'),
|
||||
]);
|
||||
|
||||
let downloads = '2.4k';
|
||||
let stars = 66;
|
||||
let version = '1.9.0';
|
||||
|
||||
if (npmResponse.status === 'fulfilled' && npmResponse.value.ok) {
|
||||
const npmData = await npmResponse.value.json();
|
||||
if (typeof npmData.downloads === 'number' && Number.isFinite(npmData.downloads)) {
|
||||
downloads = formatDownloads(npmData.downloads);
|
||||
}
|
||||
}
|
||||
|
||||
if (githubResponse.status === 'fulfilled' && githubResponse.value.ok) {
|
||||
const githubData = await githubResponse.value.json();
|
||||
if (typeof githubData.stargazers_count === 'number' && Number.isFinite(githubData.stargazers_count)) {
|
||||
stars = githubData.stargazers_count;
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
const registryResponse = await fetch('https://registry.npmjs.org/skillkit/latest');
|
||||
if (registryResponse.ok) {
|
||||
const registryData = await registryResponse.json();
|
||||
if (registryData.version) {
|
||||
version = registryData.version;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Use default version
|
||||
}
|
||||
|
||||
const newStats = { version, downloads, stars };
|
||||
setCachedStats(newStats);
|
||||
setStats({ ...newStats, loading: false });
|
||||
} catch {
|
||||
setStats((prev) => ({ ...prev, loading: false }));
|
||||
}
|
||||
}
|
||||
|
||||
fetchStats();
|
||||
}, []);
|
||||
|
||||
return stats;
|
||||
}
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "skillkit",
|
||||
"private": true,
|
||||
"version": "1.9.0",
|
||||
"version": "1.12.0",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
|
||||
@@ -0,0 +1,354 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>SkillKit API</title>
|
||||
<meta name="description" content="SkillKit REST API — discover and retrieve 15,000+ AI agent skills on demand">
|
||||
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
|
||||
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
|
||||
body {
|
||||
background: #0a0a0a;
|
||||
color: #e4e4e7;
|
||||
font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
|
||||
}
|
||||
|
||||
.topbar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 50;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
height: 56px;
|
||||
padding: 0 24px;
|
||||
border-bottom: 1px solid #27272a;
|
||||
background: rgba(10, 10, 10, 0.95);
|
||||
backdrop-filter: blur(12px);
|
||||
}
|
||||
|
||||
.topbar-left {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.topbar-logo {
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
background: white;
|
||||
}
|
||||
|
||||
.topbar-title {
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-weight: 700;
|
||||
font-size: 14px;
|
||||
color: white;
|
||||
text-decoration: none;
|
||||
letter-spacing: -0.025em;
|
||||
}
|
||||
|
||||
.topbar-sep {
|
||||
color: #3f3f46;
|
||||
font-size: 18px;
|
||||
}
|
||||
|
||||
.topbar-subtitle {
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-size: 12px;
|
||||
color: #71717a;
|
||||
}
|
||||
|
||||
.topbar-links {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 16px;
|
||||
}
|
||||
|
||||
.topbar-links a {
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-size: 12px;
|
||||
color: #71717a;
|
||||
text-decoration: none;
|
||||
transition: color 0.2s;
|
||||
}
|
||||
|
||||
.topbar-links a:hover { color: white; }
|
||||
|
||||
.topbar-version {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
padding: 2px 8px;
|
||||
border: 1px solid #27272a;
|
||||
background: rgba(24, 24, 27, 0.5);
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-size: 11px;
|
||||
color: #a1a1aa;
|
||||
}
|
||||
|
||||
.topbar-version .dot {
|
||||
width: 6px;
|
||||
height: 6px;
|
||||
background: #22c55e;
|
||||
border-radius: 50%;
|
||||
}
|
||||
|
||||
#swagger-ui {
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 0 16px 64px;
|
||||
}
|
||||
|
||||
/* Dark theme overrides */
|
||||
.swagger-ui .topbar { display: none; }
|
||||
|
||||
.swagger-ui,
|
||||
.swagger-ui .wrapper { background: transparent; }
|
||||
|
||||
.swagger-ui .info { margin: 32px 0 16px; }
|
||||
|
||||
.swagger-ui .info .title {
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .info .description,
|
||||
.swagger-ui .info .description p {
|
||||
font-family: 'Inter', sans-serif;
|
||||
color: #a1a1aa;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.swagger-ui .info .description code {
|
||||
background: #18181b;
|
||||
border: 1px solid #27272a;
|
||||
padding: 2px 6px;
|
||||
border-radius: 3px;
|
||||
color: #e4e4e7;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.swagger-ui .info .description pre {
|
||||
background: #18181b;
|
||||
border: 1px solid #27272a;
|
||||
border-radius: 6px;
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
.swagger-ui .scheme-container {
|
||||
background: #18181b;
|
||||
border: 1px solid #27272a;
|
||||
box-shadow: none;
|
||||
padding: 12px 16px;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock-tag {
|
||||
color: white;
|
||||
border-bottom: 1px solid #27272a;
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock-tag small { color: #71717a; }
|
||||
|
||||
.swagger-ui .opblock {
|
||||
border-color: #27272a;
|
||||
background: #0f0f0f;
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-summary {
|
||||
border-bottom: 1px solid #27272a;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-summary-description {
|
||||
color: #a1a1aa;
|
||||
font-family: 'Inter', sans-serif;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-summary-path {
|
||||
color: white;
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-section-header {
|
||||
background: #18181b;
|
||||
border-bottom: 1px solid #27272a;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock .opblock-section-header h4 {
|
||||
color: #e4e4e7;
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock-body pre.microlight {
|
||||
background: #18181b;
|
||||
border: 1px solid #27272a;
|
||||
border-radius: 4px;
|
||||
color: #e4e4e7;
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.opblock-get {
|
||||
border-color: #27272a;
|
||||
background: rgba(34, 197, 94, 0.05);
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.opblock-get .opblock-summary-method {
|
||||
background: #166534;
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.opblock-post {
|
||||
border-color: #27272a;
|
||||
background: rgba(59, 130, 246, 0.05);
|
||||
}
|
||||
|
||||
.swagger-ui .opblock.opblock-post .opblock-summary-method {
|
||||
background: #1e40af;
|
||||
}
|
||||
|
||||
.swagger-ui .btn {
|
||||
border-color: #3f3f46;
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.swagger-ui .btn:hover {
|
||||
background: #27272a;
|
||||
}
|
||||
|
||||
.swagger-ui .btn.execute {
|
||||
background: white;
|
||||
color: black;
|
||||
border-color: white;
|
||||
}
|
||||
|
||||
.swagger-ui .btn.execute:hover {
|
||||
background: #e4e4e7;
|
||||
}
|
||||
|
||||
.swagger-ui table thead tr th,
|
||||
.swagger-ui table thead tr td,
|
||||
.swagger-ui .parameter__name,
|
||||
.swagger-ui .parameter__type {
|
||||
color: #a1a1aa;
|
||||
}
|
||||
|
||||
.swagger-ui .parameter__name.required span { color: #ef4444; }
|
||||
|
||||
.swagger-ui table tbody tr td {
|
||||
color: #e4e4e7;
|
||||
border-bottom: 1px solid #1c1c1e;
|
||||
}
|
||||
|
||||
.swagger-ui input[type=text],
|
||||
.swagger-ui textarea,
|
||||
.swagger-ui select {
|
||||
background: #18181b;
|
||||
border: 1px solid #3f3f46;
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.swagger-ui .model-box {
|
||||
background: #18181b;
|
||||
border: 1px solid #27272a;
|
||||
}
|
||||
|
||||
.swagger-ui .model { color: #a1a1aa; }
|
||||
.swagger-ui .model-title { color: white; }
|
||||
.swagger-ui .prop-type { color: #22c55e; }
|
||||
.swagger-ui .prop-format { color: #71717a; }
|
||||
|
||||
.swagger-ui section.models {
|
||||
border: 1px solid #27272a;
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.swagger-ui section.models h4 {
|
||||
color: white;
|
||||
border-bottom: 1px solid #27272a;
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
}
|
||||
|
||||
.swagger-ui section.models .model-container {
|
||||
border-bottom: 1px solid #27272a;
|
||||
background: transparent;
|
||||
}
|
||||
|
||||
.swagger-ui .response-col_status { color: #22c55e; font-family: 'JetBrains Mono', monospace; }
|
||||
.swagger-ui .response-col_description { color: #a1a1aa; }
|
||||
|
||||
.swagger-ui .responses-inner h4,
|
||||
.swagger-ui .responses-inner h5 {
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.swagger-ui .filter .operation-filter-input {
|
||||
background: #18181b;
|
||||
border: 1px solid #3f3f46;
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.swagger-ui .loading-container .loading::after {
|
||||
color: #71717a;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.topbar { padding: 0 16px; }
|
||||
.topbar-sep, .topbar-subtitle { display: none; }
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: light) {
|
||||
body { background: #0a0a0a; }
|
||||
}
|
||||
</style>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar">
|
||||
<div class="topbar-left">
|
||||
<a href="/" style="display:flex;align-items:center;gap:8px;text-decoration:none;">
|
||||
<div class="topbar-logo"></div>
|
||||
<span class="topbar-title">SKILLKIT</span>
|
||||
</a>
|
||||
<span class="topbar-sep">/</span>
|
||||
<span class="topbar-subtitle">API Reference</span>
|
||||
</div>
|
||||
<div class="topbar-links">
|
||||
<span class="topbar-version">
|
||||
<span class="dot"></span>
|
||||
v1.12.0
|
||||
</span>
|
||||
<a href="/">Home</a>
|
||||
<a href="/docs">Docs</a>
|
||||
<a href="https://github.com/rohitg00/skillkit" target="_blank" rel="noopener">GitHub</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="swagger-ui"></div>
|
||||
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
|
||||
<script>
|
||||
SwaggerUIBundle({
|
||||
url: '/openapi.json',
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
showExtensions: true,
|
||||
showCommonExtensions: true,
|
||||
defaultModelsExpandDepth: 2,
|
||||
defaultModelExpandDepth: 2,
|
||||
docExpansion: 'list',
|
||||
filter: true,
|
||||
tryItOutEnabled: true,
|
||||
persistAuthorization: true,
|
||||
displayRequestDuration: true,
|
||||
syntaxHighlight: { theme: 'monokai' },
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,368 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "SkillKit",
|
||||
"version": "1.12.0",
|
||||
"description": "Skills shouldn't require pre-installation. This API lets any agent, framework, or tool discover and retrieve skills on demand.\n\n15,000+ skills across 32 AI coding agents. Results ranked by a multi-signal scoring system (content 40pts, query match 30pts, popularity 15pts, references 15pts).\n\n## Quick Start\n\n```bash\nnpx skillkit serve\n```\n\nThe API is now running at http://localhost:3737\n\n## MCP Server\n\nFor agent-native discovery (Claude Desktop, Cursor):\n\n```json\n{\n \"mcpServers\": {\n \"skillkit\": { \"command\": \"npx\", \"args\": [\"@skillkit/mcp\"] }\n }\n}\n```\n\n## Python Client\n\n```bash\npip install skillkit-client\n```",
|
||||
"license": {
|
||||
"name": "Apache-2.0",
|
||||
"url": "https://opensource.org/licenses/Apache-2.0"
|
||||
},
|
||||
"contact": {
|
||||
"name": "SkillKit",
|
||||
"url": "https://github.com/rohitg00/skillkit"
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "http://localhost:3737",
|
||||
"description": "Local development (skillkit serve)"
|
||||
}
|
||||
],
|
||||
"tags": [
|
||||
{ "name": "Search", "description": "Skill search and filtering" },
|
||||
{ "name": "Skills", "description": "Individual skill retrieval" },
|
||||
{ "name": "Discovery", "description": "Trending skills and categories" },
|
||||
{ "name": "System", "description": "Health checks and diagnostics" }
|
||||
],
|
||||
"paths": {
|
||||
"/search": {
|
||||
"get": {
|
||||
"summary": "Search skills",
|
||||
"description": "Find skills matching your query. Results are ranked by relevance: content availability (40pts), query match (30pts), popularity (15pts), and references (15pts). Best matches come first.",
|
||||
"operationId": "searchSkillsGet",
|
||||
"tags": ["Search"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "q",
|
||||
"in": "query",
|
||||
"required": true,
|
||||
"schema": { "type": "string", "minLength": 1, "maxLength": 200 },
|
||||
"description": "Search query (e.g., 'react performance', 'authentication')",
|
||||
"example": "react hooks"
|
||||
},
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 },
|
||||
"description": "Maximum results to return"
|
||||
},
|
||||
{
|
||||
"name": "include_content",
|
||||
"in": "query",
|
||||
"schema": { "type": "boolean", "default": false },
|
||||
"description": "Include full SKILL.md content in response"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Search results ranked by relevance",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/SearchResponse" },
|
||||
"example": {
|
||||
"skills": [
|
||||
{
|
||||
"name": "react-performance",
|
||||
"description": "React app performance optimization patterns",
|
||||
"source": "anthropics/skills",
|
||||
"tags": ["react", "performance"],
|
||||
"category": "frontend"
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"query": "react hooks",
|
||||
"limit": 20
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Missing query parameter",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
|
||||
},
|
||||
"429": {
|
||||
"description": "Rate limit exceeded (60 req/min per IP)",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitResponse" } } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"summary": "Search skills with filters",
|
||||
"description": "Search with filters. Narrow results by tags, category, or source repository.",
|
||||
"operationId": "searchSkillsPost",
|
||||
"tags": ["Search"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["query"],
|
||||
"properties": {
|
||||
"query": { "type": "string", "description": "Search query" },
|
||||
"limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 },
|
||||
"include_content": { "type": "boolean", "default": false },
|
||||
"filters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tags" },
|
||||
"category": { "type": "string", "description": "Filter by category" },
|
||||
"source": { "type": "string", "description": "Filter by source repository" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"example": {
|
||||
"query": "authentication",
|
||||
"limit": 10,
|
||||
"filters": { "tags": ["security"], "category": "backend" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Filtered search results",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
|
||||
},
|
||||
"400": {
|
||||
"description": "Invalid request body",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/skills/{owner}/{repo}/{id}": {
|
||||
"get": {
|
||||
"summary": "Get skill by ID",
|
||||
"description": "Get full details of a specific skill by its source repository and name.",
|
||||
"operationId": "getSkill",
|
||||
"tags": ["Skills"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "owner",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string" },
|
||||
"description": "Repository owner",
|
||||
"example": "anthropics"
|
||||
},
|
||||
{
|
||||
"name": "repo",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string" },
|
||||
"description": "Repository name",
|
||||
"example": "skills"
|
||||
},
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": { "type": "string" },
|
||||
"description": "Skill name",
|
||||
"example": "pdf-processing"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Skill details",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" } } }
|
||||
},
|
||||
"404": {
|
||||
"description": "Skill not found",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/trending": {
|
||||
"get": {
|
||||
"summary": "Trending skills",
|
||||
"description": "The most popular skills right now, ranked by relevance score across all sources.",
|
||||
"operationId": "getTrending",
|
||||
"tags": ["Discovery"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 },
|
||||
"description": "Maximum results"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Trending skills list",
|
||||
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendingResponse" } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/categories": {
|
||||
"get": {
|
||||
"summary": "Skill categories",
|
||||
"description": "Browse all skill categories with counts. See what's available before searching.",
|
||||
"operationId": "getCategories",
|
||||
"tags": ["Discovery"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Category list with counts",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/CategoriesResponse" },
|
||||
"example": {
|
||||
"categories": [
|
||||
{ "name": "react", "count": 156 },
|
||||
{ "name": "typescript", "count": 134 },
|
||||
{ "name": "testing", "count": 89 }
|
||||
],
|
||||
"total": 89
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/health": {
|
||||
"get": {
|
||||
"summary": "Health check",
|
||||
"description": "Check if the server is running. Returns version, skill count, and uptime.",
|
||||
"operationId": "getHealth",
|
||||
"tags": ["System"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Server health",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/HealthResponse" },
|
||||
"example": {
|
||||
"status": "ok",
|
||||
"version": "1.12.0",
|
||||
"skillCount": 15062,
|
||||
"uptime": 3600
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/cache/stats": {
|
||||
"get": {
|
||||
"summary": "Cache statistics",
|
||||
"description": "See how the cache is performing. Shows hit/miss rates and current size.",
|
||||
"operationId": "getCacheStats",
|
||||
"tags": ["System"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Cache statistics",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { "$ref": "#/components/schemas/CacheStatsResponse" },
|
||||
"example": {
|
||||
"hits": 142,
|
||||
"misses": 38,
|
||||
"size": 45,
|
||||
"maxSize": 500,
|
||||
"hitRate": 0.789
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"Skill": {
|
||||
"type": "object",
|
||||
"description": "An AI agent skill from the marketplace",
|
||||
"properties": {
|
||||
"name": { "type": "string", "description": "Skill name" },
|
||||
"description": { "type": "string", "description": "What this skill does" },
|
||||
"source": { "type": "string", "description": "Source repository (owner/repo)" },
|
||||
"repo": { "type": "string", "description": "Full repository URL" },
|
||||
"tags": { "type": "array", "items": { "type": "string" }, "description": "Skill tags" },
|
||||
"category": { "type": "string", "description": "Primary category" },
|
||||
"content": { "type": "string", "description": "Full SKILL.md content (when include_content=true)" },
|
||||
"stars": { "type": "integer", "description": "GitHub stars" },
|
||||
"installs": { "type": "integer", "description": "Install count" }
|
||||
},
|
||||
"required": ["name", "source"]
|
||||
},
|
||||
"SearchResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } },
|
||||
"total": { "type": "integer", "description": "Total matching skills (before limit)" },
|
||||
"query": { "type": "string", "description": "Original search query" },
|
||||
"limit": { "type": "integer", "description": "Applied result limit" }
|
||||
},
|
||||
"required": ["skills", "total", "query", "limit"]
|
||||
},
|
||||
"TrendingResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } },
|
||||
"limit": { "type": "integer" }
|
||||
},
|
||||
"required": ["skills", "limit"]
|
||||
},
|
||||
"CategoriesResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryCount" } },
|
||||
"total": { "type": "integer" }
|
||||
},
|
||||
"required": ["categories", "total"]
|
||||
},
|
||||
"CategoryCount": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"count": { "type": "integer" }
|
||||
},
|
||||
"required": ["name", "count"]
|
||||
},
|
||||
"HealthResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": { "type": "string", "enum": ["ok"] },
|
||||
"version": { "type": "string" },
|
||||
"skillCount": { "type": "integer" },
|
||||
"uptime": { "type": "number", "description": "Seconds since server start" }
|
||||
},
|
||||
"required": ["status", "version", "skillCount", "uptime"]
|
||||
},
|
||||
"CacheStatsResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"hits": { "type": "integer" },
|
||||
"misses": { "type": "integer" },
|
||||
"size": { "type": "integer", "description": "Current cached entries" },
|
||||
"maxSize": { "type": "integer", "description": "Maximum cache capacity" },
|
||||
"hitRate": { "type": "number", "description": "Hit rate (0.0 - 1.0)" }
|
||||
},
|
||||
"required": ["hits", "misses", "size", "maxSize", "hitRate"]
|
||||
},
|
||||
"ErrorResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error": { "type": "string", "description": "Error message" }
|
||||
},
|
||||
"required": ["error"]
|
||||
},
|
||||
"RateLimitResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error": { "type": "string" },
|
||||
"retryAfter": { "type": "integer", "description": "Seconds until rate limit window resets" }
|
||||
},
|
||||
"required": ["error", "retryAfter"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -4,6 +4,10 @@
|
||||
"installCommand": "npm install",
|
||||
"framework": "vite",
|
||||
"rewrites": [
|
||||
{
|
||||
"source": "/api",
|
||||
"destination": "/api.html"
|
||||
},
|
||||
{
|
||||
"source": "/_next/:path*",
|
||||
"destination": "https://skillkit-docs.vercel.app/_next/:path*"
|
||||
|
||||
+19
-2
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"$schema": "./schema.json",
|
||||
"version": 1,
|
||||
"updatedAt": "2026-01-26",
|
||||
"totalSkills": 15064,
|
||||
"updatedAt": "2026-02-02",
|
||||
"totalSkills": 15065,
|
||||
"curatedCollections": 31,
|
||||
"skills": [
|
||||
{
|
||||
@@ -33112,6 +33112,23 @@
|
||||
"k8s"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "rohitg00/beautiful-mermaid/beautiful-mermaid",
|
||||
"name": "Beautiful Mermaid",
|
||||
"description": "Render Mermaid diagrams as beautiful SVGs or ASCII art. 5 diagram types, 15 themes, Shiki integration, zero DOM dependencies.",
|
||||
"source": "rohitg00/beautiful-mermaid",
|
||||
"tags": [
|
||||
"mermaid",
|
||||
"diagrams",
|
||||
"visualization",
|
||||
"flowchart",
|
||||
"sequence",
|
||||
"uml",
|
||||
"ascii",
|
||||
"svg",
|
||||
"themes"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "itsmostafa/aws-agent-skills/cognito",
|
||||
"name": "Cognito",
|
||||
|
||||
Generated
+2
-2
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "skillkit-monorepo",
|
||||
"version": "1.7.10",
|
||||
"version": "1.13.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "skillkit-monorepo",
|
||||
"version": "1.7.10",
|
||||
"version": "1.13.0",
|
||||
"license": "Apache-2.0",
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
|
||||
+9
-3
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"name": "skillkit-monorepo",
|
||||
"version": "1.9.0",
|
||||
"version": "1.13.0",
|
||||
"private": true,
|
||||
"description": "Universal skills loader for AI coding agents - Monorepo",
|
||||
"description": "The package manager for AI agent skills — install, translate, share across 32 coding agents",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "turbo run build",
|
||||
@@ -31,7 +31,13 @@
|
||||
"coding-assistant",
|
||||
"skill-loader",
|
||||
"cli",
|
||||
"monorepo"
|
||||
"monorepo",
|
||||
"skill-md",
|
||||
"package-manager",
|
||||
"plugin",
|
||||
"workflow",
|
||||
"automation",
|
||||
"SKILL.md"
|
||||
],
|
||||
"author": "Rohit Ghumare",
|
||||
"license": "Apache-2.0",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/agents",
|
||||
"version": "1.9.0",
|
||||
"version": "1.13.0",
|
||||
"description": "Agent adapters for SkillKit - supports 32 AI coding agents",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
{
|
||||
"name": "@skillkit/api",
|
||||
"version": "1.13.0",
|
||||
"description": "REST API server for SkillKit skill discovery",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"bin": {
|
||||
"skillkit-api": "./dist/index.js"
|
||||
},
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts"
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "tsup",
|
||||
"dev": "tsup --watch",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run",
|
||||
"start": "node dist/index.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"hono": "^4.0.0",
|
||||
"@hono/node-server": "^1.0.0",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"zod": "^3.24.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
"tsup": "^8.3.5",
|
||||
"typescript": "^5.7.2",
|
||||
"vitest": "^2.1.8"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"license": "Apache-2.0",
|
||||
"keywords": [
|
||||
"skillkit",
|
||||
"api",
|
||||
"rest",
|
||||
"skills",
|
||||
"discovery",
|
||||
"ai",
|
||||
"agents"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
describe('Health Routes', () => {
|
||||
const { app } = createApp({ skills: [{ name: 'test', source: 'a/b' }], rateLimitMax: 1000 });
|
||||
|
||||
it('GET /health returns status ok', async () => {
|
||||
const res = await app.request('/health');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.status).toBe('ok');
|
||||
expect(body.skillCount).toBe(1);
|
||||
expect(typeof body.uptime).toBe('number');
|
||||
expect(body.version).toBeDefined();
|
||||
});
|
||||
|
||||
it('GET /cache/stats returns cache statistics', async () => {
|
||||
const res = await app.request('/cache/stats');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(typeof body.hits).toBe('number');
|
||||
expect(typeof body.misses).toBe('number');
|
||||
expect(typeof body.size).toBe('number');
|
||||
expect(typeof body.maxSize).toBe('number');
|
||||
expect(typeof body.hitRate).toBe('number');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,56 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const testSkills = [
|
||||
{ name: 'react-perf', description: 'React performance tips', source: 'owner/repo', tags: ['react', 'performance'] },
|
||||
{ name: 'testing-guide', description: 'Unit testing guide', source: 'owner/repo2', tags: ['testing'] },
|
||||
{ name: 'nextjs-auth', description: 'Next.js authentication', source: 'other/repo', tags: ['nextjs', 'auth'], category: 'framework' },
|
||||
];
|
||||
|
||||
describe('Search Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /search returns results for query', async () => {
|
||||
const res = await app.request('/search?q=react');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.query).toBe('react');
|
||||
expect(body.skills.length).toBeGreaterThan(0);
|
||||
expect(body.total).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('GET /search returns 400 without query', async () => {
|
||||
const res = await app.request('/search');
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it('GET /search respects limit parameter', async () => {
|
||||
const res = await app.request('/search?q=test&limit=1');
|
||||
const body = await res.json();
|
||||
expect(body.skills.length).toBeLessThanOrEqual(1);
|
||||
expect(body.limit).toBe(1);
|
||||
});
|
||||
|
||||
it('POST /search with filters', async () => {
|
||||
const res = await app.request('/search', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
query: 'auth',
|
||||
filters: { tags: ['nextjs'] },
|
||||
}),
|
||||
});
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.skills.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('POST /search returns 400 without query', async () => {
|
||||
const res = await app.request('/search', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({}),
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,53 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { createApp } from '../server.js';
|
||||
|
||||
const testSkills = [
|
||||
{ name: 'my-skill', description: 'A test skill', source: 'owner/repo' },
|
||||
];
|
||||
|
||||
describe('Skill Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /skills/:source/:id returns a skill', async () => {
|
||||
const res = await app.request('/skills/owner/repo/my-skill');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.name).toBe('my-skill');
|
||||
expect(body.source).toBe('owner/repo');
|
||||
});
|
||||
|
||||
it('GET /skills/:owner/:repo/:id returns 404 for missing skill', async () => {
|
||||
const res = await app.request('/skills/owner/repo/nonexistent');
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Trending Routes', () => {
|
||||
const { app } = createApp({ skills: testSkills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /trending returns skills', async () => {
|
||||
const res = await app.request('/trending');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.skills).toBeInstanceOf(Array);
|
||||
expect(body.limit).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Category Routes', () => {
|
||||
const skills = [
|
||||
{ name: 'a', source: 'x/y', tags: ['react', 'ui'] },
|
||||
{ name: 'b', source: 'x/z', tags: ['react'], category: 'framework' },
|
||||
];
|
||||
const { app } = createApp({ skills, rateLimitMax: 1000 });
|
||||
|
||||
it('GET /categories returns tag counts', async () => {
|
||||
const res = await app.request('/categories');
|
||||
expect(res.status).toBe(200);
|
||||
const body = await res.json();
|
||||
expect(body.categories).toBeInstanceOf(Array);
|
||||
expect(body.total).toBeGreaterThan(0);
|
||||
const react = body.categories.find((c: { name: string }) => c.name === 'react');
|
||||
expect(react?.count).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,11 @@
|
||||
export { createApp, startServer } from './server.js';
|
||||
export type { ServerOptions } from './server.js';
|
||||
export type {
|
||||
ApiSkill,
|
||||
SearchResponse,
|
||||
HealthResponse,
|
||||
CacheStatsResponse,
|
||||
TrendingResponse,
|
||||
CategoriesResponse,
|
||||
CategoryCount,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,43 @@
|
||||
import type { Context, Next } from 'hono';
|
||||
|
||||
interface RateLimitEntry {
|
||||
count: number;
|
||||
resetAt: number;
|
||||
}
|
||||
|
||||
export function rateLimiter(maxRequests = 60, windowMs = 60_000) {
|
||||
const windows = new Map<string, RateLimitEntry>();
|
||||
|
||||
setInterval(() => {
|
||||
const now = Date.now();
|
||||
for (const [key, entry] of windows) {
|
||||
if (now > entry.resetAt) {
|
||||
windows.delete(key);
|
||||
}
|
||||
}
|
||||
}, windowMs).unref();
|
||||
|
||||
return async (c: Context, next: Next): Promise<Response | void> => {
|
||||
const forwardedFor = c.req.header('x-forwarded-for');
|
||||
const ip = (forwardedFor?.split(',')[0]?.trim()) || c.req.header('x-real-ip') || 'unknown';
|
||||
const now = Date.now();
|
||||
|
||||
let entry = windows.get(ip);
|
||||
if (!entry || now > entry.resetAt) {
|
||||
entry = { count: 0, resetAt: now + windowMs };
|
||||
windows.set(ip, entry);
|
||||
}
|
||||
|
||||
entry.count++;
|
||||
|
||||
c.header('X-RateLimit-Limit', String(maxRequests));
|
||||
c.header('X-RateLimit-Remaining', String(Math.max(0, maxRequests - entry.count)));
|
||||
c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
|
||||
|
||||
if (entry.count > maxRequests) {
|
||||
return c.json({ error: 'Too many requests', retryAfter: Math.ceil((entry.resetAt - now) / 1000) }, 429);
|
||||
}
|
||||
|
||||
await next();
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, CategoriesResponse } from '../types.js';
|
||||
|
||||
export function categoryRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/categories', (c) => {
|
||||
const tagCounts = new Map<string, number>();
|
||||
|
||||
for (const skill of skills) {
|
||||
if (skill.tags) {
|
||||
for (const tag of skill.tags) {
|
||||
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
|
||||
}
|
||||
}
|
||||
if (skill.category) {
|
||||
const key = `category:${skill.category}`;
|
||||
tagCounts.set(key, (tagCounts.get(key) || 0) + 1);
|
||||
}
|
||||
}
|
||||
|
||||
const categories = Array.from(tagCounts.entries())
|
||||
.map(([name, count]) => ({ name, count }))
|
||||
.sort((a, b) => b.count - a.count);
|
||||
|
||||
const response: CategoriesResponse = {
|
||||
categories,
|
||||
total: categories.length,
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,294 @@
|
||||
import { Hono } from 'hono';
|
||||
|
||||
const OPENAPI_SPEC = {
|
||||
openapi: '3.1.0',
|
||||
info: {
|
||||
title: 'SkillKit',
|
||||
version: '1.12.0',
|
||||
description: 'Skill Discovery API for AI coding agents. Search, browse, and retrieve skills from the SkillKit marketplace (15,000+ skills across 32 agents).',
|
||||
license: { name: 'Apache-2.0', url: 'https://opensource.org/licenses/Apache-2.0' },
|
||||
contact: { name: 'SkillKit', url: 'https://github.com/rohitg00/skillkit' },
|
||||
},
|
||||
servers: [
|
||||
{ url: 'http://localhost:3737', description: 'Local development' },
|
||||
],
|
||||
paths: {
|
||||
'/search': {
|
||||
get: {
|
||||
summary: 'Search skills',
|
||||
description: 'Locate agent skills matching a query, ranked by multi-signal relevance (content, query match, popularity, references).',
|
||||
operationId: 'searchSkillsGet',
|
||||
tags: ['Search'],
|
||||
parameters: [
|
||||
{ name: 'q', in: 'query', required: true, schema: { type: 'string', minLength: 1, maxLength: 200 }, description: 'Search query' },
|
||||
{ name: 'limit', in: 'query', schema: { type: 'integer', default: 20, minimum: 1, maximum: 100 }, description: 'Max results to return' },
|
||||
{ name: 'include_content', in: 'query', schema: { type: 'boolean', default: false }, description: 'Include full skill content in response' },
|
||||
],
|
||||
responses: {
|
||||
'200': { description: 'Search results', content: { 'application/json': { schema: { $ref: '#/components/schemas/SearchResponse' } } } },
|
||||
'400': { description: 'Missing query parameter', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } } },
|
||||
'429': { description: 'Rate limit exceeded', content: { 'application/json': { schema: { $ref: '#/components/schemas/RateLimitResponse' } } } },
|
||||
},
|
||||
},
|
||||
post: {
|
||||
summary: 'Search skills with filters',
|
||||
description: 'Search with advanced filters including tags, category, and source.',
|
||||
operationId: 'searchSkillsPost',
|
||||
tags: ['Search'],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['query'],
|
||||
properties: {
|
||||
query: { type: 'string', description: 'Search query' },
|
||||
limit: { type: 'integer', default: 20, minimum: 1, maximum: 100, description: 'Max results' },
|
||||
include_content: { type: 'boolean', default: false, description: 'Include full content' },
|
||||
filters: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
|
||||
category: { type: 'string', description: 'Filter by category' },
|
||||
source: { type: 'string', description: 'Filter by source repo' },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
'200': { description: 'Filtered search results', content: { 'application/json': { schema: { $ref: '#/components/schemas/SearchResponse' } } } },
|
||||
'400': { description: 'Invalid request', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
'/skills/{owner}/{repo}/{id}': {
|
||||
get: {
|
||||
summary: 'Get skill by ID',
|
||||
description: 'Retrieve a specific skill by its source repository and name.',
|
||||
operationId: 'getSkill',
|
||||
tags: ['Skills'],
|
||||
parameters: [
|
||||
{ name: 'owner', in: 'path', required: true, schema: { type: 'string' }, description: 'Repository owner' },
|
||||
{ name: 'repo', in: 'path', required: true, schema: { type: 'string' }, description: 'Repository name' },
|
||||
{ name: 'id', in: 'path', required: true, schema: { type: 'string' }, description: 'Skill name' },
|
||||
],
|
||||
responses: {
|
||||
'200': { description: 'Skill details', content: { 'application/json': { schema: { $ref: '#/components/schemas/Skill' } } } },
|
||||
'404': { description: 'Skill not found', content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
'/trending': {
|
||||
get: {
|
||||
summary: 'Trending skills',
|
||||
description: 'Get top skills ranked by multi-signal relevance score (content availability, popularity, references).',
|
||||
operationId: 'getTrending',
|
||||
tags: ['Discovery'],
|
||||
parameters: [
|
||||
{ name: 'limit', in: 'query', schema: { type: 'integer', default: 20, minimum: 1, maximum: 100 }, description: 'Max results' },
|
||||
],
|
||||
responses: {
|
||||
'200': { description: 'Trending skills', content: { 'application/json': { schema: { $ref: '#/components/schemas/TrendingResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
'/categories': {
|
||||
get: {
|
||||
summary: 'Skill categories',
|
||||
description: 'List all skill categories and tags with their counts, sorted by popularity.',
|
||||
operationId: 'getCategories',
|
||||
tags: ['Discovery'],
|
||||
responses: {
|
||||
'200': { description: 'Category list', content: { 'application/json': { schema: { $ref: '#/components/schemas/CategoriesResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
'/health': {
|
||||
get: {
|
||||
summary: 'Health check',
|
||||
description: 'Server health status including version, skill count, and uptime.',
|
||||
operationId: 'getHealth',
|
||||
tags: ['System'],
|
||||
responses: {
|
||||
'200': { description: 'Server health', content: { 'application/json': { schema: { $ref: '#/components/schemas/HealthResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
'/cache/stats': {
|
||||
get: {
|
||||
summary: 'Cache statistics',
|
||||
description: 'Cache hit/miss rates and current size.',
|
||||
operationId: 'getCacheStats',
|
||||
tags: ['System'],
|
||||
responses: {
|
||||
'200': { description: 'Cache stats', content: { 'application/json': { schema: { $ref: '#/components/schemas/CacheStatsResponse' } } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
components: {
|
||||
schemas: {
|
||||
Skill: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
name: { type: 'string', description: 'Skill name' },
|
||||
description: { type: 'string', description: 'Skill description' },
|
||||
source: { type: 'string', description: 'Source repository (owner/repo)' },
|
||||
repo: { type: 'string', description: 'Repository URL' },
|
||||
tags: { type: 'array', items: { type: 'string' }, description: 'Skill tags' },
|
||||
category: { type: 'string', description: 'Skill category' },
|
||||
content: { type: 'string', description: 'Full SKILL.md content (when requested)' },
|
||||
stars: { type: 'integer', description: 'GitHub stars' },
|
||||
installs: { type: 'integer', description: 'Install count' },
|
||||
},
|
||||
required: ['name', 'source'],
|
||||
},
|
||||
SearchResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
skills: { type: 'array', items: { $ref: '#/components/schemas/Skill' } },
|
||||
total: { type: 'integer', description: 'Total matching skills' },
|
||||
query: { type: 'string', description: 'Original query' },
|
||||
limit: { type: 'integer', description: 'Applied limit' },
|
||||
},
|
||||
required: ['skills', 'total', 'query', 'limit'],
|
||||
},
|
||||
TrendingResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
skills: { type: 'array', items: { $ref: '#/components/schemas/Skill' } },
|
||||
limit: { type: 'integer' },
|
||||
},
|
||||
required: ['skills', 'limit'],
|
||||
},
|
||||
CategoriesResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
categories: { type: 'array', items: { $ref: '#/components/schemas/CategoryCount' } },
|
||||
total: { type: 'integer' },
|
||||
},
|
||||
required: ['categories', 'total'],
|
||||
},
|
||||
CategoryCount: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
name: { type: 'string' },
|
||||
count: { type: 'integer' },
|
||||
},
|
||||
required: ['name', 'count'],
|
||||
},
|
||||
HealthResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
status: { type: 'string', enum: ['ok'] },
|
||||
version: { type: 'string' },
|
||||
skillCount: { type: 'integer' },
|
||||
uptime: { type: 'number', description: 'Uptime in seconds' },
|
||||
},
|
||||
required: ['status', 'version', 'skillCount', 'uptime'],
|
||||
},
|
||||
CacheStatsResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
hits: { type: 'integer' },
|
||||
misses: { type: 'integer' },
|
||||
size: { type: 'integer' },
|
||||
maxSize: { type: 'integer' },
|
||||
hitRate: { type: 'number' },
|
||||
},
|
||||
required: ['hits', 'misses', 'size', 'maxSize', 'hitRate'],
|
||||
},
|
||||
ErrorResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
error: { type: 'string' },
|
||||
},
|
||||
required: ['error'],
|
||||
},
|
||||
RateLimitResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
error: { type: 'string' },
|
||||
retryAfter: { type: 'integer', description: 'Seconds until rate limit resets' },
|
||||
},
|
||||
required: ['error', 'retryAfter'],
|
||||
},
|
||||
},
|
||||
},
|
||||
tags: [
|
||||
{ name: 'Search', description: 'Skill search and filtering' },
|
||||
{ name: 'Skills', description: 'Individual skill retrieval' },
|
||||
{ name: 'Discovery', description: 'Trending skills and categories' },
|
||||
{ name: 'System', description: 'Health checks and diagnostics' },
|
||||
],
|
||||
};
|
||||
|
||||
const SWAGGER_HTML = `<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>SkillKit API Documentation</title>
|
||||
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
|
||||
<style>
|
||||
body { margin: 0; background: #1a1a2e; }
|
||||
.swagger-ui .topbar { display: none; }
|
||||
.swagger-ui { max-width: 1200px; margin: 0 auto; }
|
||||
.swagger-ui .info .title { font-family: monospace; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="swagger-ui"></div>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
|
||||
<script>
|
||||
SwaggerUIBundle({
|
||||
url: '/openapi.json',
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
showExtensions: true,
|
||||
showCommonExtensions: true,
|
||||
defaultModelsExpandDepth: 2,
|
||||
defaultModelExpandDepth: 2,
|
||||
docExpansion: 'list',
|
||||
filter: true,
|
||||
tryItOutEnabled: true,
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>`;
|
||||
|
||||
export function docsRoutes() {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/openapi.json', (c) => {
|
||||
return c.json(OPENAPI_SPEC);
|
||||
});
|
||||
|
||||
app.get('/docs', (c) => {
|
||||
return c.html(SWAGGER_HTML);
|
||||
});
|
||||
|
||||
app.get('/', (c) => {
|
||||
return c.json({
|
||||
name: 'SkillKit API',
|
||||
version: '1.12.0',
|
||||
docs: '/docs',
|
||||
openapi: '/openapi.json',
|
||||
endpoints: {
|
||||
search: 'GET /search?q=...',
|
||||
searchFiltered: 'POST /search',
|
||||
skill: 'GET /skills/:owner/:repo/:id',
|
||||
trending: 'GET /trending',
|
||||
categories: 'GET /categories',
|
||||
health: 'GET /health',
|
||||
cache: 'GET /cache/stats',
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { HealthResponse, CacheStatsResponse } from '../types.js';
|
||||
import type { CacheBackend } from '@skillkit/core';
|
||||
|
||||
const startTime = Date.now();
|
||||
|
||||
export function healthRoutes(skillCount: number, cache: CacheBackend) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/health', (c) => {
|
||||
const response: HealthResponse = {
|
||||
status: 'ok',
|
||||
version: '1.11.0',
|
||||
skillCount,
|
||||
uptime: Math.floor((Date.now() - startTime) / 1000),
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
app.get('/cache/stats', (c) => {
|
||||
const stats = cache.stats();
|
||||
const response: CacheStatsResponse = {
|
||||
hits: stats.hits,
|
||||
misses: stats.misses,
|
||||
size: stats.size,
|
||||
maxSize: stats.maxSize,
|
||||
hitRate: stats.hitRate,
|
||||
};
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, SearchResponse } from '../types.js';
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
import type { MemoryCache } from '@skillkit/core';
|
||||
|
||||
export function searchRoutes(skills: ApiSkill[], cache: MemoryCache<SearchResponse>) {
|
||||
const app = new Hono();
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
app.get('/search', (c) => {
|
||||
const query = c.req.query('q') || '';
|
||||
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
|
||||
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
|
||||
const includeContent = c.req.query('include_content') === 'true';
|
||||
|
||||
if (!query) {
|
||||
return c.json({ error: 'Query parameter "q" is required' }, 400);
|
||||
}
|
||||
|
||||
const cacheKey = `search:${query}:${limit}:${includeContent}`;
|
||||
const cached = cache.get(cacheKey);
|
||||
if (cached) return c.json(cached);
|
||||
|
||||
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
source: s.source,
|
||||
})),
|
||||
query,
|
||||
);
|
||||
|
||||
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
|
||||
if (!includeContent) {
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
}
|
||||
return original;
|
||||
});
|
||||
|
||||
const response: SearchResponse = {
|
||||
skills: results,
|
||||
total: ranked.length,
|
||||
query,
|
||||
limit,
|
||||
};
|
||||
|
||||
cache.set(cacheKey, response);
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
app.post('/search', async (c) => {
|
||||
let body: {
|
||||
query: string;
|
||||
limit?: number;
|
||||
include_content?: boolean;
|
||||
filters?: { tags?: string[]; category?: string; source?: string };
|
||||
};
|
||||
try {
|
||||
body = await c.req.json();
|
||||
} catch {
|
||||
return c.json({ error: 'Invalid JSON body' }, 400);
|
||||
}
|
||||
|
||||
if (!body.query) {
|
||||
return c.json({ error: 'Field "query" is required' }, 400);
|
||||
}
|
||||
|
||||
const limit = Math.min(body.limit ?? 20, 100);
|
||||
let filtered = skills;
|
||||
|
||||
if (body.filters) {
|
||||
if (body.filters.tags?.length) {
|
||||
filtered = filtered.filter((s) =>
|
||||
body.filters!.tags!.some((t) => s.tags?.includes(t)),
|
||||
);
|
||||
}
|
||||
if (body.filters.category) {
|
||||
filtered = filtered.filter((s) => s.category === body.filters!.category);
|
||||
}
|
||||
if (body.filters.source) {
|
||||
filtered = filtered.filter((s) => s.source.includes(body.filters!.source!));
|
||||
}
|
||||
}
|
||||
|
||||
const filteredMap = new Map(filtered.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
filtered.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
source: s.source,
|
||||
})),
|
||||
body.query,
|
||||
);
|
||||
|
||||
const results: ApiSkill[] = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = filteredMap.get(key) ?? filtered.find((s) => s.name === r.skill.name)!;
|
||||
if (!body.include_content) {
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
}
|
||||
return original;
|
||||
});
|
||||
|
||||
const response: SearchResponse = {
|
||||
skills: results,
|
||||
total: ranked.length,
|
||||
query: body.query,
|
||||
limit,
|
||||
};
|
||||
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill } from '../types.js';
|
||||
|
||||
export function skillRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
|
||||
app.get('/skills/:owner/:repo/:id', (c) => {
|
||||
const source = `${c.req.param('owner')}/${c.req.param('repo')}`;
|
||||
const id = c.req.param('id');
|
||||
|
||||
const skill = skills.find(
|
||||
(s) => s.source === source && s.name === id,
|
||||
);
|
||||
|
||||
if (!skill) {
|
||||
return c.json({ error: `Skill not found: ${source}/${id}` }, 404);
|
||||
}
|
||||
|
||||
return c.json(skill);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
import { Hono } from 'hono';
|
||||
import type { ApiSkill, TrendingResponse } from '../types.js';
|
||||
import { RelevanceRanker } from '@skillkit/core';
|
||||
|
||||
export function trendingRoutes(skills: ApiSkill[]) {
|
||||
const app = new Hono();
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
app.get('/trending', (c) => {
|
||||
const parsedLimit = parseInt(c.req.query('limit') || '20', 10);
|
||||
const limit = Math.min(Number.isNaN(parsedLimit) ? 20 : parsedLimit, 100);
|
||||
|
||||
const skillMap = new Map(skills.map((s) => [`${s.source}:${s.name}`, s]));
|
||||
|
||||
const ranked = ranker.rank(
|
||||
skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: s.content,
|
||||
stars: s.stars,
|
||||
installs: s.installs,
|
||||
references: [],
|
||||
source: s.source,
|
||||
})),
|
||||
);
|
||||
|
||||
const results = ranked.slice(0, limit).map((r) => {
|
||||
const key = `${(r.skill as Record<string, unknown>).source}:${r.skill.name}`;
|
||||
const original = skillMap.get(key) ?? skills.find((s) => s.name === r.skill.name)!;
|
||||
const { content: _, ...rest } = original;
|
||||
return rest;
|
||||
});
|
||||
|
||||
const response: TrendingResponse = { skills: results, limit };
|
||||
return c.json(response);
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
import { Hono } from 'hono';
|
||||
import { cors } from 'hono/cors';
|
||||
import { MemoryCache } from '@skillkit/core';
|
||||
import { rateLimiter } from './middleware/rate-limit.js';
|
||||
import { healthRoutes } from './routes/health.js';
|
||||
import { searchRoutes } from './routes/search.js';
|
||||
import { skillRoutes } from './routes/skills.js';
|
||||
import { trendingRoutes } from './routes/trending.js';
|
||||
import { categoryRoutes } from './routes/categories.js';
|
||||
import { docsRoutes } from './routes/docs.js';
|
||||
import type { ApiSkill, SearchResponse } from './types.js';
|
||||
|
||||
export interface ServerOptions {
|
||||
port?: number;
|
||||
host?: string;
|
||||
corsOrigin?: string;
|
||||
cacheTtlMs?: number;
|
||||
skills?: ApiSkill[];
|
||||
rateLimitMax?: number;
|
||||
}
|
||||
|
||||
export function createApp(options: ServerOptions = {}) {
|
||||
const skills = options.skills || [];
|
||||
const cache = new MemoryCache<SearchResponse>({
|
||||
maxSize: 500,
|
||||
ttlMs: options.cacheTtlMs ?? 86_400_000,
|
||||
});
|
||||
|
||||
const app = new Hono();
|
||||
|
||||
app.use('*', cors({ origin: options.corsOrigin || '*' }));
|
||||
app.use('*', rateLimiter(options.rateLimitMax ?? 60));
|
||||
|
||||
app.route('/', healthRoutes(skills.length, cache));
|
||||
app.route('/', searchRoutes(skills, cache));
|
||||
app.route('/', skillRoutes(skills));
|
||||
app.route('/', trendingRoutes(skills));
|
||||
app.route('/', categoryRoutes(skills));
|
||||
app.route('/', docsRoutes());
|
||||
|
||||
return { app, cache };
|
||||
}
|
||||
|
||||
export async function startServer(options: ServerOptions = {}) {
|
||||
const port = options.port ?? 3737;
|
||||
const host = options.host ?? '0.0.0.0';
|
||||
const { app, cache } = createApp(options);
|
||||
|
||||
const { serve } = await import('@hono/node-server');
|
||||
|
||||
const server = serve({ fetch: app.fetch, port, hostname: host }, () => {
|
||||
console.log(`SkillKit API server running at http://${host}:${port}`);
|
||||
console.log(`Skills loaded: ${options.skills?.length ?? 0}`);
|
||||
});
|
||||
|
||||
return { server, app, cache };
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
export interface ApiSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
source: string;
|
||||
repo?: string;
|
||||
tags?: string[];
|
||||
category?: string;
|
||||
content?: string;
|
||||
stars?: number;
|
||||
installs?: number;
|
||||
}
|
||||
|
||||
export interface SearchResponse {
|
||||
skills: ApiSkill[];
|
||||
total: number;
|
||||
query: string;
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface HealthResponse {
|
||||
status: 'ok';
|
||||
version: string;
|
||||
skillCount: number;
|
||||
uptime: number;
|
||||
}
|
||||
|
||||
export interface CacheStatsResponse {
|
||||
hits: number;
|
||||
misses: number;
|
||||
size: number;
|
||||
maxSize: number;
|
||||
hitRate: number;
|
||||
}
|
||||
|
||||
export interface TrendingResponse {
|
||||
skills: ApiSkill[];
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export interface CategoryCount {
|
||||
name: string;
|
||||
count: number;
|
||||
}
|
||||
|
||||
export interface CategoriesResponse {
|
||||
categories: CategoryCount[];
|
||||
total: number;
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"composite": false
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist", "**/*.test.ts"]
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
import { defineConfig } from 'tsup';
|
||||
|
||||
export default defineConfig({
|
||||
entry: ['src/index.ts'],
|
||||
format: ['esm'],
|
||||
target: 'node18',
|
||||
outDir: 'dist',
|
||||
clean: true,
|
||||
dts: true,
|
||||
sourcemap: true,
|
||||
splitting: false,
|
||||
skipNodeModulesBundle: true,
|
||||
platform: 'node',
|
||||
banner: {
|
||||
js: '#!/usr/bin/env node',
|
||||
},
|
||||
});
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/cli",
|
||||
"version": "1.9.0",
|
||||
"version": "1.13.0",
|
||||
"description": "CLI commands for SkillKit",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
@@ -22,6 +22,7 @@
|
||||
},
|
||||
"dependencies": {
|
||||
"@clack/prompts": "^0.11.0",
|
||||
"@skillkit/api": "workspace:*",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@skillkit/resources": "workspace:*",
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { join, normalize, resolve, sep } from 'node:path';
|
||||
|
||||
function isPathInside(child: string, parent: string): boolean {
|
||||
const resolved = resolve(child);
|
||||
const resolvedParent = resolve(parent);
|
||||
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
|
||||
}
|
||||
|
||||
function sanitizeName(name: string): string {
|
||||
return name.split(/[/\\]/).pop() || name;
|
||||
}
|
||||
|
||||
describe('Quick Command Security', () => {
|
||||
describe('path traversal protection', () => {
|
||||
const installDir = '/home/user/.claude/skills';
|
||||
|
||||
it('should block skill names that escape the install directory', () => {
|
||||
const maliciousNames = ['../evil', '../../etc/passwd', '../../../tmp/bad', '..\\evil'];
|
||||
|
||||
for (const name of maliciousNames) {
|
||||
const sanitized = sanitizeName(name);
|
||||
const targetPath = normalize(join(installDir, sanitized));
|
||||
expect(isPathInside(targetPath, installDir)).toBe(true);
|
||||
expect(sanitized).not.toContain('..');
|
||||
expect(sanitized).not.toContain('/');
|
||||
expect(sanitized).not.toContain('\\');
|
||||
}
|
||||
});
|
||||
|
||||
it('should sanitize "../evil" to "evil"', () => {
|
||||
expect(sanitizeName('../evil')).toBe('evil');
|
||||
});
|
||||
|
||||
it('should sanitize "../../etc/passwd" to "passwd"', () => {
|
||||
expect(sanitizeName('../../etc/passwd')).toBe('passwd');
|
||||
});
|
||||
|
||||
it('should sanitize "..\\evil" to "evil"', () => {
|
||||
expect(sanitizeName('..\\evil')).toBe('evil');
|
||||
});
|
||||
|
||||
it('should keep valid skill names unchanged', () => {
|
||||
expect(sanitizeName('my-skill')).toBe('my-skill');
|
||||
expect(sanitizeName('react-best-practices')).toBe('react-best-practices');
|
||||
});
|
||||
|
||||
it('should produce a path inside installDir after sanitization', () => {
|
||||
const evilName = '../evil';
|
||||
const sanitized = sanitizeName(evilName);
|
||||
const targetPath = normalize(join(installDir, sanitized));
|
||||
expect(isPathInside(targetPath, installDir)).toBe(true);
|
||||
expect(targetPath).toBe(join(installDir, 'evil'));
|
||||
});
|
||||
|
||||
it('should detect unsanitized traversal names before normalization', () => {
|
||||
const rawPath = `${installDir}/../evil`;
|
||||
expect(isPathInside(rawPath, installDir)).toBe(false);
|
||||
});
|
||||
|
||||
it('should ensure sanitization prevents the traversal entirely', () => {
|
||||
const evilName = '../evil';
|
||||
const sanitized = sanitizeName(evilName);
|
||||
const targetPath = normalize(join(installDir, sanitized));
|
||||
expect(targetPath).toBe(join(installDir, 'evil'));
|
||||
expect(targetPath.startsWith(installDir)).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,39 @@
|
||||
const SKILLKIT_LOGO_SVG_BASE64 =
|
||||
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
|
||||
|
||||
function encodeBadgeSegment(text: string): string {
|
||||
return encodeURIComponent(text).replace(/-/g, '--');
|
||||
}
|
||||
|
||||
export function generateBadge(skills: string[]): {
|
||||
url: string;
|
||||
markdown: string;
|
||||
html: string;
|
||||
} {
|
||||
const count = skills.length;
|
||||
|
||||
if (count === 0) {
|
||||
const url = `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
|
||||
return {
|
||||
url,
|
||||
markdown: `[](https://agenstskills.com)`,
|
||||
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
|
||||
};
|
||||
}
|
||||
|
||||
const maxDisplay = 5;
|
||||
const displayNames = skills.slice(0, maxDisplay);
|
||||
const suffix = count > maxDisplay ? ` +${count - maxDisplay} more` : '';
|
||||
const label = `SkillKit ${count} skills`;
|
||||
const message = displayNames.join(' | ') + suffix;
|
||||
const encodedLabel = encodeBadgeSegment(label);
|
||||
const encodedMessage = encodeBadgeSegment(message);
|
||||
|
||||
const url = `https://img.shields.io/badge/${encodedLabel}-${encodedMessage}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
|
||||
|
||||
return {
|
||||
url,
|
||||
markdown: `[](https://agenstskills.com)`,
|
||||
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
|
||||
};
|
||||
}
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
select,
|
||||
header,
|
||||
} from '../onboarding/index.js';
|
||||
import { FederatedSearch, GitHubSkillRegistry, RateLimitError } from '@skillkit/core';
|
||||
|
||||
interface SkillResult {
|
||||
name: string;
|
||||
@@ -54,6 +55,10 @@ export class FindCommand extends Command {
|
||||
description: 'Minimal output (just list skills)',
|
||||
});
|
||||
|
||||
federated = Option.Boolean('--federated,-f', false, {
|
||||
description: 'Search external registries (GitHub SKILL.md files)',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const s = spinner();
|
||||
const limit = parseInt(this.limit, 10) || 10;
|
||||
@@ -128,12 +133,46 @@ export class FindCommand extends Command {
|
||||
}
|
||||
}
|
||||
|
||||
if (this.federated && this.query) {
|
||||
s.start('Searching external registries...');
|
||||
const fedSearch = new FederatedSearch();
|
||||
fedSearch.addRegistry(new GitHubSkillRegistry());
|
||||
try {
|
||||
const fedResult = await fedSearch.search(this.query, { limit: parseInt(this.limit, 10) || 10 });
|
||||
s.stop(`Found ${fedResult.total} external skill(s) from ${fedResult.registries.join(', ') || 'none'}`);
|
||||
|
||||
if (fedResult.skills.length > 0) {
|
||||
console.log('');
|
||||
console.log(colors.bold('External Skills (SKILL.md):'));
|
||||
for (const skill of fedResult.skills) {
|
||||
const stars = typeof skill.stars === 'number' ? colors.muted(` ★${skill.stars}`) : '';
|
||||
const desc = skill.description
|
||||
? colors.muted(` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? '...' : ''}`)
|
||||
: '';
|
||||
console.log(` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${stars}${desc}`);
|
||||
if (!this.quiet) {
|
||||
console.log(` ${colors.muted(skill.source)}`);
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
}
|
||||
} catch (err) {
|
||||
if (err instanceof RateLimitError) {
|
||||
s.stop(colors.warning('Rate limited by GitHub API'));
|
||||
console.log(colors.muted('Set GITHUB_TOKEN env var or wait before retrying.'));
|
||||
} else {
|
||||
s.stop(colors.warning('Federated search failed'));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (results.length === 0) {
|
||||
console.log(colors.muted('No skills found matching your search'));
|
||||
console.log('');
|
||||
console.log(colors.muted('Try:'));
|
||||
console.log(colors.muted(' skillkit find --top # Show featured skills'));
|
||||
console.log(colors.muted(' skillkit ui # Browse in TUI'));
|
||||
console.log(colors.muted(' skillkit find --top # Show featured skills'));
|
||||
console.log(colors.muted(' skillkit find -f <query> # Search external registries'));
|
||||
console.log(colors.muted(' skillkit ui # Browse in TUI'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
|
||||
@@ -108,3 +108,12 @@ export {
|
||||
|
||||
// Tree command for hierarchical skill browsing (Phase 21)
|
||||
export { TreeCommand } from './tree.js';
|
||||
|
||||
// Quick setup (zero-friction entry)
|
||||
export { QuickCommand } from './quick.js';
|
||||
|
||||
// SKILL.md ecosystem
|
||||
export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from './skillmd.js';
|
||||
|
||||
// API server
|
||||
export { ServeCommand } from './serve.js';
|
||||
|
||||
@@ -8,6 +8,9 @@ import {
|
||||
getMemoryStatus,
|
||||
createMemoryCompressor,
|
||||
createMemoryInjector,
|
||||
createClaudeMdUpdater,
|
||||
syncGlobalClaudeMd,
|
||||
createProgressiveDisclosureManager,
|
||||
type Learning,
|
||||
} from '@skillkit/core';
|
||||
|
||||
@@ -24,17 +27,19 @@ export class MemoryCommand extends Command {
|
||||
captured from coding sessions across all AI agents.
|
||||
|
||||
Subcommands:
|
||||
- status: Show current memory status
|
||||
- search: Search memories by query
|
||||
- list: List all learnings
|
||||
- show: Show a specific learning
|
||||
- compress: Compress observations into learnings
|
||||
- export: Export a learning as a skill
|
||||
- import: Import memories from another project
|
||||
- clear: Clear session observations
|
||||
- add: Manually add a learning
|
||||
- rate: Rate a learning's effectiveness
|
||||
- config: Configure memory settings
|
||||
- status: Show current memory status
|
||||
- search: Search memories by query
|
||||
- list: List all learnings
|
||||
- show: Show a specific learning
|
||||
- compress: Compress observations into learnings
|
||||
- export: Export a learning as a skill
|
||||
- import: Import memories from another project
|
||||
- clear: Clear session observations
|
||||
- add: Manually add a learning
|
||||
- rate: Rate a learning's effectiveness
|
||||
- sync-claude: Sync learnings to CLAUDE.md
|
||||
- index: Show memory index (progressive disclosure)
|
||||
- config: Configure memory settings
|
||||
`,
|
||||
examples: [
|
||||
['Show memory status', '$0 memory status'],
|
||||
@@ -48,6 +53,8 @@ export class MemoryCommand extends Command {
|
||||
['Clear session', '$0 memory clear'],
|
||||
['Add manual learning', '$0 memory add --title "..." --content "..."'],
|
||||
['Rate effectiveness', '$0 memory rate <id> 85'],
|
||||
['Sync to CLAUDE.md', '$0 memory sync-claude'],
|
||||
['Show memory index', '$0 memory index'],
|
||||
],
|
||||
});
|
||||
|
||||
@@ -146,9 +153,13 @@ export class MemoryCommand extends Command {
|
||||
return this.rateLearning();
|
||||
case 'config':
|
||||
return this.showConfig();
|
||||
case 'sync-claude':
|
||||
return this.syncClaudeMd();
|
||||
case 'index':
|
||||
return this.showIndex();
|
||||
default:
|
||||
console.error(chalk.red(`Unknown action: ${action}`));
|
||||
console.log(chalk.gray('Available actions: status, search, list, show, compress, export, import, clear, add, rate, config'));
|
||||
console.log(chalk.gray('Available actions: status, search, list, show, compress, export, import, clear, add, rate, sync-claude, index, config'));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
@@ -761,6 +772,150 @@ export class MemoryCommand extends Command {
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sync learnings to CLAUDE.md
|
||||
*/
|
||||
private async syncClaudeMd(): Promise<number> {
|
||||
const projectPath = process.cwd();
|
||||
|
||||
if (this.global) {
|
||||
if (this.dryRun) {
|
||||
console.log(chalk.gray('(Dry run - previewing global CLAUDE.md sync)\n'));
|
||||
}
|
||||
|
||||
const result = this.dryRun
|
||||
? { updated: false, path: '~/.claude/CLAUDE.md', learningsAdded: 0, learningSummaries: [], previousLearnings: 0 }
|
||||
: syncGlobalClaudeMd({ minEffectiveness: 60 });
|
||||
|
||||
if (this.dryRun) {
|
||||
const globalStore = new LearningStore('global');
|
||||
const learnings = globalStore.getAll()
|
||||
.filter((l) => (l.effectiveness ?? 0) >= 60 || l.useCount >= 3)
|
||||
.slice(0, 20);
|
||||
console.log(chalk.cyan(`Would add ${learnings.length} learnings to global CLAUDE.md`));
|
||||
for (const l of learnings.slice(0, 5)) {
|
||||
console.log(` ${chalk.gray('●')} ${l.title}`);
|
||||
}
|
||||
if (learnings.length > 5) {
|
||||
console.log(chalk.gray(` ... and ${learnings.length - 5} more`));
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (result.updated) {
|
||||
console.log(chalk.green(`✓ Updated global CLAUDE.md with ${result.learningsAdded} learnings`));
|
||||
console.log(chalk.gray(` Path: ${result.path}`));
|
||||
} else {
|
||||
console.log(chalk.yellow('No learnings to sync to global CLAUDE.md'));
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
const updater = createClaudeMdUpdater(projectPath);
|
||||
|
||||
if (this.dryRun) {
|
||||
const preview = updater.preview({ minEffectiveness: 60 });
|
||||
|
||||
console.log(chalk.gray('(Dry run preview)\n'));
|
||||
|
||||
if (!preview.wouldUpdate) {
|
||||
console.log(chalk.yellow('No learnings to sync to CLAUDE.md'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan(`Would add ${preview.learnings.length} learnings to CLAUDE.md\n`));
|
||||
|
||||
for (const learning of preview.learnings.slice(0, 5)) {
|
||||
console.log(` ${chalk.gray('●')} ${learning.title}`);
|
||||
}
|
||||
|
||||
if (preview.learnings.length > 5) {
|
||||
console.log(chalk.gray(` ... and ${preview.learnings.length - 5} more`));
|
||||
}
|
||||
|
||||
console.log(chalk.bold('\nFormatted section preview:'));
|
||||
console.log(chalk.gray('─'.repeat(50)));
|
||||
console.log(preview.formattedSection.slice(0, 500));
|
||||
if (preview.formattedSection.length > 500) {
|
||||
console.log(chalk.gray('...'));
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
const result = updater.update({ minEffectiveness: 60 });
|
||||
|
||||
if (result.updated) {
|
||||
console.log(chalk.green(`✓ Updated CLAUDE.md with ${result.learningsAdded} learnings`));
|
||||
console.log(chalk.gray(` Path: ${result.path}`));
|
||||
|
||||
if (this.verbose && result.learningSummaries.length > 0) {
|
||||
console.log(chalk.cyan('\nLearnings added:'));
|
||||
for (const title of result.learningSummaries.slice(0, 10)) {
|
||||
console.log(` ${chalk.gray('●')} ${title}`);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.log(chalk.yellow('No learnings to sync to CLAUDE.md'));
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Show memory index (progressive disclosure Layer 1)
|
||||
*/
|
||||
private async showIndex(): Promise<number> {
|
||||
const projectPath = process.cwd();
|
||||
const manager = createProgressiveDisclosureManager(projectPath);
|
||||
|
||||
let maxResults = 50;
|
||||
if (this.limit) {
|
||||
const parsed = parseInt(this.limit, 10);
|
||||
if (isNaN(parsed) || parsed <= 0) {
|
||||
console.log(chalk.red('Invalid --limit value. Must be a positive number.'));
|
||||
return 1;
|
||||
}
|
||||
maxResults = parsed;
|
||||
}
|
||||
|
||||
const index = manager.getIndex({ includeGlobal: this.global, maxResults });
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(index, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.bold(`\nMemory Index (${index.length} entries)\n`));
|
||||
|
||||
if (index.length === 0) {
|
||||
console.log(chalk.gray('No learnings found.'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
const displayLimit = this.limit ? parseInt(this.limit, 10) : 20;
|
||||
const displayed = index.slice(0, displayLimit);
|
||||
|
||||
for (const entry of displayed) {
|
||||
const effectiveness = entry.effectiveness !== undefined
|
||||
? ` [${this.formatScore(entry.effectiveness)}%]`
|
||||
: '';
|
||||
const scope = entry.scope === 'global' ? chalk.magenta('[G]') : chalk.blue('[P]');
|
||||
|
||||
console.log(`${scope} ${chalk.gray(entry.id.slice(0, 8))} ${entry.title}${chalk.green(effectiveness)}`);
|
||||
console.log(` Tags: ${entry.tags.join(', ')} | Uses: ${entry.useCount}`);
|
||||
}
|
||||
|
||||
if (index.length > displayLimit) {
|
||||
console.log(chalk.gray(`\n... and ${index.length - displayLimit} more (use --limit to show more)`));
|
||||
}
|
||||
|
||||
console.log(chalk.gray('\nUse "skillkit memory show <id>" to view full details'));
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Format relevance/effectiveness score with color
|
||||
*/
|
||||
|
||||
@@ -0,0 +1,375 @@
|
||||
import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync } from 'node:fs';
|
||||
import { join, resolve, normalize } from 'node:path';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { promisify } from 'node:util';
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
import { Command } from 'clipanion';
|
||||
import {
|
||||
type ProjectProfile,
|
||||
type SkillMetadata,
|
||||
type AgentType,
|
||||
ContextManager,
|
||||
RecommendationEngine,
|
||||
loadIndex as loadIndexFromCache,
|
||||
isIndexStale,
|
||||
buildSkillIndex,
|
||||
saveIndex,
|
||||
KNOWN_SKILL_REPOS,
|
||||
isPathInside,
|
||||
isLocalPath,
|
||||
detectProvider,
|
||||
} from '@skillkit/core';
|
||||
import { getAdapter, detectAgent, getAllAdapters } from '@skillkit/agents';
|
||||
import { getInstallDir, saveSkillMetadata } from '../helpers.js';
|
||||
import {
|
||||
welcome,
|
||||
spinner,
|
||||
step,
|
||||
success,
|
||||
error,
|
||||
warn,
|
||||
colors,
|
||||
symbols,
|
||||
confirm,
|
||||
select,
|
||||
outro,
|
||||
formatAgent,
|
||||
getAgentIcon,
|
||||
isCancel,
|
||||
cancel,
|
||||
showProjectSummary,
|
||||
progressBar,
|
||||
formatQualityBadge,
|
||||
saveLastAgents,
|
||||
} from '../onboarding/index.js';
|
||||
|
||||
function truncate(str: string, maxLen: number): string {
|
||||
if (str.length <= maxLen) return str;
|
||||
return str.slice(0, maxLen - 3) + '...';
|
||||
}
|
||||
|
||||
export class QuickCommand extends Command {
|
||||
static override paths = [['quick']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Zero-friction skill setup: detect agents, analyze project, recommend and install',
|
||||
examples: [
|
||||
['Quick setup', '$0 quick'],
|
||||
],
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const s = spinner();
|
||||
|
||||
try {
|
||||
welcome();
|
||||
|
||||
step(`${colors.bold('Quick Setup')} - zero-friction skill installation`);
|
||||
console.log('');
|
||||
|
||||
s.start('Detecting installed AI agents...');
|
||||
const allAdapters = getAllAdapters();
|
||||
const detectedAgents: AgentType[] = [];
|
||||
|
||||
for (const adapter of allAdapters) {
|
||||
try {
|
||||
const installDir = getInstallDir(false, adapter.type);
|
||||
const globalDir = getInstallDir(true, adapter.type);
|
||||
if (existsSync(installDir) || existsSync(globalDir) || existsSync(adapter.configFile)) {
|
||||
detectedAgents.push(adapter.type);
|
||||
}
|
||||
} catch {
|
||||
// skip
|
||||
}
|
||||
}
|
||||
|
||||
if (detectedAgents.length === 0) {
|
||||
const fallback = await detectAgent();
|
||||
detectedAgents.push(fallback);
|
||||
}
|
||||
|
||||
s.stop(`Detected ${detectedAgents.length} agent${detectedAgents.length !== 1 ? 's' : ''}: ${detectedAgents.map(formatAgent).join(', ')}`);
|
||||
|
||||
s.start('Analyzing project...');
|
||||
const targetPath = resolve(process.cwd());
|
||||
const manager = new ContextManager(targetPath);
|
||||
let context = manager.get();
|
||||
if (!context) {
|
||||
context = manager.init();
|
||||
}
|
||||
s.stop('Project analyzed');
|
||||
|
||||
if (!context) {
|
||||
error('Failed to analyze project');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const profile: ProjectProfile = {
|
||||
name: context.project.name,
|
||||
type: context.project.type,
|
||||
stack: context.stack,
|
||||
patterns: context.patterns,
|
||||
installedSkills: context.skills?.installed || [],
|
||||
excludedSkills: context.skills?.excluded || [],
|
||||
};
|
||||
|
||||
const languages = profile.stack.languages.map((l: { name: string; version?: string }) => `${l.name}${l.version ? ` ${l.version}` : ''}`);
|
||||
const frameworks = profile.stack.frameworks.map((f: { name: string; version?: string }) => `${f.name}${f.version ? ` ${f.version}` : ''}`);
|
||||
|
||||
showProjectSummary({
|
||||
name: profile.name,
|
||||
type: profile.type,
|
||||
languages,
|
||||
frameworks,
|
||||
});
|
||||
|
||||
let index = loadIndexFromCache();
|
||||
|
||||
if (!index || index.skills.length === 0) {
|
||||
s.start('Building skill index from known sources...');
|
||||
try {
|
||||
const result = await buildSkillIndex(KNOWN_SKILL_REPOS, (message: string) => {
|
||||
s.message(message);
|
||||
});
|
||||
index = result.index;
|
||||
saveIndex(index);
|
||||
s.stop(`Indexed ${index.skills.length} skills`);
|
||||
} catch {
|
||||
s.stop(colors.error('Failed to build index'));
|
||||
warn('Could not fetch skill index. Try running: skillkit recommend --update');
|
||||
return 1;
|
||||
}
|
||||
} else if (isIndexStale(index)) {
|
||||
step(colors.muted('Skill index is stale. Run "skillkit recommend --update" to refresh.'));
|
||||
}
|
||||
|
||||
const engine = new RecommendationEngine();
|
||||
engine.loadIndex(index);
|
||||
|
||||
const result = engine.recommend(profile, {
|
||||
limit: 5,
|
||||
minScore: 20,
|
||||
excludeInstalled: true,
|
||||
includeReasons: true,
|
||||
});
|
||||
|
||||
const recommendations = result.recommendations;
|
||||
|
||||
if (recommendations.length === 0) {
|
||||
warn('No matching skills found for your project.');
|
||||
console.log(colors.muted('Try running: skillkit recommend --update'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(colors.bold(`Top ${recommendations.length} Recommended Skills:`));
|
||||
console.log('');
|
||||
|
||||
const options: Array<{ value: string; label: string; hint?: string }> = [];
|
||||
|
||||
for (let i = 0; i < recommendations.length; i++) {
|
||||
const rec = recommendations[i];
|
||||
let scoreColor: (text: string) => string;
|
||||
if (rec.score >= 70) {
|
||||
scoreColor = colors.success;
|
||||
} else if (rec.score >= 50) {
|
||||
scoreColor = colors.warning;
|
||||
} else {
|
||||
scoreColor = colors.muted;
|
||||
}
|
||||
const scoreBar = progressBar(rec.score, 100, 10);
|
||||
const qualityScore = rec.skill.quality ?? null;
|
||||
const qualityDisplay = typeof qualityScore === 'number' && Number.isFinite(qualityScore)
|
||||
? ` ${formatQualityBadge(qualityScore)}`
|
||||
: '';
|
||||
|
||||
console.log(` ${colors.bold(`${i + 1}.`)} ${scoreColor(`${rec.score}%`)} ${colors.dim(scoreBar)} ${colors.bold(rec.skill.name)}${qualityDisplay}`);
|
||||
|
||||
if (rec.skill.description) {
|
||||
console.log(` ${colors.muted(truncate(rec.skill.description, 70))}`);
|
||||
}
|
||||
|
||||
options.push({
|
||||
value: `${i}`,
|
||||
label: `${rec.skill.name} (${rec.score}% match)`,
|
||||
hint: rec.skill.source || undefined,
|
||||
});
|
||||
}
|
||||
|
||||
console.log('');
|
||||
|
||||
const skipOption = { value: 'skip', label: 'Skip installation' };
|
||||
const selectResult = await select({
|
||||
message: 'Select a skill to install',
|
||||
options: [...options, skipOption],
|
||||
});
|
||||
|
||||
if (isCancel(selectResult) || selectResult === 'skip') {
|
||||
cancel('Quick setup complete (no installation)');
|
||||
return 0;
|
||||
}
|
||||
|
||||
const selectedIndex = parseInt(selectResult as string, 10);
|
||||
const selectedSkill = recommendations[selectedIndex];
|
||||
|
||||
if (!selectedSkill || !selectedSkill.skill.source) {
|
||||
error('Selected skill has no installable source');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const agentDisplay = detectedAgents.length <= 3
|
||||
? detectedAgents.map(formatAgent).join(', ')
|
||||
: `${detectedAgents.slice(0, 2).map(formatAgent).join(', ')} +${detectedAgents.length - 2} more`;
|
||||
|
||||
const confirmResult = await confirm({
|
||||
message: `Install ${colors.bold(selectedSkill.skill.name)} to ${agentDisplay}?`,
|
||||
initialValue: true,
|
||||
});
|
||||
|
||||
if (isCancel(confirmResult) || !confirmResult) {
|
||||
cancel('Installation cancelled');
|
||||
return 0;
|
||||
}
|
||||
|
||||
saveLastAgents(detectedAgents);
|
||||
|
||||
const providerAdapter = detectProvider(selectedSkill.skill.source);
|
||||
|
||||
if (!providerAdapter) {
|
||||
error(`Could not detect provider for: ${selectedSkill.skill.source}`);
|
||||
return 1;
|
||||
}
|
||||
|
||||
s.start(`Fetching ${selectedSkill.skill.name}...`);
|
||||
|
||||
const cloneResult = await providerAdapter.clone(selectedSkill.skill.source, '', { depth: 1 });
|
||||
|
||||
if (!cloneResult.success || !cloneResult.path) {
|
||||
s.stop(colors.error(cloneResult.error || 'Failed to fetch source'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const discoveredSkills = cloneResult.discoveredSkills || [];
|
||||
const matchedSkill = discoveredSkills.find(ds => ds.name === selectedSkill.skill.name) || discoveredSkills[0];
|
||||
|
||||
if (!matchedSkill) {
|
||||
s.stop(colors.error('Skill not found in repository'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
s.stop(`Found ${selectedSkill.skill.name}`);
|
||||
|
||||
let primaryPath: string | null = null;
|
||||
const installedAgents: string[] = [];
|
||||
|
||||
for (const agentType of detectedAgents) {
|
||||
const adapter = getAdapter(agentType);
|
||||
const installDir = getInstallDir(false, agentType);
|
||||
|
||||
if (!existsSync(installDir)) {
|
||||
mkdirSync(installDir, { recursive: true });
|
||||
}
|
||||
|
||||
const sanitizedName = matchedSkill.name.split(/[/\\]/).pop() || matchedSkill.name;
|
||||
const targetInstallPath = normalize(join(installDir, sanitizedName));
|
||||
|
||||
if (!isPathInside(targetInstallPath, installDir)) {
|
||||
error(`Skipping ${matchedSkill.name} for ${adapter.name} (install path escapes target directory)`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const securityRoot = cloneResult.tempRoot || cloneResult.path;
|
||||
if (!isPathInside(matchedSkill.path, securityRoot)) {
|
||||
error(`Skipping ${matchedSkill.name} for ${adapter.name} (path traversal detected)`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const useSymlink = detectedAgents.length > 1 && primaryPath !== null;
|
||||
|
||||
s.start(`Installing to ${adapter.name}${useSymlink ? ' (symlink)' : ''}...`);
|
||||
|
||||
try {
|
||||
if (existsSync(targetInstallPath)) {
|
||||
rmSync(targetInstallPath, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
if (useSymlink && primaryPath) {
|
||||
symlinkSync(primaryPath, targetInstallPath, 'dir');
|
||||
} else {
|
||||
cpSync(matchedSkill.path, targetInstallPath, { recursive: true, dereference: true });
|
||||
if (detectedAgents.length > 1 && primaryPath === null) {
|
||||
primaryPath = targetInstallPath;
|
||||
}
|
||||
|
||||
const packageJsonPath = join(targetInstallPath, 'package.json');
|
||||
if (existsSync(packageJsonPath)) {
|
||||
s.stop(`Installed to ${adapter.name}`);
|
||||
s.start('Installing npm dependencies...');
|
||||
try {
|
||||
await execFileAsync('npm', ['install', '--production'], { cwd: targetInstallPath });
|
||||
s.stop('Dependencies installed');
|
||||
} catch {
|
||||
s.stop(colors.warning('Dependencies failed'));
|
||||
console.log(colors.muted('Run manually: npm install in ' + targetInstallPath));
|
||||
}
|
||||
s.start('Finishing installation...');
|
||||
}
|
||||
}
|
||||
|
||||
const metadata: SkillMetadata = {
|
||||
name: matchedSkill.name,
|
||||
description: selectedSkill.skill.description || '',
|
||||
source: selectedSkill.skill.source,
|
||||
sourceType: providerAdapter.type,
|
||||
subpath: matchedSkill.name,
|
||||
installedAt: new Date().toISOString(),
|
||||
enabled: true,
|
||||
};
|
||||
saveSkillMetadata(targetInstallPath, metadata);
|
||||
|
||||
installedAgents.push(agentType);
|
||||
s.stop(`Installed to ${adapter.name}${useSymlink ? ' (symlink)' : ''}`);
|
||||
} catch (err) {
|
||||
s.stop(colors.error(`Failed to install to ${adapter.name}`));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
}
|
||||
}
|
||||
|
||||
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
|
||||
if (!isLocalPath(selectedSkill.skill.source) && cleanupPath && existsSync(cleanupPath)) {
|
||||
rmSync(cleanupPath, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
if (installedAgents.length > 0) {
|
||||
console.log('');
|
||||
success(`Installed ${colors.bold(matchedSkill.name)} to ${installedAgents.length} agent${installedAgents.length !== 1 ? 's' : ''}`);
|
||||
for (const a of installedAgents) {
|
||||
console.log(colors.muted(` ${symbols.success} ${getAgentIcon(a)} ${formatAgent(a)}`));
|
||||
}
|
||||
|
||||
console.log('');
|
||||
const badgeUrl = `https://img.shields.io/badge/SkillKit-${encodeURIComponent(matchedSkill.name)}-black?style=flat-square`;
|
||||
console.log(colors.dim('Add to your README:'));
|
||||
console.log(colors.muted(` [](https://agenstskills.com)`));
|
||||
|
||||
outro('Quick setup complete!');
|
||||
|
||||
console.log('');
|
||||
console.log(colors.muted('Next steps:'));
|
||||
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit sync')} to update agent configs`));
|
||||
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit recommend')} for more suggestions`));
|
||||
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit list')} to see installed skills`));
|
||||
console.log('');
|
||||
} else {
|
||||
warn('No agents were installed');
|
||||
}
|
||||
|
||||
return 0;
|
||||
} catch (err) {
|
||||
s.stop(colors.error('Quick setup failed'));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -52,6 +52,9 @@ export class RecommendCommand extends Command {
|
||||
['Update skill index', '$0 recommend --update'],
|
||||
['Search for skills by task', '$0 recommend --task "authentication"'],
|
||||
['Search for skills (alias)', '$0 recommend --search "testing"'],
|
||||
['Hybrid search (vector + keyword)', '$0 recommend --search "auth" --hybrid'],
|
||||
['Hybrid search with query expansion', '$0 recommend --search "auth" --hybrid --expand'],
|
||||
['Build hybrid search index', '$0 recommend --build-index'],
|
||||
],
|
||||
});
|
||||
|
||||
@@ -125,6 +128,26 @@ export class RecommendCommand extends Command {
|
||||
description: 'Show category path for each recommendation',
|
||||
});
|
||||
|
||||
// Hybrid search mode
|
||||
hybrid = Option.Boolean('--hybrid,-H', false, {
|
||||
description: 'Use hybrid search (vector + keyword)',
|
||||
});
|
||||
|
||||
// Query expansion
|
||||
expand = Option.Boolean('--expand,-x', false, {
|
||||
description: 'Enable query expansion (requires --hybrid)',
|
||||
});
|
||||
|
||||
// Reranking
|
||||
rerank = Option.Boolean('--rerank', false, {
|
||||
description: 'Enable LLM reranking (requires --hybrid)',
|
||||
});
|
||||
|
||||
// Build index
|
||||
buildIndex = Option.Boolean('--build-index', false, {
|
||||
description: 'Build/rebuild the hybrid search embedding index',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const targetPath = resolve(this.projectPath || process.cwd());
|
||||
|
||||
@@ -133,6 +156,16 @@ export class RecommendCommand extends Command {
|
||||
return await this.updateIndex();
|
||||
}
|
||||
|
||||
// Handle hybrid index building
|
||||
if (this.buildIndex) {
|
||||
return await this.buildHybridIndex();
|
||||
}
|
||||
|
||||
// Validate hybrid-dependent options
|
||||
if ((this.expand || this.rerank) && !this.hybrid) {
|
||||
warn('--expand and --rerank require --hybrid flag. These options will be ignored.');
|
||||
}
|
||||
|
||||
if (!this.quiet && !this.json) {
|
||||
header('Skill Recommendations');
|
||||
}
|
||||
@@ -168,6 +201,9 @@ export class RecommendCommand extends Command {
|
||||
// Handle search mode (--search or --task)
|
||||
const searchQuery = this.search || this.task;
|
||||
if (searchQuery) {
|
||||
if (this.hybrid) {
|
||||
return await this.handleHybridSearch(engine, searchQuery);
|
||||
}
|
||||
return this.handleSearch(engine, searchQuery);
|
||||
}
|
||||
|
||||
@@ -446,6 +482,132 @@ export class RecommendCommand extends Command {
|
||||
console.log(colors.muted('More details: skillkit recommend --explain --verbose'));
|
||||
}
|
||||
|
||||
private async handleHybridSearch(engine: RecommendationEngine, query: string): Promise<number> {
|
||||
if (!this.quiet && !this.json) {
|
||||
header(`Hybrid Search: "${query}"`);
|
||||
}
|
||||
|
||||
const s = !this.quiet && !this.json ? spinner() : null;
|
||||
s?.start('Initializing hybrid search...');
|
||||
|
||||
try {
|
||||
await engine.initHybridSearch();
|
||||
s?.message('Searching...');
|
||||
|
||||
const results = await engine.hybridSearch({
|
||||
query,
|
||||
limit: this.limit ? parseInt(this.limit, 10) : 10,
|
||||
hybrid: true,
|
||||
enableExpansion: this.expand,
|
||||
enableReranking: this.rerank,
|
||||
filters: {
|
||||
minScore: this.minScore ? parseInt(this.minScore, 10) : undefined,
|
||||
},
|
||||
});
|
||||
|
||||
s?.stop(`Found ${results.length} results`);
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(results, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (results.length === 0) {
|
||||
warn(`No skills found matching "${query}"`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(colors.bold(`Hybrid search results for "${query}" (${results.length} found):`));
|
||||
if (this.expand && results[0]?.expandedTerms?.length) {
|
||||
console.log(colors.muted(` Expanded: ${results[0].expandedTerms.join(', ')}`));
|
||||
}
|
||||
console.log('');
|
||||
|
||||
for (const result of results) {
|
||||
let relevanceColor: (text: string) => string;
|
||||
if (result.relevance >= 70) {
|
||||
relevanceColor = colors.success;
|
||||
} else if (result.relevance >= 50) {
|
||||
relevanceColor = colors.warning;
|
||||
} else {
|
||||
relevanceColor = colors.muted;
|
||||
}
|
||||
const relevanceBar = progressBar(result.relevance, 100, 10);
|
||||
|
||||
console.log(` ${relevanceColor(`${result.relevance}%`)} ${colors.dim(relevanceBar)} ${colors.bold(result.skill.name)}`);
|
||||
|
||||
if (result.skill.description) {
|
||||
console.log(` ${colors.muted(truncate(result.skill.description, 70))}`);
|
||||
}
|
||||
|
||||
if (this.verbose) {
|
||||
const scores: string[] = [];
|
||||
if (typeof result.vectorSimilarity === 'number') {
|
||||
scores.push(`vector: ${(result.vectorSimilarity * 100).toFixed(0)}%`);
|
||||
}
|
||||
if (typeof result.keywordScore === 'number') {
|
||||
scores.push(`keyword: ${result.keywordScore.toFixed(0)}%`);
|
||||
}
|
||||
if (typeof result.rrfScore === 'number') {
|
||||
scores.push(`rrf: ${result.rrfScore.toFixed(3)}`);
|
||||
}
|
||||
if (scores.length > 0) {
|
||||
console.log(` ${colors.dim('Scores:')} ${scores.join(' | ')}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (result.matchedTerms.length > 0) {
|
||||
console.log(` ${colors.dim('Matched:')} ${result.matchedTerms.join(', ')}`);
|
||||
}
|
||||
|
||||
console.log('');
|
||||
}
|
||||
|
||||
return 0;
|
||||
} catch (err) {
|
||||
s?.stop(colors.error('Hybrid search failed'));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
console.log(colors.muted('Falling back to standard search...'));
|
||||
return this.handleSearch(engine, query);
|
||||
}
|
||||
}
|
||||
|
||||
private async buildHybridIndex(): Promise<number> {
|
||||
if (!this.quiet) {
|
||||
header('Build Hybrid Search Index');
|
||||
}
|
||||
|
||||
const index = this.loadIndex();
|
||||
if (!index || index.skills.length === 0) {
|
||||
warn('No skill index found. Run --update first.');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const s = spinner();
|
||||
s.start('Initializing...');
|
||||
|
||||
try {
|
||||
const engine = new RecommendationEngine();
|
||||
engine.loadIndex(index);
|
||||
|
||||
await engine.buildHybridIndex((progress) => {
|
||||
const percentage = Math.round((progress.current / progress.total) * 100);
|
||||
s.message(`${progress.phase}: ${progress.message || ''} (${percentage}%)`);
|
||||
});
|
||||
|
||||
s.stop(colors.success(`${symbols.success} Built hybrid index for ${index.skills.length} skills`));
|
||||
console.log(colors.muted(' Index stored in: ~/.skillkit/search.db'));
|
||||
console.log(colors.muted(' Use --hybrid flag for vector+keyword search\n'));
|
||||
|
||||
return 0;
|
||||
} catch (err) {
|
||||
s.stop(colors.error('Failed to build hybrid index'));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private handleSearch(engine: RecommendationEngine, query: string): number {
|
||||
if (!this.quiet && !this.json) {
|
||||
header(`Search: "${query}"`);
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
import { Command, Option } from 'clipanion';
|
||||
import {
|
||||
colors,
|
||||
header,
|
||||
step,
|
||||
} from '../onboarding/index.js';
|
||||
|
||||
import skillsData from '../../../../marketplace/skills.json' with { type: 'json' };
|
||||
|
||||
export class ServeCommand extends Command {
|
||||
static override paths = [['serve'], ['server']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Start the SkillKit REST API server for skill discovery',
|
||||
details: `
|
||||
Launches a local HTTP server that exposes the SkillKit skill catalog
|
||||
via a REST API. Useful for integrating with other tools, building
|
||||
custom UIs, or enabling agent-native skill discovery.
|
||||
`,
|
||||
examples: [
|
||||
['Start server on default port', '$0 serve'],
|
||||
['Start on custom port', '$0 serve --port 8080'],
|
||||
['Start with custom CORS', '$0 serve --cors "http://localhost:3000"'],
|
||||
],
|
||||
});
|
||||
|
||||
port = Option.String('--port,-p', '3737', {
|
||||
description: 'Port to listen on',
|
||||
});
|
||||
|
||||
host = Option.String('--host,-H', '0.0.0.0', {
|
||||
description: 'Host to bind to',
|
||||
});
|
||||
|
||||
corsOrigin = Option.String('--cors', '*', {
|
||||
description: 'CORS allowed origin',
|
||||
});
|
||||
|
||||
cacheTtl = Option.String('--cache-ttl', '86400000', {
|
||||
description: 'Cache TTL in milliseconds',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
header('SkillKit API Server');
|
||||
|
||||
const skills = (skillsData.skills || []).map((skill: Record<string, unknown>) => ({
|
||||
name: skill.name as string,
|
||||
description: skill.description as string | undefined,
|
||||
source: (skill.source as string) || '',
|
||||
repo: skill.repo as string | undefined,
|
||||
tags: skill.tags as string[] | undefined,
|
||||
category: skill.category as string | undefined,
|
||||
}));
|
||||
|
||||
step(`Loading ${skills.length} skills from marketplace`);
|
||||
|
||||
const portNum = parseInt(this.port, 10) || 3737;
|
||||
const cacheTtlMs = parseInt(this.cacheTtl, 10) || 86_400_000;
|
||||
|
||||
try {
|
||||
const { startServer } = await import('@skillkit/api');
|
||||
|
||||
await startServer({
|
||||
port: portNum,
|
||||
host: this.host,
|
||||
corsOrigin: this.corsOrigin,
|
||||
cacheTtlMs,
|
||||
skills,
|
||||
});
|
||||
|
||||
step(`Server running at ${colors.cyan(`http://${this.host}:${portNum}`)}`);
|
||||
console.log('');
|
||||
console.log(colors.muted('Endpoints:'));
|
||||
console.log(colors.muted(` GET /health - Server health check`));
|
||||
console.log(colors.muted(` GET /search?q=... - Search skills`));
|
||||
console.log(colors.muted(` POST /search - Search with filters`));
|
||||
console.log(colors.muted(` GET /skills/:o/:r/:id - Get specific skill`));
|
||||
console.log(colors.muted(` GET /trending - Top skills`));
|
||||
console.log(colors.muted(` GET /categories - Skill categories`));
|
||||
console.log(colors.muted(` GET /cache/stats - Cache statistics`));
|
||||
console.log(colors.muted(` GET /docs - Interactive API docs`));
|
||||
console.log(colors.muted(` GET /openapi.json - OpenAPI specification`));
|
||||
console.log('');
|
||||
console.log(colors.muted('Press Ctrl+C to stop'));
|
||||
|
||||
await new Promise(() => {});
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : String(err);
|
||||
console.error(colors.error(`Failed to start server: ${message}`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,440 @@
|
||||
import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
|
||||
import { join, resolve, basename, relative } from 'node:path';
|
||||
import { Command, Option } from 'clipanion';
|
||||
import {
|
||||
colors,
|
||||
symbols,
|
||||
spinner,
|
||||
step,
|
||||
success,
|
||||
error,
|
||||
warn,
|
||||
header,
|
||||
} from '../onboarding/index.js';
|
||||
|
||||
interface SkillMdValidation {
|
||||
path: string;
|
||||
exists: boolean;
|
||||
hasName: boolean;
|
||||
hasDescription: boolean;
|
||||
hasTriggers: boolean;
|
||||
hasCapabilities: boolean;
|
||||
triggerCount: number;
|
||||
capabilityCount: number;
|
||||
score: number;
|
||||
issues: string[];
|
||||
}
|
||||
|
||||
function validateSkillMd(filePath: string): SkillMdValidation {
|
||||
const result: SkillMdValidation = {
|
||||
path: filePath,
|
||||
exists: false,
|
||||
hasName: false,
|
||||
hasDescription: false,
|
||||
hasTriggers: false,
|
||||
hasCapabilities: false,
|
||||
triggerCount: 0,
|
||||
capabilityCount: 0,
|
||||
score: 0,
|
||||
issues: [],
|
||||
};
|
||||
|
||||
if (!existsSync(filePath)) {
|
||||
result.issues.push('File does not exist');
|
||||
return result;
|
||||
}
|
||||
|
||||
result.exists = true;
|
||||
const content = readFileSync(filePath, 'utf-8');
|
||||
|
||||
if (!content.trim()) {
|
||||
result.issues.push('File is empty');
|
||||
return result;
|
||||
}
|
||||
|
||||
const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
||||
const bodyContent = frontmatterMatch
|
||||
? content.slice(frontmatterMatch[0].length)
|
||||
: content;
|
||||
|
||||
if (frontmatterMatch) {
|
||||
const frontmatter = frontmatterMatch[1];
|
||||
if (/^name:\s*.+$/m.test(frontmatter)) result.hasName = true;
|
||||
if (/^description:\s*.+$/m.test(frontmatter)) result.hasDescription = true;
|
||||
}
|
||||
|
||||
if (!result.hasName) {
|
||||
if (/^#\s+.+$/m.test(bodyContent)) result.hasName = true;
|
||||
}
|
||||
|
||||
if (!result.hasDescription) {
|
||||
if (/^##?\s*(description|about|overview)\b/im.test(bodyContent)) {
|
||||
result.hasDescription = true;
|
||||
} else {
|
||||
const lines = bodyContent.split(/\r?\n/).filter(l => l.trim());
|
||||
const nonHeaderLines = lines.filter(l => !l.startsWith('#'));
|
||||
if (nonHeaderLines.length >= 2) result.hasDescription = true;
|
||||
}
|
||||
}
|
||||
|
||||
const triggerPatterns = [
|
||||
/triggers?\s*when/i,
|
||||
/when\s*to\s*use/i,
|
||||
/use\s*this\s*when/i,
|
||||
/\*\*triggers?\b/i,
|
||||
/^[-*]\s+.+(when|if|pattern|trigger)/im,
|
||||
/glob:/i,
|
||||
];
|
||||
|
||||
for (const pattern of triggerPatterns) {
|
||||
if (pattern.test(content)) {
|
||||
result.hasTriggers = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (result.hasTriggers) {
|
||||
const triggerSection = content.match(/triggers?\s*when[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
|
||||
result.triggerCount = triggerSection
|
||||
? (triggerSection[1].match(/^[-*]\s+/gm) || []).length
|
||||
: 1;
|
||||
}
|
||||
|
||||
const capabilityPatterns = [
|
||||
/capabilities?[:\s]/i,
|
||||
/features?[:\s]/i,
|
||||
/what\s*(it|this)\s*(does|can)/i,
|
||||
/^##?\s*capabilities/im,
|
||||
/^##?\s*features/im,
|
||||
];
|
||||
|
||||
for (const pattern of capabilityPatterns) {
|
||||
if (pattern.test(content)) {
|
||||
result.hasCapabilities = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (result.hasCapabilities) {
|
||||
const capSection = content.match(/(?:capabilities?|features?)[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
|
||||
result.capabilityCount = capSection
|
||||
? (capSection[1].match(/^[-*]\s+/gm) || []).length
|
||||
: 1;
|
||||
}
|
||||
|
||||
if (!result.hasName) result.issues.push('Missing name field');
|
||||
if (!result.hasDescription) result.issues.push('Missing description section');
|
||||
if (!result.hasTriggers) result.issues.push('No trigger patterns found');
|
||||
if (!result.hasCapabilities) result.issues.push('No capabilities list found');
|
||||
|
||||
let score = 0;
|
||||
if (result.exists) score += 10;
|
||||
if (result.hasName) score += 20;
|
||||
if (result.hasDescription) score += 25;
|
||||
if (result.hasTriggers) score += 20;
|
||||
if (result.hasCapabilities) score += 15;
|
||||
if (result.triggerCount >= 3) score += 5;
|
||||
if (result.capabilityCount >= 3) score += 5;
|
||||
|
||||
if (frontmatterMatch) {
|
||||
const fm = frontmatterMatch[1];
|
||||
if (/^version:/m.test(fm)) score += 3;
|
||||
if (/^license:/m.test(fm)) score += 2;
|
||||
if (/^tags:/m.test(fm)) score += 3;
|
||||
if (/^metadata:/m.test(fm)) score += 2;
|
||||
}
|
||||
|
||||
result.score = Math.min(100, score);
|
||||
return result;
|
||||
}
|
||||
|
||||
function printValidation(validation: SkillMdValidation, verbose = false): void {
|
||||
const scoreColor = validation.score >= 80
|
||||
? colors.success
|
||||
: validation.score >= 60
|
||||
? colors.warning
|
||||
: colors.error;
|
||||
|
||||
console.log(` ${colors.muted('Score:')} ${scoreColor(`${validation.score}`)}/100`);
|
||||
console.log(` ${validation.hasName ? colors.success(symbols.success) : colors.error(symbols.error)} Name field`);
|
||||
console.log(` ${validation.hasDescription ? colors.success(symbols.success) : colors.error(symbols.error)} Description section`);
|
||||
console.log(` ${validation.hasTriggers ? colors.success(symbols.success) : colors.error(symbols.error)} Trigger patterns${validation.triggerCount > 0 ? ` (${validation.triggerCount})` : ''}`);
|
||||
console.log(` ${validation.hasCapabilities ? colors.success(symbols.success) : colors.error(symbols.error)} Capabilities list${validation.capabilityCount > 0 ? ` (${validation.capabilityCount})` : ''}`);
|
||||
|
||||
if (verbose && validation.issues.length > 0) {
|
||||
console.log('');
|
||||
console.log(` ${colors.warning('Issues:')}`);
|
||||
for (const issue of validation.issues) {
|
||||
console.log(` ${colors.warning(symbols.warning)} ${issue}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export class SkillMdValidateCommand extends Command {
|
||||
static override paths = [['skillmd', 'validate'], ['skill-md', 'validate']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Validate a SKILL.md file against the standard',
|
||||
examples: [
|
||||
['Validate SKILL.md in current directory', '$0 skillmd validate'],
|
||||
['Validate specific file', '$0 skillmd validate ./path/to/SKILL.md'],
|
||||
],
|
||||
});
|
||||
|
||||
targetPath = Option.String({ required: false, name: 'path' });
|
||||
|
||||
verbose = Option.Boolean('--verbose,-v', false, {
|
||||
description: 'Show detailed validation results',
|
||||
});
|
||||
|
||||
json = Option.Boolean('--json', false, {
|
||||
description: 'Output as JSON',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const targetPath = this.targetPath || join(process.cwd(), 'SKILL.md');
|
||||
const resolvedPath = resolve(targetPath);
|
||||
const filePath = resolvedPath.endsWith('SKILL.md') ? resolvedPath : join(resolvedPath, 'SKILL.md');
|
||||
|
||||
if (!this.json) {
|
||||
header('SKILL.md Validation');
|
||||
step(`Validating: ${colors.cyan(filePath)}`);
|
||||
console.log('');
|
||||
}
|
||||
|
||||
const validation = validateSkillMd(filePath);
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(validation, null, 2));
|
||||
return validation.score >= 60 ? 0 : 1;
|
||||
}
|
||||
|
||||
console.log(colors.primary(basename(filePath)));
|
||||
printValidation(validation, this.verbose);
|
||||
console.log('');
|
||||
|
||||
if (validation.score >= 80) {
|
||||
success(`SKILL.md is compliant (score: ${validation.score}/100)`);
|
||||
} else if (validation.score >= 60) {
|
||||
warn(`SKILL.md needs improvement (score: ${validation.score}/100)`);
|
||||
} else {
|
||||
error(`SKILL.md does not meet minimum standard (score: ${validation.score}/100)`);
|
||||
}
|
||||
|
||||
return validation.score >= 60 ? 0 : 1;
|
||||
}
|
||||
}
|
||||
|
||||
export class SkillMdInitCommand extends Command {
|
||||
static override paths = [['skillmd', 'init'], ['skill-md', 'init']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Create a template SKILL.md in the current directory',
|
||||
examples: [
|
||||
['Create SKILL.md template', '$0 skillmd init'],
|
||||
['Create with custom name', '$0 skillmd init --name my-skill'],
|
||||
],
|
||||
});
|
||||
|
||||
name = Option.String('--name,-n', {
|
||||
description: 'Skill name',
|
||||
});
|
||||
|
||||
force = Option.Boolean('--force,-f', false, {
|
||||
description: 'Overwrite existing SKILL.md',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const outputPath = join(process.cwd(), 'SKILL.md');
|
||||
|
||||
if (existsSync(outputPath) && !this.force) {
|
||||
warn('SKILL.md already exists');
|
||||
console.log(colors.muted('Use --force to overwrite'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skillName = this.name || basename(process.cwd());
|
||||
const formattedName = skillName
|
||||
.split('-')
|
||||
.map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
|
||||
.join(' ');
|
||||
|
||||
const template = [
|
||||
'---',
|
||||
`name: ${skillName}`,
|
||||
'description: What this skill does and when to use it',
|
||||
'version: "1.0"',
|
||||
'license: MIT',
|
||||
'tags: [general]',
|
||||
'metadata:',
|
||||
' author: your-name',
|
||||
'---',
|
||||
'',
|
||||
`# ${formattedName}`,
|
||||
'',
|
||||
'Brief description of what this skill provides to AI coding agents.',
|
||||
'',
|
||||
'## Triggers when:',
|
||||
`- User asks about ${skillName} related tasks`,
|
||||
`- Project contains ${skillName} configuration files`,
|
||||
`- Code changes involve ${skillName} patterns`,
|
||||
'',
|
||||
'## Capabilities:',
|
||||
`- Provides best practices for ${skillName}`,
|
||||
'- Generates boilerplate code and configurations',
|
||||
'- Validates existing implementations',
|
||||
'- Suggests improvements and optimizations',
|
||||
'',
|
||||
'## Steps',
|
||||
'1. First step the AI agent should take',
|
||||
'2. Second step with specific instructions',
|
||||
'3. Third step with expected outcome',
|
||||
'',
|
||||
'## Examples',
|
||||
'',
|
||||
'```',
|
||||
'Example code or configuration here',
|
||||
'```',
|
||||
'',
|
||||
].join('\n');
|
||||
|
||||
writeFileSync(outputPath, template);
|
||||
success(`Created SKILL.md for "${skillName}"`);
|
||||
console.log('');
|
||||
console.log(colors.muted('Next steps:'));
|
||||
console.log(` ${colors.cyan('1.')} Edit SKILL.md with your skill instructions`);
|
||||
console.log(` ${colors.cyan('2.')} Run ${colors.cyan('skillkit skillmd validate')} to check compliance`);
|
||||
console.log(` ${colors.cyan('3.')} Run ${colors.cyan('skillkit publish submit')} to share with the marketplace`);
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
export class SkillMdCheckCommand extends Command {
|
||||
static override paths = [['skillmd', 'check'], ['skill-md', 'check']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Check all SKILL.md files in the project for compliance',
|
||||
examples: [
|
||||
['Check current directory', '$0 skillmd check'],
|
||||
['Check specific directory', '$0 skillmd check ./skills'],
|
||||
],
|
||||
});
|
||||
|
||||
targetPath = Option.String({ required: false, name: 'path' });
|
||||
|
||||
verbose = Option.Boolean('--verbose,-v', false, {
|
||||
description: 'Show detailed validation results',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const targetPath = resolve(this.targetPath || process.cwd());
|
||||
|
||||
header('SKILL.md Compliance Check');
|
||||
|
||||
const s = spinner();
|
||||
s.start('Scanning for SKILL.md files...');
|
||||
const skillMdFiles = this.findSkillMdFiles(targetPath);
|
||||
s.stop(`Found ${skillMdFiles.length} SKILL.md file(s)`);
|
||||
|
||||
if (skillMdFiles.length === 0) {
|
||||
warn('No SKILL.md files found');
|
||||
console.log(colors.muted(`Searched: ${targetPath}`));
|
||||
console.log('');
|
||||
console.log(colors.muted('Create one with:'));
|
||||
console.log(` ${colors.cyan('skillkit skillmd init')}`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
const validations: SkillMdValidation[] = skillMdFiles.map(f => validateSkillMd(f));
|
||||
validations.sort((a, b) => b.score - a.score);
|
||||
|
||||
console.log('');
|
||||
|
||||
for (const validation of validations) {
|
||||
const relativePath = relative(targetPath, validation.path);
|
||||
const scoreColor = validation.score >= 80 ? colors.success : validation.score >= 60 ? colors.warning : colors.error;
|
||||
console.log(`${scoreColor(symbols.bullet)} ${colors.primary(relativePath)} ${colors.muted(`(${validation.score}/100)`)}`);
|
||||
if (this.verbose) {
|
||||
printValidation(validation, true);
|
||||
console.log('');
|
||||
}
|
||||
}
|
||||
|
||||
console.log('');
|
||||
|
||||
const passing = validations.filter(v => v.score >= 60).length;
|
||||
const failing = validations.filter(v => v.score < 60).length;
|
||||
const avgScore = Math.round(validations.reduce((sum, v) => sum + v.score, 0) / validations.length);
|
||||
|
||||
console.log(colors.muted('Summary:'));
|
||||
console.log(` ${colors.muted('Total:')} ${validations.length}`);
|
||||
console.log(` ${colors.success(symbols.success)} Passing (60+): ${passing}`);
|
||||
if (failing > 0) {
|
||||
console.log(` ${colors.error(symbols.error)} Failing: ${failing}`);
|
||||
}
|
||||
console.log(` ${colors.muted('Average score:')} ${avgScore}/100`);
|
||||
console.log('');
|
||||
|
||||
if (failing > 0) {
|
||||
error(`${failing} SKILL.md file(s) below minimum standard`);
|
||||
return 1;
|
||||
}
|
||||
|
||||
success('All SKILL.md files are compliant');
|
||||
return 0;
|
||||
}
|
||||
|
||||
private findSkillMdFiles(dir: string): string[] {
|
||||
const results: string[] = [];
|
||||
const directFile = join(dir, 'SKILL.md');
|
||||
if (existsSync(directFile)) results.push(directFile);
|
||||
|
||||
const searchDirs = [
|
||||
join(dir, 'skills'),
|
||||
join(dir, '.claude', 'skills'),
|
||||
join(dir, '.cursor', 'skills'),
|
||||
join(dir, '.codex', 'skills'),
|
||||
join(dir, '.github', 'skills'),
|
||||
];
|
||||
|
||||
for (const searchDir of searchDirs) {
|
||||
if (!existsSync(searchDir)) continue;
|
||||
this.scanDir(searchDir, results, 0);
|
||||
}
|
||||
|
||||
try {
|
||||
const entries = readdirSync(dir, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
|
||||
const entrySkillMd = join(dir, entry.name, 'SKILL.md');
|
||||
if (existsSync(entrySkillMd) && !results.includes(entrySkillMd)) {
|
||||
results.push(entrySkillMd);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// ignore read errors
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
private scanDir(dir: string, results: string[], depth: number): void {
|
||||
if (depth > 3) return;
|
||||
try {
|
||||
const entries = readdirSync(dir, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
const entryPath = join(dir, entry.name);
|
||||
if (entry.isFile() && entry.name === 'SKILL.md') {
|
||||
if (!results.includes(entryPath)) results.push(entryPath);
|
||||
}
|
||||
if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
|
||||
this.scanDir(entryPath, results, depth + 1);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// ignore read errors
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/core",
|
||||
"version": "1.9.0",
|
||||
"version": "1.13.0",
|
||||
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
@@ -37,6 +37,10 @@
|
||||
"./learning": {
|
||||
"import": "./dist/learning/index.js",
|
||||
"types": "./dist/learning/index.d.ts"
|
||||
},
|
||||
"./search": {
|
||||
"import": "./dist/search/index.js",
|
||||
"types": "./dist/search/index.d.ts"
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
@@ -53,7 +57,13 @@
|
||||
"yaml": "^2.6.1",
|
||||
"zod": "^3.24.1"
|
||||
},
|
||||
"optionalDependencies": {
|
||||
"node-llama-cpp": "^3.15.0",
|
||||
"better-sqlite3": "^12.0.0",
|
||||
"sqlite-vec": "^0.1.6"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/better-sqlite3": "^7.6.11",
|
||||
"@types/node": "^22.10.5",
|
||||
"tsup": "^8.3.5",
|
||||
"typescript": "^5.7.2",
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
import { describe, it, expect, beforeEach, vi } from 'vitest';
|
||||
import { MemoryCache } from '../memory.js';
|
||||
|
||||
describe('MemoryCache', () => {
|
||||
let cache: MemoryCache<string>;
|
||||
|
||||
beforeEach(() => {
|
||||
cache = new MemoryCache<string>({ maxSize: 3, ttlMs: 1000 });
|
||||
});
|
||||
|
||||
it('stores and retrieves values', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.get('a')).toBe('value-a');
|
||||
});
|
||||
|
||||
it('returns undefined for missing keys', () => {
|
||||
expect(cache.get('missing')).toBeUndefined();
|
||||
});
|
||||
|
||||
it('deletes entries', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.delete('a')).toBe(true);
|
||||
expect(cache.get('a')).toBeUndefined();
|
||||
});
|
||||
|
||||
it('checks existence with has()', () => {
|
||||
cache.set('a', 'value-a');
|
||||
expect(cache.has('a')).toBe(true);
|
||||
expect(cache.has('b')).toBe(false);
|
||||
});
|
||||
|
||||
it('clears all entries', () => {
|
||||
cache.set('a', '1');
|
||||
cache.set('b', '2');
|
||||
cache.clear();
|
||||
expect(cache.has('a')).toBe(false);
|
||||
expect(cache.stats().size).toBe(0);
|
||||
});
|
||||
|
||||
it('evicts LRU when at capacity', () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
cache.set('a', '1');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('b', '2');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('c', '3');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.get('a');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.get('b');
|
||||
vi.advanceTimersByTime(1);
|
||||
cache.set('d', '4');
|
||||
expect(cache.has('c')).toBe(false);
|
||||
expect(cache.has('a')).toBe(true);
|
||||
expect(cache.has('d')).toBe(true);
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it('expires entries after TTL', () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
cache.set('a', 'value');
|
||||
expect(cache.get('a')).toBe('value');
|
||||
vi.advanceTimersByTime(1001);
|
||||
expect(cache.get('a')).toBeUndefined();
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it('tracks hit/miss stats', () => {
|
||||
cache.set('a', '1');
|
||||
cache.get('a');
|
||||
cache.get('missing');
|
||||
const stats = cache.stats();
|
||||
expect(stats.hits).toBe(1);
|
||||
expect(stats.misses).toBe(1);
|
||||
expect(stats.hitRate).toBe(0.5);
|
||||
expect(stats.size).toBe(1);
|
||||
expect(stats.maxSize).toBe(3);
|
||||
});
|
||||
|
||||
it('uses default options', () => {
|
||||
const defaultCache = new MemoryCache<string>();
|
||||
const stats = defaultCache.stats();
|
||||
expect(stats.maxSize).toBe(1000);
|
||||
});
|
||||
});
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
export * from './types.js';
|
||||
export * from './memory.js';
|
||||
Vendored
+101
@@ -0,0 +1,101 @@
|
||||
import type { CacheBackend, CacheOptions, CacheStats } from './types.js';
|
||||
|
||||
interface CacheEntry<V> {
|
||||
value: V;
|
||||
expiresAt: number;
|
||||
lastAccessed: number;
|
||||
}
|
||||
|
||||
const DEFAULT_MAX_SIZE = 1000;
|
||||
const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
export class MemoryCache<V = unknown> implements CacheBackend<V> {
|
||||
private store = new Map<string, CacheEntry<V>>();
|
||||
private maxSize: number;
|
||||
private ttlMs: number;
|
||||
private hitCount = 0;
|
||||
private missCount = 0;
|
||||
|
||||
constructor(options?: CacheOptions) {
|
||||
this.maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
|
||||
this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
|
||||
}
|
||||
|
||||
get(key: string): V | undefined {
|
||||
const entry = this.store.get(key);
|
||||
if (!entry) {
|
||||
this.missCount++;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
if (Date.now() > entry.expiresAt) {
|
||||
this.store.delete(key);
|
||||
this.missCount++;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
entry.lastAccessed = Date.now();
|
||||
this.hitCount++;
|
||||
return entry.value;
|
||||
}
|
||||
|
||||
set(key: string, value: V): void {
|
||||
if (this.store.size >= this.maxSize && !this.store.has(key)) {
|
||||
this.evictLRU();
|
||||
}
|
||||
|
||||
const now = Date.now();
|
||||
this.store.set(key, {
|
||||
value,
|
||||
expiresAt: now + this.ttlMs,
|
||||
lastAccessed: now,
|
||||
});
|
||||
}
|
||||
|
||||
delete(key: string): boolean {
|
||||
return this.store.delete(key);
|
||||
}
|
||||
|
||||
has(key: string): boolean {
|
||||
const entry = this.store.get(key);
|
||||
if (!entry) return false;
|
||||
if (Date.now() > entry.expiresAt) {
|
||||
this.store.delete(key);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
clear(): void {
|
||||
this.store.clear();
|
||||
this.hitCount = 0;
|
||||
this.missCount = 0;
|
||||
}
|
||||
|
||||
stats(): CacheStats {
|
||||
const total = this.hitCount + this.missCount;
|
||||
return {
|
||||
hits: this.hitCount,
|
||||
misses: this.missCount,
|
||||
size: this.store.size,
|
||||
maxSize: this.maxSize,
|
||||
hitRate: total > 0 ? this.hitCount / total : 0,
|
||||
};
|
||||
}
|
||||
|
||||
private evictLRU(): void {
|
||||
let oldestKey: string | null = null;
|
||||
let oldestTime = Infinity;
|
||||
|
||||
for (const [key, entry] of this.store) {
|
||||
if (entry.lastAccessed < oldestTime) {
|
||||
oldestTime = entry.lastAccessed;
|
||||
oldestKey = key;
|
||||
}
|
||||
}
|
||||
|
||||
if (oldestKey) {
|
||||
this.store.delete(oldestKey);
|
||||
}
|
||||
}
|
||||
}
|
||||
Vendored
+21
@@ -0,0 +1,21 @@
|
||||
export interface CacheStats {
|
||||
hits: number;
|
||||
misses: number;
|
||||
size: number;
|
||||
maxSize: number;
|
||||
hitRate: number;
|
||||
}
|
||||
|
||||
export interface CacheOptions {
|
||||
maxSize?: number;
|
||||
ttlMs?: number;
|
||||
}
|
||||
|
||||
export interface CacheBackend<V = unknown> {
|
||||
get(key: string): V | undefined;
|
||||
set(key: string, value: V): void;
|
||||
delete(key: string): boolean;
|
||||
has(key: string): boolean;
|
||||
clear(): void;
|
||||
stats(): CacheStats;
|
||||
}
|
||||
@@ -101,3 +101,22 @@ export * from './connectors/index.js';
|
||||
|
||||
// Execution Flow (Step Tracking & Metrics - Phase 21)
|
||||
export * from './execution/index.js';
|
||||
|
||||
// Hybrid Search (QMD-Inspired Vector + Keyword Search)
|
||||
export * from './search/index.js';
|
||||
|
||||
// Federated Registry (External Skill Sources)
|
||||
export * from './registry/index.js';
|
||||
|
||||
// Pluggable Cache Backend
|
||||
export * from './cache/index.js';
|
||||
|
||||
// Multi-Signal Relevance Ranking
|
||||
export * from './ranking/index.js';
|
||||
|
||||
// Enhanced SKILL.md Parser (References & Frontmatter)
|
||||
export { discoverReferences, stripFrontmatter, parseSkillMd } from './parser/index.js';
|
||||
export type { SkillReference, ParsedSkillContent } from './parser/index.js';
|
||||
|
||||
// Runtime Skill Injection
|
||||
export * from './runtime/index.js';
|
||||
|
||||
@@ -0,0 +1,444 @@
|
||||
/**
|
||||
* CLAUDE.md Auto-Updater
|
||||
*
|
||||
* Automatically updates CLAUDE.md with learnings from memory.
|
||||
* Populates the LEARNED section with high-effectiveness insights.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { join, dirname, basename } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import type { Learning } from './types.js';
|
||||
import { LearningStore } from './learning-store.js';
|
||||
|
||||
/**
|
||||
* CLAUDE.md section markers
|
||||
*/
|
||||
const SKILLKIT_MARKER = '<!-- Auto-populated by SkillKit -->';
|
||||
|
||||
/**
|
||||
* Update options
|
||||
*/
|
||||
export interface ClaudeMdUpdateOptions {
|
||||
minEffectiveness?: number;
|
||||
maxLearnings?: number;
|
||||
includeGlobal?: boolean;
|
||||
preserveManualEntries?: boolean;
|
||||
sectionTitle?: string;
|
||||
addTimestamp?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default update options
|
||||
*/
|
||||
const DEFAULT_UPDATE_OPTIONS: Required<ClaudeMdUpdateOptions> = {
|
||||
minEffectiveness: 60,
|
||||
maxLearnings: 20,
|
||||
includeGlobal: false,
|
||||
preserveManualEntries: true,
|
||||
sectionTitle: 'LEARNED',
|
||||
addTimestamp: true,
|
||||
};
|
||||
|
||||
/**
|
||||
* Parsed CLAUDE.md structure
|
||||
*/
|
||||
export interface ParsedClaudeMd {
|
||||
content: string;
|
||||
sections: Map<string, { start: number; end: number; content: string }>;
|
||||
hasLearnedSection: boolean;
|
||||
learnedSectionContent?: string;
|
||||
learnedSectionRange?: { start: number; end: number };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update result
|
||||
*/
|
||||
export interface ClaudeMdUpdateResult {
|
||||
updated: boolean;
|
||||
path: string;
|
||||
learningsAdded: number;
|
||||
learningSummaries: string[];
|
||||
previousLearnings: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* CLAUDE.md Updater
|
||||
*
|
||||
* Manages automatic updates to CLAUDE.md with learnings from memory.
|
||||
*/
|
||||
export class ClaudeMdUpdater {
|
||||
private projectPath: string;
|
||||
private claudeMdPath: string;
|
||||
|
||||
constructor(projectPath: string, claudeMdPath?: string) {
|
||||
this.projectPath = projectPath;
|
||||
this.claudeMdPath = claudeMdPath || join(projectPath, 'CLAUDE.md');
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse CLAUDE.md to extract structure
|
||||
*/
|
||||
parse(): ParsedClaudeMd {
|
||||
if (!existsSync(this.claudeMdPath)) {
|
||||
return {
|
||||
content: '',
|
||||
sections: new Map(),
|
||||
hasLearnedSection: false,
|
||||
};
|
||||
}
|
||||
|
||||
const content = readFileSync(this.claudeMdPath, 'utf-8');
|
||||
const sections = new Map<string, { start: number; end: number; content: string }>();
|
||||
|
||||
const lines = content.split('\n');
|
||||
let currentSection: string | null = null;
|
||||
let sectionStart = 0;
|
||||
let sectionContent: string[] = [];
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const headerMatch = line.match(/^(#{1,3})\s+(.+)$/);
|
||||
|
||||
if (headerMatch) {
|
||||
if (currentSection) {
|
||||
sections.set(currentSection, {
|
||||
start: sectionStart,
|
||||
end: i - 1,
|
||||
content: sectionContent.join('\n'),
|
||||
});
|
||||
}
|
||||
|
||||
currentSection = headerMatch[2].trim();
|
||||
sectionStart = i;
|
||||
sectionContent = [line];
|
||||
} else if (currentSection) {
|
||||
sectionContent.push(line);
|
||||
}
|
||||
}
|
||||
|
||||
if (currentSection) {
|
||||
sections.set(currentSection, {
|
||||
start: sectionStart,
|
||||
end: lines.length - 1,
|
||||
content: sectionContent.join('\n'),
|
||||
});
|
||||
}
|
||||
|
||||
const learnedSection = sections.get('LEARNED') || sections.get('Learned');
|
||||
const hasLearnedSection = !!learnedSection;
|
||||
|
||||
return {
|
||||
content,
|
||||
sections,
|
||||
hasLearnedSection,
|
||||
learnedSectionContent: learnedSection?.content,
|
||||
learnedSectionRange: learnedSection
|
||||
? { start: learnedSection.start, end: learnedSection.end }
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get learnings to add to CLAUDE.md
|
||||
*/
|
||||
getLearningsForClaudeMd(options: ClaudeMdUpdateOptions = {}): Learning[] {
|
||||
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
|
||||
|
||||
const projectStore = new LearningStore('project', this.projectPath);
|
||||
let learnings = projectStore.getAll();
|
||||
|
||||
if (opts.includeGlobal) {
|
||||
const globalStore = new LearningStore('global');
|
||||
learnings = [...learnings, ...globalStore.getAll()];
|
||||
}
|
||||
|
||||
return learnings
|
||||
.filter((l) => (l.effectiveness ?? 0) >= opts.minEffectiveness || l.useCount >= 3)
|
||||
.sort((a, b) => {
|
||||
const scoreA = (a.effectiveness ?? 50) + a.useCount * 5;
|
||||
const scoreB = (b.effectiveness ?? 50) + b.useCount * 5;
|
||||
return scoreB - scoreA;
|
||||
})
|
||||
.slice(0, opts.maxLearnings);
|
||||
}
|
||||
|
||||
/**
|
||||
* Format learnings as CLAUDE.md LEARNED section
|
||||
*/
|
||||
formatLearnedSection(learnings: Learning[], options: ClaudeMdUpdateOptions = {}): string {
|
||||
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push(`## ${opts.sectionTitle}`);
|
||||
lines.push('');
|
||||
lines.push(SKILLKIT_MARKER);
|
||||
|
||||
if (opts.addTimestamp) {
|
||||
lines.push(`<!-- Last updated: ${new Date().toISOString()} -->`);
|
||||
}
|
||||
|
||||
lines.push('');
|
||||
|
||||
const byCategory = this.categorizeLearnings(learnings);
|
||||
|
||||
for (const [category, categoryLearnings] of byCategory) {
|
||||
if (categoryLearnings.length > 0) {
|
||||
lines.push(`### ${category}`);
|
||||
|
||||
for (const learning of categoryLearnings) {
|
||||
const title = this.formatLearningTitle(learning);
|
||||
const summary = this.extractSummary(learning.content);
|
||||
lines.push(`${title}`);
|
||||
lines.push(summary);
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Update CLAUDE.md with learnings
|
||||
*/
|
||||
update(options: ClaudeMdUpdateOptions = {}): ClaudeMdUpdateResult {
|
||||
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
|
||||
const learnings = this.getLearningsForClaudeMd(opts);
|
||||
|
||||
if (learnings.length === 0) {
|
||||
return {
|
||||
updated: false,
|
||||
path: this.claudeMdPath,
|
||||
learningsAdded: 0,
|
||||
learningSummaries: [],
|
||||
previousLearnings: 0,
|
||||
};
|
||||
}
|
||||
|
||||
const parsed = this.parse();
|
||||
const newSection = this.formatLearnedSection(learnings, opts);
|
||||
|
||||
let newContent: string;
|
||||
let previousLearnings = 0;
|
||||
|
||||
if (parsed.hasLearnedSection && parsed.learnedSectionRange) {
|
||||
if (opts.preserveManualEntries) {
|
||||
const existingContent = parsed.learnedSectionContent || '';
|
||||
const manualEntries = this.extractManualEntries(existingContent);
|
||||
previousLearnings = this.countLearnings(existingContent);
|
||||
|
||||
const combinedSection = this.combineWithManualEntries(newSection, manualEntries);
|
||||
|
||||
const lines = parsed.content.split('\n');
|
||||
const before = lines.slice(0, parsed.learnedSectionRange.start).join('\n');
|
||||
const after = lines.slice(parsed.learnedSectionRange.end + 1).join('\n');
|
||||
|
||||
newContent = before + (before ? '\n' : '') + combinedSection + (after ? '\n' + after : '');
|
||||
} else {
|
||||
const lines = parsed.content.split('\n');
|
||||
const before = lines.slice(0, parsed.learnedSectionRange.start).join('\n');
|
||||
const after = lines.slice(parsed.learnedSectionRange.end + 1).join('\n');
|
||||
|
||||
newContent = before + (before ? '\n' : '') + newSection + (after ? '\n' + after : '');
|
||||
}
|
||||
} else if (parsed.content) {
|
||||
newContent = parsed.content + '\n\n' + newSection;
|
||||
} else {
|
||||
newContent = this.createNewClaudeMd(newSection);
|
||||
}
|
||||
|
||||
const dir = dirname(this.claudeMdPath);
|
||||
if (!existsSync(dir)) {
|
||||
mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
|
||||
writeFileSync(this.claudeMdPath, newContent, 'utf-8');
|
||||
|
||||
return {
|
||||
updated: true,
|
||||
path: this.claudeMdPath,
|
||||
learningsAdded: learnings.length,
|
||||
learningSummaries: learnings.map((l) => l.title),
|
||||
previousLearnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Preview update without writing
|
||||
*/
|
||||
preview(options: ClaudeMdUpdateOptions = {}): {
|
||||
learnings: Learning[];
|
||||
formattedSection: string;
|
||||
wouldUpdate: boolean;
|
||||
} {
|
||||
const learnings = this.getLearningsForClaudeMd(options);
|
||||
const formattedSection = this.formatLearnedSection(learnings, options);
|
||||
|
||||
return {
|
||||
learnings,
|
||||
formattedSection,
|
||||
wouldUpdate: learnings.length > 0,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if CLAUDE.md exists
|
||||
*/
|
||||
exists(): boolean {
|
||||
return existsSync(this.claudeMdPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get CLAUDE.md path
|
||||
*/
|
||||
getPath(): string {
|
||||
return this.claudeMdPath;
|
||||
}
|
||||
|
||||
private categorizeLearnings(learnings: Learning[]): Map<string, Learning[]> {
|
||||
const categories = new Map<string, Learning[]>();
|
||||
|
||||
for (const learning of learnings) {
|
||||
let category = 'General';
|
||||
|
||||
if (learning.patterns?.includes('error-handling')) {
|
||||
category = 'Error-Handling';
|
||||
} else if (learning.patterns?.includes('debugging')) {
|
||||
category = 'Debugging';
|
||||
} else if (learning.patterns?.includes('architecture')) {
|
||||
category = 'Architecture';
|
||||
} else if (learning.patterns?.includes('workflow')) {
|
||||
category = 'Workflow';
|
||||
} else if (learning.tags.some((t) => t.includes('react') || t.includes('typescript'))) {
|
||||
category = 'Code-Patterns';
|
||||
}
|
||||
|
||||
const existing = categories.get(category) || [];
|
||||
existing.push(learning);
|
||||
categories.set(category, existing);
|
||||
}
|
||||
|
||||
return categories;
|
||||
}
|
||||
|
||||
private formatLearningTitle(learning: Learning): string {
|
||||
const tags = learning.tags.slice(0, 3).join(', ');
|
||||
return tags ? `**${tags}**: ${learning.title}` : `**${learning.title}**`;
|
||||
}
|
||||
|
||||
private extractSummary(content: string): string {
|
||||
const lines = content.split('\n').filter((l) => l.trim());
|
||||
|
||||
for (const line of lines) {
|
||||
const cleaned = line.replace(/^#+\s*/, '').replace(/^\*\*.*?\*\*:?\s*/, '');
|
||||
if (cleaned.length > 20 && !cleaned.startsWith('#')) {
|
||||
return cleaned.slice(0, 200) + (cleaned.length > 200 ? '...' : '');
|
||||
}
|
||||
}
|
||||
|
||||
return content.slice(0, 200) + (content.length > 200 ? '...' : '');
|
||||
}
|
||||
|
||||
private extractManualEntries(sectionContent: string): string[] {
|
||||
const lines = sectionContent.split('\n');
|
||||
const manualEntries: string[] = [];
|
||||
let inManualEntry = false;
|
||||
let currentEntry: string[] = [];
|
||||
|
||||
for (const line of lines) {
|
||||
if (line.includes(SKILLKIT_MARKER)) {
|
||||
inManualEntry = false;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (line.startsWith('### ') && !line.includes('Auto-populated')) {
|
||||
if (currentEntry.length > 0) {
|
||||
manualEntries.push(currentEntry.join('\n'));
|
||||
}
|
||||
inManualEntry = true;
|
||||
currentEntry = [line];
|
||||
} else if (inManualEntry) {
|
||||
currentEntry.push(line);
|
||||
}
|
||||
}
|
||||
|
||||
if (currentEntry.length > 0) {
|
||||
manualEntries.push(currentEntry.join('\n'));
|
||||
}
|
||||
|
||||
return manualEntries.filter((e) => e.trim().length > 0);
|
||||
}
|
||||
|
||||
private combineWithManualEntries(autoSection: string, manualEntries: string[]): string {
|
||||
if (manualEntries.length === 0) {
|
||||
return autoSection;
|
||||
}
|
||||
|
||||
const lines = autoSection.split('\n');
|
||||
const combinedLines = [...lines];
|
||||
|
||||
combinedLines.push('');
|
||||
combinedLines.push('### Manual Entries');
|
||||
combinedLines.push('<!-- Preserved from previous edits -->');
|
||||
combinedLines.push('');
|
||||
|
||||
for (const entry of manualEntries) {
|
||||
combinedLines.push(entry);
|
||||
combinedLines.push('');
|
||||
}
|
||||
|
||||
return combinedLines.join('\n');
|
||||
}
|
||||
|
||||
private countLearnings(content: string): number {
|
||||
const matches = content.match(/^\*\*[^*]+\*\*/gm);
|
||||
return matches ? matches.length : 0;
|
||||
}
|
||||
|
||||
private createNewClaudeMd(learnedSection: string): string {
|
||||
const projectName = basename(this.projectPath) || 'Project';
|
||||
|
||||
return `# ${projectName}
|
||||
|
||||
${learnedSection}
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a CLAUDE.md updater
|
||||
*/
|
||||
export function createClaudeMdUpdater(
|
||||
projectPath: string,
|
||||
claudeMdPath?: string
|
||||
): ClaudeMdUpdater {
|
||||
return new ClaudeMdUpdater(projectPath, claudeMdPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Update CLAUDE.md with learnings (standalone function)
|
||||
*/
|
||||
export function updateClaudeMd(
|
||||
projectPath: string,
|
||||
options: ClaudeMdUpdateOptions = {}
|
||||
): ClaudeMdUpdateResult {
|
||||
const updater = new ClaudeMdUpdater(projectPath);
|
||||
return updater.update(options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Sync global CLAUDE.md with global learnings
|
||||
*/
|
||||
export function syncGlobalClaudeMd(options: ClaudeMdUpdateOptions = {}): ClaudeMdUpdateResult {
|
||||
const globalClaudeMdPath = join(homedir(), '.claude', 'CLAUDE.md');
|
||||
const updater = new ClaudeMdUpdater(homedir(), globalClaudeMdPath);
|
||||
|
||||
const globalOpts: ClaudeMdUpdateOptions = {
|
||||
...options,
|
||||
includeGlobal: true,
|
||||
sectionTitle: 'Global Learnings',
|
||||
};
|
||||
|
||||
return updater.update(globalOpts);
|
||||
}
|
||||
@@ -95,7 +95,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
): Promise<CompressionResult> {
|
||||
const opts = { ...DEFAULT_COMPRESSION_OPTIONS, ...options };
|
||||
|
||||
// Filter observations
|
||||
const filtered = opts.includeLowRelevance
|
||||
? observations
|
||||
: observations.filter((o) => o.relevance >= 50);
|
||||
@@ -116,36 +115,29 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
const learnings: CompressedLearning[] = [];
|
||||
const processedIds: string[] = [];
|
||||
|
||||
// Group observations by type
|
||||
const byType = this.groupByType(filtered);
|
||||
|
||||
// Extract error-solution pairs
|
||||
const errorSolutionLearnings = this.extractErrorSolutionPairs(byType, opts);
|
||||
learnings.push(...errorSolutionLearnings.learnings);
|
||||
processedIds.push(...errorSolutionLearnings.processedIds);
|
||||
|
||||
// Extract decision patterns
|
||||
const decisionLearnings = this.extractDecisionPatterns(byType, opts);
|
||||
learnings.push(...decisionLearnings.learnings);
|
||||
processedIds.push(...decisionLearnings.processedIds);
|
||||
|
||||
// Extract file change patterns
|
||||
const fileChangeLearnings = this.extractFileChangePatterns(byType, opts);
|
||||
learnings.push(...fileChangeLearnings.learnings);
|
||||
processedIds.push(...fileChangeLearnings.processedIds);
|
||||
|
||||
// Extract tool usage patterns
|
||||
const toolUsageLearnings = this.extractToolUsagePatterns(byType, opts);
|
||||
learnings.push(...toolUsageLearnings.learnings);
|
||||
processedIds.push(...toolUsageLearnings.processedIds);
|
||||
|
||||
// Filter by importance and limit
|
||||
const finalLearnings = learnings
|
||||
.filter((l) => l.importance >= opts.minImportance)
|
||||
.sort((a, b) => b.importance - a.importance)
|
||||
.slice(0, opts.maxLearnings);
|
||||
|
||||
// Add additional tags
|
||||
if (opts.additionalTags.length > 0) {
|
||||
for (const learning of finalLearnings) {
|
||||
learning.tags = [...new Set([...learning.tags, ...opts.additionalTags])];
|
||||
@@ -187,7 +179,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
const learnings: CompressedLearning[] = [];
|
||||
const processedIds: string[] = [];
|
||||
|
||||
// Match errors with solutions
|
||||
for (const error of errors) {
|
||||
const errorText = error.content.error || error.content.action;
|
||||
const matchingSolution = solutions.find((s) => {
|
||||
@@ -195,21 +186,18 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
const solutionAction = s.content.action?.toLowerCase() || '';
|
||||
const errorLower = errorText.toLowerCase();
|
||||
|
||||
// Require keyword similarity between error and solution
|
||||
const hasKeywordMatch = this.hasSimilarKeywords(errorLower, solutionContext) ||
|
||||
this.hasSimilarKeywords(errorLower, solutionAction);
|
||||
if (!hasKeywordMatch) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Solution should indicate it's a fix/resolution, or have strong keyword overlap
|
||||
const isSolutionIndicator = solutionContext.includes('fix') ||
|
||||
solutionContext.includes('resolve') ||
|
||||
solutionContext.includes('solution') ||
|
||||
solutionAction.includes('fix') ||
|
||||
solutionAction.includes('resolve');
|
||||
|
||||
// Require both keyword match AND solution indicator
|
||||
return isSolutionIndicator || this.hasStrongKeywordOverlap(errorLower, solutionContext);
|
||||
});
|
||||
|
||||
@@ -230,7 +218,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
|
||||
processedIds.push(error.id, matchingSolution.id);
|
||||
} else if (error.content.error) {
|
||||
// Standalone error learning
|
||||
const title = this.generateTitle('Error Pattern', errorText);
|
||||
const content = this.formatStandaloneErrorContent(error);
|
||||
const tags = this.extractTags([error]);
|
||||
@@ -249,7 +236,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
}
|
||||
}
|
||||
|
||||
// Process remaining solutions
|
||||
for (const solution of solutions) {
|
||||
if (!processedIds.includes(solution.id)) {
|
||||
const title = this.generateTitle('Solution', solution.content.action);
|
||||
@@ -310,7 +296,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
const learnings: CompressedLearning[] = [];
|
||||
const processedIds: string[] = [];
|
||||
|
||||
// Group file changes by pattern (same files modified together)
|
||||
const filePatterns = new Map<string, Observation[]>();
|
||||
for (const change of fileChanges) {
|
||||
const files = change.content.files || [];
|
||||
@@ -320,7 +305,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
filePatterns.set(pattern, existing);
|
||||
}
|
||||
|
||||
// Create learnings for significant patterns (2+ occurrences)
|
||||
for (const [pattern, changes] of filePatterns) {
|
||||
if (changes.length >= 2 || changes.some((c) => (c.content.files?.length || 0) > 3)) {
|
||||
const title = `File Modification Pattern: ${pattern}`;
|
||||
@@ -353,10 +337,8 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
const learnings: CompressedLearning[] = [];
|
||||
const processedIds: string[] = [];
|
||||
|
||||
// Only extract if there are significant patterns
|
||||
const allObs = [...toolUses, ...checkpoints];
|
||||
if (allObs.length >= 5) {
|
||||
// Group by common action patterns
|
||||
const actionPatterns = new Map<string, Observation[]>();
|
||||
for (const obs of allObs) {
|
||||
const actionType = this.getActionType(obs.content.action);
|
||||
@@ -390,7 +372,6 @@ export class RuleBasedCompressor implements CompressionEngine {
|
||||
}
|
||||
|
||||
private generateTitle(prefix: string, text: string): string {
|
||||
// Extract key words from text
|
||||
const cleaned = text
|
||||
.replace(/[^a-zA-Z0-9\s]/g, ' ')
|
||||
.replace(/\s+/g, ' ')
|
||||
@@ -534,7 +515,6 @@ Consider automating or documenting this workflow for future reference.
|
||||
private getFilePattern(files: string[]): string {
|
||||
if (files.length === 0) return 'unknown';
|
||||
|
||||
// Extract common directory
|
||||
const dirs = files.map((f) => {
|
||||
const parts = f.split('/');
|
||||
return parts.slice(0, -1).join('/') || 'root';
|
||||
@@ -545,7 +525,6 @@ Consider automating or documenting this workflow for future reference.
|
||||
return uniqueDirs[0];
|
||||
}
|
||||
|
||||
// Extract file types
|
||||
const extensions = files.map((f) => {
|
||||
const ext = f.split('.').pop() || 'unknown';
|
||||
return ext;
|
||||
@@ -568,7 +547,6 @@ Consider automating or documenting this workflow for future reference.
|
||||
}
|
||||
|
||||
private hasSimilarKeywords(text1: string, text2: string): boolean {
|
||||
// Normalize: lowercase and strip punctuation for better matching
|
||||
const normalize = (word: string) => word.toLowerCase().replace(/[^a-z0-9]/g, '');
|
||||
const words1 = text1.split(/\s+/).map(normalize).filter((w) => w.length > 3);
|
||||
const words2 = new Set(text2.split(/\s+/).map(normalize).filter((w) => w.length > 3));
|
||||
@@ -580,7 +558,6 @@ Consider automating or documenting this workflow for future reference.
|
||||
* More strict than hasSimilarKeywords - requires at least 2 matching words
|
||||
*/
|
||||
private hasStrongKeywordOverlap(text1: string, text2: string): boolean {
|
||||
// Normalize: lowercase and strip punctuation for better matching
|
||||
const normalize = (word: string) => word.toLowerCase().replace(/[^a-z0-9]/g, '');
|
||||
const words1 = text1.split(/\s+/).map(normalize).filter((w) => w.length > 3);
|
||||
const words2 = new Set(text2.split(/\s+/).map(normalize).filter((w) => w.length > 3));
|
||||
@@ -625,7 +602,6 @@ export class APIBasedCompressor implements CompressionEngine {
|
||||
): Promise<CompressionResult> {
|
||||
const opts = { ...DEFAULT_COMPRESSION_OPTIONS, ...options };
|
||||
|
||||
// Filter observations
|
||||
const filtered = opts.includeLowRelevance
|
||||
? observations
|
||||
: observations.filter((o) => o.relevance >= 50);
|
||||
@@ -643,26 +619,18 @@ export class APIBasedCompressor implements CompressionEngine {
|
||||
};
|
||||
}
|
||||
|
||||
// Format observations for the prompt
|
||||
const observationsText = this.formatObservationsForPrompt(filtered);
|
||||
|
||||
// Build the prompt
|
||||
const prompt = this.buildCompressionPrompt(observationsText, opts);
|
||||
|
||||
try {
|
||||
// Call the API
|
||||
const response = await this.callAPI(prompt);
|
||||
|
||||
// Parse the response
|
||||
const learnings = this.parseAPIResponse(response, filtered);
|
||||
|
||||
// Filter and limit
|
||||
const finalLearnings = learnings
|
||||
.filter((l) => l.importance >= opts.minImportance)
|
||||
.sort((a, b) => b.importance - a.importance)
|
||||
.slice(0, opts.maxLearnings);
|
||||
|
||||
// Add additional tags
|
||||
if (opts.additionalTags.length > 0) {
|
||||
for (const learning of finalLearnings) {
|
||||
learning.tags = [...new Set([...learning.tags, ...opts.additionalTags])];
|
||||
@@ -686,7 +654,6 @@ export class APIBasedCompressor implements CompressionEngine {
|
||||
},
|
||||
};
|
||||
} catch (error) {
|
||||
// Fall back to rule-based compression on API failure
|
||||
console.warn('API compression failed, falling back to rule-based:', error);
|
||||
const fallback = new RuleBasedCompressor();
|
||||
return fallback.compress(observations, options);
|
||||
@@ -820,7 +787,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
|
||||
|
||||
private parseAPIResponse(response: string, observations: Observation[]): CompressedLearning[] {
|
||||
try {
|
||||
// Extract JSON from response (handle markdown code blocks)
|
||||
let jsonStr = response;
|
||||
const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
|
||||
if (jsonMatch) {
|
||||
@@ -833,7 +799,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
|
||||
throw new Error('Response is not an array');
|
||||
}
|
||||
|
||||
// Validate and clean up each learning
|
||||
const observationIds = new Set(observations.map((o) => o.id));
|
||||
return parsed
|
||||
.filter((item): item is CompressedLearning => {
|
||||
@@ -847,7 +812,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
|
||||
})
|
||||
.map((item) => ({
|
||||
...item,
|
||||
// Validate source observation IDs
|
||||
sourceObservationIds: (item.sourceObservationIds || []).filter((id: string) =>
|
||||
observationIds.has(id)
|
||||
),
|
||||
@@ -884,7 +848,6 @@ export class MemoryCompressor {
|
||||
projectPath,
|
||||
options?.projectName
|
||||
);
|
||||
// For global scope, use home directory; for project scope, use project path
|
||||
const indexBasePath = options?.scope === 'global' ? homedir() : projectPath;
|
||||
this.indexStore = new MemoryIndexStore(indexBasePath, options?.scope === 'global');
|
||||
this.projectName = options?.projectName;
|
||||
@@ -926,10 +889,8 @@ export class MemoryCompressor {
|
||||
projectName: this.projectName || options?.projectName,
|
||||
};
|
||||
|
||||
// Compress observations
|
||||
const result = await this.engine.compress(observations, compressionOptions);
|
||||
|
||||
// Store each learning
|
||||
const storedLearnings: Learning[] = [];
|
||||
for (const compressed of result.learnings) {
|
||||
const learning = this.learningStore.add({
|
||||
@@ -942,7 +903,6 @@ export class MemoryCompressor {
|
||||
patterns: compressed.patterns,
|
||||
});
|
||||
|
||||
// Index the learning
|
||||
this.indexStore.indexLearning(learning);
|
||||
|
||||
storedLearnings.push(learning);
|
||||
@@ -1004,12 +964,10 @@ export class LearningConsolidator {
|
||||
* Merge two similar learnings
|
||||
*/
|
||||
merge(learning1: Learning, learning2: Learning): Omit<Learning, 'id' | 'createdAt' | 'updatedAt'> {
|
||||
// Keep the more effective/used one as base
|
||||
const base = this.getBetterLearning(learning1, learning2);
|
||||
const other = base === learning1 ? learning2 : learning1;
|
||||
|
||||
return {
|
||||
// Preserve the source from the base learning instead of hard-coding 'session'
|
||||
source: base.source,
|
||||
sourceObservations: [
|
||||
...(base.sourceObservations || []),
|
||||
@@ -1046,14 +1004,11 @@ export class LearningConsolidator {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Merge the learnings
|
||||
const merged = this.merge(l1, l2);
|
||||
|
||||
// Add the merged learning
|
||||
const newLearning = store.add(merged);
|
||||
index.indexLearning(newLearning);
|
||||
|
||||
// Remove the old learnings
|
||||
store.delete(l1.id);
|
||||
store.delete(l2.id);
|
||||
index.removeLearning(l1.id);
|
||||
@@ -1073,14 +1028,12 @@ export class LearningConsolidator {
|
||||
private calculateSimilarity(l1: Learning, l2: Learning): number {
|
||||
let score = 0;
|
||||
|
||||
// Title similarity (Jaccard)
|
||||
const title1Words = new Set(l1.title.toLowerCase().split(/\s+/));
|
||||
const title2Words = new Set(l2.title.toLowerCase().split(/\s+/));
|
||||
const titleIntersection = [...title1Words].filter((w) => title2Words.has(w)).length;
|
||||
const titleUnion = new Set([...title1Words, ...title2Words]).size;
|
||||
score += (titleIntersection / titleUnion) * 0.3;
|
||||
|
||||
// Tag overlap
|
||||
const tags1 = new Set(l1.tags);
|
||||
const tags2 = new Set(l2.tags);
|
||||
const tagIntersection = [...tags1].filter((t) => tags2.has(t)).length;
|
||||
@@ -1089,7 +1042,6 @@ export class LearningConsolidator {
|
||||
score += (tagIntersection / tagUnion) * 0.3;
|
||||
}
|
||||
|
||||
// Pattern overlap
|
||||
const patterns1 = new Set(l1.patterns || []);
|
||||
const patterns2 = new Set(l2.patterns || []);
|
||||
const patternIntersection = [...patterns1].filter((p) => patterns2.has(p)).length;
|
||||
@@ -1098,7 +1050,6 @@ export class LearningConsolidator {
|
||||
score += (patternIntersection / patternUnion) * 0.2;
|
||||
}
|
||||
|
||||
// Content similarity (simple word overlap)
|
||||
const content1Words = new Set(
|
||||
l1.content
|
||||
.toLowerCase()
|
||||
@@ -1121,20 +1072,16 @@ export class LearningConsolidator {
|
||||
}
|
||||
|
||||
private getBetterLearning(l1: Learning, l2: Learning): Learning {
|
||||
// Prefer higher effectiveness
|
||||
if (l1.effectiveness !== l2.effectiveness) {
|
||||
return (l1.effectiveness || 0) > (l2.effectiveness || 0) ? l1 : l2;
|
||||
}
|
||||
// Prefer higher use count
|
||||
if (l1.useCount !== l2.useCount) {
|
||||
return l1.useCount > l2.useCount ? l1 : l2;
|
||||
}
|
||||
// Prefer more recent
|
||||
return new Date(l1.updatedAt) > new Date(l2.updatedAt) ? l1 : l2;
|
||||
}
|
||||
|
||||
private mergeContent(content1: string, content2: string): string {
|
||||
// Simple merge: keep the longer one and add a note
|
||||
if (content1.length >= content2.length) {
|
||||
return content1;
|
||||
}
|
||||
|
||||
@@ -39,30 +39,23 @@ export class MemoryEnabledEngine {
|
||||
private userProgressCallback?: ExecutionProgressCallback;
|
||||
|
||||
constructor(projectPath: string, options: MemoryEnabledEngineOptions = {}) {
|
||||
// Create memory observer
|
||||
this.observer = new MemoryObserver(projectPath, options.sessionId, options.memoryConfig);
|
||||
|
||||
// Set default agent if provided
|
||||
if (options.defaultAgent) {
|
||||
this.observer.setAgent(options.defaultAgent);
|
||||
}
|
||||
|
||||
// Store user's progress callback
|
||||
this.userProgressCallback = options.onProgress;
|
||||
|
||||
// Create the combined progress callback
|
||||
const combinedProgressCallback: ExecutionProgressCallback = (event: ExecutionProgressEvent) => {
|
||||
// Forward to memory observer
|
||||
const observerCallback = this.observer.createProgressCallback();
|
||||
observerCallback(event);
|
||||
|
||||
// Forward to user's callback if provided
|
||||
if (this.userProgressCallback) {
|
||||
this.userProgressCallback(event);
|
||||
}
|
||||
};
|
||||
|
||||
// Create the underlying engine with the combined callback
|
||||
this.engine = createExecutionEngine(projectPath, {
|
||||
checkpointHandler: options.checkpointHandler,
|
||||
onProgress: combinedProgressCallback,
|
||||
@@ -76,22 +69,17 @@ export class MemoryEnabledEngine {
|
||||
skill: ExecutableSkill,
|
||||
options: ExecutionOptions = {}
|
||||
): ReturnType<SkillExecutionEngine['execute']> {
|
||||
// Set skill name in observer
|
||||
this.observer.setSkillName(skill.name);
|
||||
|
||||
// Set agent if provided in options
|
||||
if (options.agent) {
|
||||
this.observer.setAgent(options.agent);
|
||||
}
|
||||
|
||||
// Record execution start
|
||||
this.observer.recordExecutionStart(skill.name, options.agent || 'claude-code');
|
||||
|
||||
try {
|
||||
// Execute the skill
|
||||
const result = await this.engine.execute(skill, options);
|
||||
|
||||
// Record file modifications from result
|
||||
if (result.filesModified.length > 0) {
|
||||
this.observer.recordFileModification(
|
||||
result.filesModified,
|
||||
@@ -99,14 +87,12 @@ export class MemoryEnabledEngine {
|
||||
);
|
||||
}
|
||||
|
||||
// Record any errors
|
||||
if (result.error) {
|
||||
this.observer.recordError(result.error, `Skill "${skill.name}" failed`);
|
||||
}
|
||||
|
||||
return result;
|
||||
} catch (error) {
|
||||
// Record unexpected errors
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
this.observer.recordError(errorMessage, `Unexpected error during skill "${skill.name}" execution`);
|
||||
throw error;
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
/**
|
||||
* Memory Hooks Module
|
||||
*
|
||||
* Provides Claude Code lifecycle hooks for automatic memory capture
|
||||
* and injection at key session lifecycle events.
|
||||
*/
|
||||
|
||||
export * from './types.js';
|
||||
export {
|
||||
SessionStartHook,
|
||||
createSessionStartHook,
|
||||
executeSessionStartHook,
|
||||
} from './session-start.js';
|
||||
export {
|
||||
PostToolUseHook,
|
||||
createPostToolUseHook,
|
||||
executePostToolUseHook,
|
||||
} from './post-tool-use.js';
|
||||
export {
|
||||
SessionEndHook,
|
||||
createSessionEndHook,
|
||||
executeSessionEndHook,
|
||||
} from './session-end.js';
|
||||
export {
|
||||
MemoryHookManager,
|
||||
createMemoryHookManager,
|
||||
} from './manager.js';
|
||||
@@ -0,0 +1,286 @@
|
||||
/**
|
||||
* Memory Hook Manager
|
||||
*
|
||||
* Unified manager for all memory lifecycle hooks.
|
||||
* Provides a single interface for session memory management.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../../types.js';
|
||||
import type { Learning, Observation } from '../types.js';
|
||||
import type {
|
||||
MemoryHookConfig,
|
||||
MemoryHookStats,
|
||||
SessionStartContext,
|
||||
SessionEndContext,
|
||||
ToolUseEvent,
|
||||
ClaudeCodeHookOutput,
|
||||
} from './types.js';
|
||||
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
|
||||
import { SessionStartHook } from './session-start.js';
|
||||
import { PostToolUseHook } from './post-tool-use.js';
|
||||
import { SessionEndHook } from './session-end.js';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
|
||||
/**
|
||||
* Memory Hook Manager
|
||||
*
|
||||
* Coordinates all memory hooks for a session.
|
||||
*/
|
||||
export class MemoryHookManager {
|
||||
private config: MemoryHookConfig;
|
||||
private projectPath: string;
|
||||
private agent: AgentType;
|
||||
private sessionId: string;
|
||||
private startedAt: string;
|
||||
|
||||
private sessionStartHook: SessionStartHook;
|
||||
private postToolUseHook: PostToolUseHook;
|
||||
private sessionEndHook: SessionEndHook;
|
||||
|
||||
private stats: MemoryHookStats;
|
||||
|
||||
constructor(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {},
|
||||
sessionId?: string
|
||||
) {
|
||||
this.projectPath = projectPath;
|
||||
this.agent = agent;
|
||||
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
|
||||
this.sessionId = sessionId || randomUUID();
|
||||
this.startedAt = new Date().toISOString();
|
||||
|
||||
this.sessionStartHook = new SessionStartHook(projectPath, agent, this.config);
|
||||
this.postToolUseHook = new PostToolUseHook(projectPath, agent, this.config, this.sessionId);
|
||||
this.sessionEndHook = new SessionEndHook(projectPath, agent, this.config);
|
||||
|
||||
this.stats = {
|
||||
sessionId: this.sessionId,
|
||||
startedAt: this.startedAt,
|
||||
observationsCaptured: 0,
|
||||
learningsInjected: 0,
|
||||
tokensUsed: 0,
|
||||
toolCallsCaptured: 0,
|
||||
errorsRecorded: 0,
|
||||
solutionsRecorded: 0,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle session start
|
||||
*/
|
||||
async onSessionStart(workingDirectory?: string): Promise<ClaudeCodeHookOutput> {
|
||||
const context: SessionStartContext = {
|
||||
session_id: this.sessionId,
|
||||
project_path: this.projectPath,
|
||||
agent: this.agent,
|
||||
timestamp: new Date().toISOString(),
|
||||
working_directory: workingDirectory,
|
||||
};
|
||||
|
||||
const result = await this.sessionStartHook.execute(context);
|
||||
|
||||
this.stats.learningsInjected = result.learnings.length;
|
||||
this.stats.tokensUsed = result.tokenCount;
|
||||
|
||||
return this.sessionStartHook.generateHookOutputFromResult(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle tool use
|
||||
*/
|
||||
async onToolUse(event: ToolUseEvent): Promise<ClaudeCodeHookOutput> {
|
||||
const result = await this.postToolUseHook.execute(event);
|
||||
|
||||
if (result.captured) {
|
||||
this.stats.observationsCaptured++;
|
||||
this.stats.toolCallsCaptured++;
|
||||
|
||||
if (result.observation?.type === 'error') {
|
||||
this.stats.errorsRecorded++;
|
||||
} else if (result.observation?.type === 'solution') {
|
||||
this.stats.solutionsRecorded++;
|
||||
}
|
||||
}
|
||||
|
||||
await this.checkAutoCompression();
|
||||
|
||||
return this.postToolUseHook.generateHookOutputFromResult(event, result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle session end
|
||||
*/
|
||||
async onSessionEnd(toolCallsCount?: number): Promise<ClaudeCodeHookOutput> {
|
||||
const context: SessionEndContext = {
|
||||
session_id: this.sessionId,
|
||||
project_path: this.projectPath,
|
||||
agent: this.agent,
|
||||
timestamp: new Date().toISOString(),
|
||||
duration_ms: Date.now() - new Date(this.startedAt).getTime(),
|
||||
tool_calls_count: toolCallsCount,
|
||||
};
|
||||
|
||||
const result = await this.sessionEndHook.execute(context);
|
||||
|
||||
return this.sessionEndHook.generateHookOutputFromResult(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Record an error manually
|
||||
*/
|
||||
recordError(error: string, context: string): Observation {
|
||||
const obs = this.postToolUseHook.recordError(error, context);
|
||||
this.stats.observationsCaptured++;
|
||||
this.stats.errorsRecorded++;
|
||||
return obs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record a solution manually
|
||||
*/
|
||||
recordSolution(solution: string, context: string, relatedError?: string): Observation {
|
||||
const obs = this.postToolUseHook.recordSolution(solution, context, relatedError);
|
||||
this.stats.observationsCaptured++;
|
||||
this.stats.solutionsRecorded++;
|
||||
return obs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record a decision manually
|
||||
*/
|
||||
recordDecision(decision: string, options: string[], context: string): Observation {
|
||||
const obs = this.postToolUseHook.recordDecision(decision, options, context);
|
||||
this.stats.observationsCaptured++;
|
||||
return obs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record file changes manually
|
||||
*/
|
||||
recordFileChange(files: string[], action: string, context: string): Observation {
|
||||
const obs = this.postToolUseHook.recordFileChange(files, action, context);
|
||||
this.stats.observationsCaptured++;
|
||||
return obs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Force compression (regardless of threshold)
|
||||
*/
|
||||
async forceCompress(): Promise<Learning[]> {
|
||||
const result = await this.sessionEndHook.forceCompress(this.sessionId);
|
||||
return result.learnings;
|
||||
}
|
||||
|
||||
/**
|
||||
* Preview compression without executing
|
||||
*/
|
||||
async previewCompression(): Promise<{
|
||||
wouldCompress: boolean;
|
||||
observationCount: number;
|
||||
estimatedLearnings: number;
|
||||
observationTypes: Record<string, number>;
|
||||
}> {
|
||||
return this.sessionEndHook.preview(this.sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current stats
|
||||
*/
|
||||
getStats(): MemoryHookStats {
|
||||
return { ...this.stats };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get session ID
|
||||
*/
|
||||
getSessionId(): string {
|
||||
return this.sessionId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get observation count
|
||||
*/
|
||||
getObservationCount(): number {
|
||||
return this.postToolUseHook.getObservationCount();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get pending errors
|
||||
*/
|
||||
getPendingErrors(): Array<{ error: string; timestamp: string }> {
|
||||
return this.postToolUseHook.getPendingErrors();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get configuration
|
||||
*/
|
||||
getConfig(): MemoryHookConfig {
|
||||
return { ...this.config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update configuration
|
||||
*/
|
||||
setConfig(config: Partial<MemoryHookConfig>): void {
|
||||
this.config = { ...this.config, ...config };
|
||||
this.sessionStartHook.setConfig(this.config);
|
||||
this.postToolUseHook.setConfig(this.config);
|
||||
this.sessionEndHook.setConfig(this.config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if auto-compression should trigger
|
||||
*/
|
||||
private async checkAutoCompression(): Promise<void> {
|
||||
if (!this.config.enabled) return;
|
||||
|
||||
const count = this.postToolUseHook.getObservationCount();
|
||||
if (count >= this.config.compressionThreshold) {
|
||||
await this.sessionEndHook.forceCompress(this.sessionId);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code hooks.json configuration
|
||||
*/
|
||||
generateClaudeCodeHooksConfig(): Record<string, unknown> {
|
||||
return {
|
||||
hooks: [
|
||||
{
|
||||
matcher: '.*',
|
||||
hooks: [
|
||||
{
|
||||
type: 'command',
|
||||
command: `npx skillkit memory hook session-start --project "${this.projectPath}"`,
|
||||
event: 'SessionStart',
|
||||
},
|
||||
{
|
||||
type: 'command',
|
||||
command: `npx skillkit memory hook post-tool-use --project "${this.projectPath}"`,
|
||||
event: 'PostToolUse',
|
||||
},
|
||||
{
|
||||
type: 'command',
|
||||
command: `npx skillkit memory hook session-end --project "${this.projectPath}"`,
|
||||
event: 'SessionEnd',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a memory hook manager
|
||||
*/
|
||||
export function createMemoryHookManager(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {},
|
||||
sessionId?: string
|
||||
): MemoryHookManager {
|
||||
return new MemoryHookManager(projectPath, agent, config, sessionId);
|
||||
}
|
||||
@@ -0,0 +1,442 @@
|
||||
/**
|
||||
* Post Tool Use Hook
|
||||
*
|
||||
* Captures tool outcomes as observations after each tool use in Claude Code.
|
||||
* This enables automatic memory capture without manual intervention.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../../types.js';
|
||||
import type { Observation, ObservationType, ObservationContent } from '../types.js';
|
||||
import type {
|
||||
ToolUseEvent,
|
||||
ToolUseCaptureResult,
|
||||
MemoryHookConfig,
|
||||
ClaudeCodeHookOutput,
|
||||
} from './types.js';
|
||||
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
|
||||
import { ObservationStore } from '../observation-store.js';
|
||||
|
||||
/**
|
||||
* Tool categories for classification
|
||||
*/
|
||||
const TOOL_CATEGORIES: Record<string, ObservationType> = {
|
||||
Read: 'tool_use',
|
||||
Write: 'file_change',
|
||||
Edit: 'file_change',
|
||||
Bash: 'tool_use',
|
||||
Glob: 'tool_use',
|
||||
Grep: 'tool_use',
|
||||
WebFetch: 'tool_use',
|
||||
WebSearch: 'tool_use',
|
||||
Task: 'checkpoint',
|
||||
AskUserQuestion: 'decision',
|
||||
};
|
||||
|
||||
/**
|
||||
* Relevance scores by tool type
|
||||
*/
|
||||
const TOOL_RELEVANCE: Record<string, number> = {
|
||||
Write: 70,
|
||||
Edit: 70,
|
||||
Bash: 60,
|
||||
Task: 65,
|
||||
AskUserQuestion: 75,
|
||||
WebFetch: 50,
|
||||
WebSearch: 50,
|
||||
Read: 30,
|
||||
Glob: 25,
|
||||
Grep: 30,
|
||||
};
|
||||
|
||||
/**
|
||||
* Post Tool Use Hook Handler
|
||||
*
|
||||
* Captures tool outcomes and stores them as observations.
|
||||
*/
|
||||
export class PostToolUseHook {
|
||||
private config: MemoryHookConfig;
|
||||
private agent: AgentType;
|
||||
private store: ObservationStore;
|
||||
private pendingErrors: Map<string, { error: string; timestamp: string }> = new Map();
|
||||
|
||||
constructor(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {},
|
||||
sessionId?: string
|
||||
) {
|
||||
this.agent = agent;
|
||||
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
|
||||
this.store = new ObservationStore(projectPath, sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the post tool use hook
|
||||
*/
|
||||
async execute(event: ToolUseEvent): Promise<ToolUseCaptureResult> {
|
||||
this.clearOldPendingErrors();
|
||||
|
||||
if (!this.config.enabled || !this.config.autoCaptureToolUse) {
|
||||
return { captured: false, reason: 'Hook disabled' };
|
||||
}
|
||||
|
||||
if (this.shouldExcludeTool(event.tool_name)) {
|
||||
return { captured: false, reason: `Tool ${event.tool_name} is excluded` };
|
||||
}
|
||||
|
||||
const relevance = this.calculateRelevance(event);
|
||||
if (relevance < this.config.minRelevanceForCapture) {
|
||||
return { captured: false, reason: `Relevance ${relevance} below threshold` };
|
||||
}
|
||||
|
||||
const observationType = this.getObservationType(event);
|
||||
const content = this.extractContent(event);
|
||||
|
||||
if (event.is_error) {
|
||||
const errorId = this.generateErrorId(content.error || content.action);
|
||||
this.pendingErrors.set(errorId, {
|
||||
error: content.error || content.action,
|
||||
timestamp: new Date().toISOString(),
|
||||
});
|
||||
}
|
||||
|
||||
const matchingSolution = event.is_error ? undefined : this.findMatchingSolution(content);
|
||||
if (matchingSolution) {
|
||||
content.solution = content.action;
|
||||
content.context = `Solution for: ${matchingSolution.error}`;
|
||||
}
|
||||
|
||||
const observation = this.store.add(
|
||||
observationType,
|
||||
content,
|
||||
this.agent,
|
||||
matchingSolution ? 95 : relevance
|
||||
);
|
||||
|
||||
return { captured: true, observation };
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code hook output format
|
||||
*/
|
||||
async generateHookOutput(event: ToolUseEvent): Promise<ClaudeCodeHookOutput> {
|
||||
const result = await this.execute(event);
|
||||
return this.generateHookOutputFromResult(event, result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate hook output from pre-computed result (avoids double execution)
|
||||
*/
|
||||
generateHookOutputFromResult(event: ToolUseEvent, result: ToolUseCaptureResult): ClaudeCodeHookOutput {
|
||||
return {
|
||||
continue: true,
|
||||
message: result.captured
|
||||
? `Observation captured: ${event.tool_name}`
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get configuration
|
||||
*/
|
||||
getConfig(): MemoryHookConfig {
|
||||
return { ...this.config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update configuration
|
||||
*/
|
||||
setConfig(config: Partial<MemoryHookConfig>): void {
|
||||
this.config = { ...this.config, ...config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Record an error explicitly
|
||||
*/
|
||||
recordError(error: string, context: string): Observation {
|
||||
const errorId = this.generateErrorId(error);
|
||||
this.pendingErrors.set(errorId, {
|
||||
error,
|
||||
timestamp: new Date().toISOString(),
|
||||
});
|
||||
|
||||
return this.store.add(
|
||||
'error',
|
||||
{
|
||||
action: 'Error encountered',
|
||||
context,
|
||||
error,
|
||||
tags: ['error'],
|
||||
},
|
||||
this.agent,
|
||||
80
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Record a solution explicitly
|
||||
*/
|
||||
recordSolution(solution: string, context: string, relatedError?: string): Observation {
|
||||
let relevance = 70;
|
||||
let solutionContext = context;
|
||||
|
||||
if (relatedError) {
|
||||
const errorId = this.generateErrorId(relatedError);
|
||||
if (this.pendingErrors.has(errorId)) {
|
||||
this.pendingErrors.delete(errorId);
|
||||
relevance = 95;
|
||||
solutionContext = `Solution for: ${relatedError}`;
|
||||
}
|
||||
}
|
||||
|
||||
return this.store.add(
|
||||
'solution',
|
||||
{
|
||||
action: solution,
|
||||
context: solutionContext,
|
||||
solution,
|
||||
tags: ['solution'],
|
||||
},
|
||||
this.agent,
|
||||
relevance
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Record a decision explicitly
|
||||
*/
|
||||
recordDecision(decision: string, options: string[], context: string): Observation {
|
||||
return this.store.add(
|
||||
'decision',
|
||||
{
|
||||
action: decision,
|
||||
context: `Options: ${options.join(', ')}. Context: ${context}`,
|
||||
tags: ['decision', 'architecture'],
|
||||
},
|
||||
this.agent,
|
||||
75
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Record file modifications
|
||||
*/
|
||||
recordFileChange(files: string[], action: string, context: string): Observation {
|
||||
return this.store.add(
|
||||
'file_change',
|
||||
{
|
||||
action,
|
||||
context,
|
||||
files,
|
||||
tags: ['file-change'],
|
||||
},
|
||||
this.agent,
|
||||
files.length > 3 ? 75 : 60
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get pending errors that haven't been resolved
|
||||
*/
|
||||
getPendingErrors(): Array<{ error: string; timestamp: string }> {
|
||||
return Array.from(this.pendingErrors.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear old pending errors (older than 30 minutes)
|
||||
*/
|
||||
clearOldPendingErrors(): number {
|
||||
const thirtyMinutesAgo = Date.now() - 30 * 60 * 1000;
|
||||
let cleared = 0;
|
||||
|
||||
for (const [id, { timestamp }] of this.pendingErrors) {
|
||||
if (new Date(timestamp).getTime() < thirtyMinutesAgo) {
|
||||
this.pendingErrors.delete(id);
|
||||
cleared++;
|
||||
}
|
||||
}
|
||||
|
||||
return cleared;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get observation store
|
||||
*/
|
||||
getStore(): ObservationStore {
|
||||
return this.store;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get observation count
|
||||
*/
|
||||
getObservationCount(): number {
|
||||
return this.store.count();
|
||||
}
|
||||
|
||||
private shouldExcludeTool(toolName: string): boolean {
|
||||
return this.config.excludeTools?.includes(toolName) ?? false;
|
||||
}
|
||||
|
||||
private calculateRelevance(event: ToolUseEvent): number {
|
||||
let relevance = TOOL_RELEVANCE[event.tool_name] || 50;
|
||||
|
||||
if (event.is_error) {
|
||||
relevance = Math.max(relevance, 80);
|
||||
}
|
||||
|
||||
if (event.duration_ms && event.duration_ms > 10000) {
|
||||
relevance = Math.min(relevance + 10, 100);
|
||||
}
|
||||
|
||||
const result = event.tool_result || '';
|
||||
if (result.includes('error') || result.includes('Error') || result.includes('failed')) {
|
||||
relevance = Math.max(relevance, 75);
|
||||
}
|
||||
|
||||
if (result.includes('success') || result.includes('created') || result.includes('updated')) {
|
||||
relevance = Math.min(relevance + 5, 100);
|
||||
}
|
||||
|
||||
return relevance;
|
||||
}
|
||||
|
||||
private getObservationType(event: ToolUseEvent): ObservationType {
|
||||
if (event.is_error) {
|
||||
return 'error';
|
||||
}
|
||||
|
||||
return TOOL_CATEGORIES[event.tool_name] || 'tool_use';
|
||||
}
|
||||
|
||||
private extractContent(event: ToolUseEvent): ObservationContent {
|
||||
const content: ObservationContent = {
|
||||
action: `${event.tool_name}: ${this.summarizeInput(event.tool_input)}`,
|
||||
context: this.extractContext(event),
|
||||
tags: [event.tool_name.toLowerCase()],
|
||||
};
|
||||
|
||||
if (event.is_error && event.tool_result) {
|
||||
content.error = event.tool_result.slice(0, 500);
|
||||
}
|
||||
|
||||
if (event.tool_result && !event.is_error) {
|
||||
content.result = event.tool_result.slice(0, 200);
|
||||
}
|
||||
|
||||
const files = this.extractFiles(event);
|
||||
if (files.length > 0) {
|
||||
content.files = files;
|
||||
}
|
||||
|
||||
return content;
|
||||
}
|
||||
|
||||
private summarizeInput(input: Record<string, unknown>): string {
|
||||
if (input.file_path) return String(input.file_path);
|
||||
if (input.pattern) return String(input.pattern);
|
||||
if (input.command) {
|
||||
const cmd = String(input.command);
|
||||
return cmd.length > 100 ? cmd.slice(0, 100) + '...' : cmd;
|
||||
}
|
||||
if (input.query) return String(input.query).slice(0, 100);
|
||||
|
||||
const keys = Object.keys(input);
|
||||
if (keys.length === 0) return '(no input)';
|
||||
return keys.slice(0, 3).join(', ');
|
||||
}
|
||||
|
||||
private extractContext(event: ToolUseEvent): string {
|
||||
const parts: string[] = [];
|
||||
|
||||
if (event.duration_ms) {
|
||||
parts.push(`Duration: ${event.duration_ms}ms`);
|
||||
}
|
||||
|
||||
if (event.is_error) {
|
||||
parts.push('Result: Error');
|
||||
} else if (event.tool_result) {
|
||||
const resultPreview = event.tool_result.slice(0, 100);
|
||||
parts.push(`Result: ${resultPreview}${event.tool_result.length > 100 ? '...' : ''}`);
|
||||
}
|
||||
|
||||
return parts.join('. ') || 'No additional context';
|
||||
}
|
||||
|
||||
private extractFiles(event: ToolUseEvent): string[] {
|
||||
const files: string[] = [];
|
||||
|
||||
if (event.tool_input.file_path) {
|
||||
files.push(String(event.tool_input.file_path));
|
||||
}
|
||||
|
||||
if (event.tool_input.path) {
|
||||
files.push(String(event.tool_input.path));
|
||||
}
|
||||
|
||||
return files;
|
||||
}
|
||||
|
||||
private generateErrorId(error: string): string {
|
||||
const normalized = error
|
||||
.toLowerCase()
|
||||
.replace(/[0-9]+/g, 'N')
|
||||
.replace(/['"`]/g, '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim()
|
||||
.slice(0, 100);
|
||||
|
||||
return normalized;
|
||||
}
|
||||
|
||||
private findMatchingSolution(content: ObservationContent): { error: string } | undefined {
|
||||
const actionLower = content.action.toLowerCase();
|
||||
const contextLower = content.context.toLowerCase();
|
||||
|
||||
for (const [errorId, errorData] of this.pendingErrors) {
|
||||
const hasKeywordMatch =
|
||||
actionLower.includes('fix') ||
|
||||
actionLower.includes('resolve') ||
|
||||
actionLower.includes('solution') ||
|
||||
contextLower.includes('fix') ||
|
||||
contextLower.includes('resolve');
|
||||
|
||||
if (hasKeywordMatch) {
|
||||
const errorWords = errorId.split(' ').filter((w) => w.length > 3);
|
||||
const textWords = new Set((actionLower + ' ' + contextLower).split(/\s+/));
|
||||
const matchCount = errorWords.filter((w) => textWords.has(w)).length;
|
||||
|
||||
if (matchCount >= 2 || (matchCount >= 1 && hasKeywordMatch)) {
|
||||
this.pendingErrors.delete(errorId);
|
||||
return errorData;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a post tool use hook handler
|
||||
*/
|
||||
export function createPostToolUseHook(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {},
|
||||
sessionId?: string
|
||||
): PostToolUseHook {
|
||||
return new PostToolUseHook(projectPath, agent, config, sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute post tool use hook (standalone function for scripts)
|
||||
*/
|
||||
export async function executePostToolUseHook(
|
||||
projectPath: string,
|
||||
event: ToolUseEvent,
|
||||
config: Partial<MemoryHookConfig> = {},
|
||||
sessionId?: string
|
||||
): Promise<ToolUseCaptureResult> {
|
||||
const hook = new PostToolUseHook(projectPath, 'claude-code', config, sessionId);
|
||||
return hook.execute(event);
|
||||
}
|
||||
@@ -0,0 +1,227 @@
|
||||
/**
|
||||
* Session End Hook
|
||||
*
|
||||
* Compresses observations to learnings when a Claude Code session ends.
|
||||
* This enables automatic memory consolidation without manual intervention.
|
||||
*/
|
||||
|
||||
import { basename } from 'node:path';
|
||||
import type { AgentType } from '../../types.js';
|
||||
import type {
|
||||
SessionEndContext,
|
||||
SessionEndResult,
|
||||
MemoryHookConfig,
|
||||
ClaudeCodeHookOutput,
|
||||
} from './types.js';
|
||||
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
|
||||
import { ObservationStore } from '../observation-store.js';
|
||||
import { MemoryCompressor } from '../compressor.js';
|
||||
|
||||
/**
|
||||
* Session End Hook Handler
|
||||
*
|
||||
* Compresses observations collected during the session into learnings.
|
||||
*/
|
||||
export class SessionEndHook {
|
||||
private config: MemoryHookConfig;
|
||||
private projectPath: string;
|
||||
private agent: AgentType;
|
||||
|
||||
constructor(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
) {
|
||||
this.projectPath = projectPath;
|
||||
this.agent = agent;
|
||||
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the session end hook
|
||||
*/
|
||||
async execute(context: SessionEndContext): Promise<SessionEndResult> {
|
||||
if (!this.config.enabled || !this.config.autoCompressOnSessionEnd) {
|
||||
return {
|
||||
compressed: false,
|
||||
observationCount: 0,
|
||||
learningCount: 0,
|
||||
learnings: [],
|
||||
};
|
||||
}
|
||||
|
||||
const store = new ObservationStore(this.projectPath, context.session_id);
|
||||
const observations = store.getAll();
|
||||
|
||||
if (observations.length < 3) {
|
||||
return {
|
||||
compressed: false,
|
||||
observationCount: observations.length,
|
||||
learningCount: 0,
|
||||
learnings: [],
|
||||
};
|
||||
}
|
||||
|
||||
const projectName = context.project_path
|
||||
? basename(context.project_path.replace(/\/+$/, '')) || undefined
|
||||
: undefined;
|
||||
|
||||
const compressor = new MemoryCompressor(this.projectPath, {
|
||||
scope: 'project',
|
||||
projectName,
|
||||
});
|
||||
|
||||
const { learnings, result } = await compressor.compressAndStore(observations, {
|
||||
minObservations: 3,
|
||||
maxLearnings: 10,
|
||||
minImportance: 4,
|
||||
includeLowRelevance: false,
|
||||
additionalTags: ['session-end', this.agent],
|
||||
});
|
||||
|
||||
if (result.processedObservationIds.length > 0) {
|
||||
store.deleteMany(result.processedObservationIds);
|
||||
}
|
||||
|
||||
return {
|
||||
compressed: learnings.length > 0,
|
||||
observationCount: observations.length,
|
||||
learningCount: learnings.length,
|
||||
learnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code hook output format
|
||||
*/
|
||||
async generateHookOutput(context: SessionEndContext): Promise<ClaudeCodeHookOutput> {
|
||||
const result = await this.execute(context);
|
||||
return this.generateHookOutputFromResult(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate hook output from pre-computed result (avoids double execution)
|
||||
*/
|
||||
generateHookOutputFromResult(result: SessionEndResult): ClaudeCodeHookOutput {
|
||||
let message: string | undefined;
|
||||
if (result.compressed) {
|
||||
message = `Session memory: ${result.observationCount} observations → ${result.learningCount} learnings`;
|
||||
}
|
||||
|
||||
return {
|
||||
continue: true,
|
||||
message,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Force compression regardless of settings
|
||||
*/
|
||||
async forceCompress(sessionId?: string): Promise<SessionEndResult> {
|
||||
const store = new ObservationStore(this.projectPath, sessionId);
|
||||
const observations = store.getAll();
|
||||
|
||||
if (observations.length === 0) {
|
||||
return {
|
||||
compressed: false,
|
||||
observationCount: 0,
|
||||
learningCount: 0,
|
||||
learnings: [],
|
||||
};
|
||||
}
|
||||
|
||||
const compressor = new MemoryCompressor(this.projectPath, {
|
||||
scope: 'project',
|
||||
});
|
||||
|
||||
const { learnings, result } = await compressor.compressAndStore(observations, {
|
||||
minObservations: 1,
|
||||
maxLearnings: 20,
|
||||
minImportance: 3,
|
||||
includeLowRelevance: true,
|
||||
});
|
||||
|
||||
if (result.processedObservationIds.length > 0) {
|
||||
store.deleteMany(result.processedObservationIds);
|
||||
}
|
||||
|
||||
return {
|
||||
compressed: learnings.length > 0,
|
||||
observationCount: observations.length,
|
||||
learningCount: learnings.length,
|
||||
learnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Preview what would be compressed (dry-run)
|
||||
*/
|
||||
async preview(sessionId?: string): Promise<{
|
||||
wouldCompress: boolean;
|
||||
observationCount: number;
|
||||
estimatedLearnings: number;
|
||||
observationTypes: Record<string, number>;
|
||||
}> {
|
||||
const store = new ObservationStore(this.projectPath, sessionId);
|
||||
const observations = store.getAll();
|
||||
|
||||
const types: Record<string, number> = {};
|
||||
for (const obs of observations) {
|
||||
types[obs.type] = (types[obs.type] || 0) + 1;
|
||||
}
|
||||
|
||||
const compressor = new MemoryCompressor(this.projectPath, {
|
||||
scope: 'project',
|
||||
});
|
||||
|
||||
const result = await compressor.compress(observations, {
|
||||
minObservations: 3,
|
||||
maxLearnings: 10,
|
||||
minImportance: 4,
|
||||
});
|
||||
|
||||
return {
|
||||
wouldCompress: result.learnings.length > 0,
|
||||
observationCount: observations.length,
|
||||
estimatedLearnings: result.learnings.length,
|
||||
observationTypes: types,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get configuration
|
||||
*/
|
||||
getConfig(): MemoryHookConfig {
|
||||
return { ...this.config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update configuration
|
||||
*/
|
||||
setConfig(config: Partial<MemoryHookConfig>): void {
|
||||
this.config = { ...this.config, ...config };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a session end hook handler
|
||||
*/
|
||||
export function createSessionEndHook(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
): SessionEndHook {
|
||||
return new SessionEndHook(projectPath, agent, config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute session end hook (standalone function for scripts)
|
||||
*/
|
||||
export async function executeSessionEndHook(
|
||||
projectPath: string,
|
||||
context: SessionEndContext,
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
): Promise<SessionEndResult> {
|
||||
const hook = new SessionEndHook(projectPath, context.agent || 'claude-code', config);
|
||||
return hook.execute(context);
|
||||
}
|
||||
@@ -0,0 +1,177 @@
|
||||
/**
|
||||
* Session Start Hook
|
||||
*
|
||||
* Injects relevant memories when a Claude Code session starts.
|
||||
* This hook runs at the beginning of each session to provide context
|
||||
* from previous sessions.
|
||||
*/
|
||||
|
||||
import { basename } from 'node:path';
|
||||
import type { AgentType } from '../../types.js';
|
||||
import type {
|
||||
SessionStartContext,
|
||||
SessionStartResult,
|
||||
MemoryHookConfig,
|
||||
ClaudeCodeHookOutput,
|
||||
} from './types.js';
|
||||
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
|
||||
import { MemoryInjector } from '../injector.js';
|
||||
import { getMemoryStatus } from '../initializer.js';
|
||||
|
||||
/**
|
||||
* Session Start Hook Handler
|
||||
*
|
||||
* Retrieves and formats relevant memories for injection at session start.
|
||||
*/
|
||||
export class SessionStartHook {
|
||||
private config: MemoryHookConfig;
|
||||
private projectPath: string;
|
||||
private agent: AgentType;
|
||||
|
||||
constructor(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
) {
|
||||
this.projectPath = projectPath;
|
||||
this.agent = agent;
|
||||
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute the session start hook
|
||||
*/
|
||||
async execute(context: SessionStartContext): Promise<SessionStartResult> {
|
||||
if (!this.config.enabled || !this.config.autoInjectOnSessionStart) {
|
||||
return {
|
||||
injected: false,
|
||||
learnings: [],
|
||||
tokenCount: 0,
|
||||
formattedContent: '',
|
||||
};
|
||||
}
|
||||
|
||||
const status = getMemoryStatus(this.projectPath);
|
||||
if (!status.projectMemoryExists && !status.globalMemoryExists) {
|
||||
return {
|
||||
injected: false,
|
||||
learnings: [],
|
||||
tokenCount: 0,
|
||||
formattedContent: '',
|
||||
};
|
||||
}
|
||||
|
||||
const projectName = context.project_path
|
||||
? basename(context.project_path.replace(/\/+$/, '')) || undefined
|
||||
: undefined;
|
||||
|
||||
const injector = new MemoryInjector(this.projectPath, projectName);
|
||||
|
||||
const result = await injector.injectForAgent(this.agent, {
|
||||
maxTokens: this.config.maxTokensForInjection,
|
||||
minRelevance: this.config.minRelevanceForCapture,
|
||||
maxLearnings: 10,
|
||||
includeGlobal: true,
|
||||
disclosureLevel: 'preview',
|
||||
});
|
||||
|
||||
const learnings = result.memories.map((m) => m.learning);
|
||||
|
||||
return {
|
||||
injected: result.memories.length > 0,
|
||||
learnings,
|
||||
tokenCount: result.totalTokens,
|
||||
formattedContent: result.formattedContent,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code hook output format
|
||||
*/
|
||||
async generateHookOutput(context: SessionStartContext): Promise<ClaudeCodeHookOutput> {
|
||||
const result = await this.execute(context);
|
||||
return this.generateHookOutputFromResult(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate hook output from pre-computed result (avoids double execution)
|
||||
*/
|
||||
generateHookOutputFromResult(result: SessionStartResult): ClaudeCodeHookOutput {
|
||||
if (!result.injected || result.learnings.length === 0) {
|
||||
return { continue: true };
|
||||
}
|
||||
|
||||
return {
|
||||
continue: true,
|
||||
inject: this.formatInjection(result),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Format learnings for injection into Claude Code context
|
||||
*/
|
||||
private formatInjection(result: SessionStartResult): string {
|
||||
if (result.learnings.length === 0) {
|
||||
return '';
|
||||
}
|
||||
|
||||
const lines: string[] = [
|
||||
'<skillkit-memories>',
|
||||
`<!-- ${result.learnings.length} relevant learnings from previous sessions (${result.tokenCount} tokens) -->`,
|
||||
'',
|
||||
];
|
||||
|
||||
for (const learning of result.learnings) {
|
||||
lines.push(`## ${learning.title}`);
|
||||
lines.push(`Tags: ${learning.tags.join(', ')}`);
|
||||
if (learning.frameworks && learning.frameworks.length > 0) {
|
||||
lines.push(`Frameworks: ${learning.frameworks.join(', ')}`);
|
||||
}
|
||||
lines.push('');
|
||||
const preview = learning.content.slice(0, 200);
|
||||
lines.push(preview + (learning.content.length > 200 ? '...' : ''));
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('</skillkit-memories>');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get configuration
|
||||
*/
|
||||
getConfig(): MemoryHookConfig {
|
||||
return { ...this.config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update configuration
|
||||
*/
|
||||
setConfig(config: Partial<MemoryHookConfig>): void {
|
||||
this.config = { ...this.config, ...config };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a session start hook handler
|
||||
*/
|
||||
export function createSessionStartHook(
|
||||
projectPath: string,
|
||||
agent: AgentType = 'claude-code',
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
): SessionStartHook {
|
||||
return new SessionStartHook(projectPath, agent, config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute session start hook (standalone function for scripts)
|
||||
*/
|
||||
export async function executeSessionStartHook(
|
||||
projectPath: string,
|
||||
context: SessionStartContext,
|
||||
config: Partial<MemoryHookConfig> = {}
|
||||
): Promise<SessionStartResult> {
|
||||
const hook = new SessionStartHook(projectPath, context.agent || 'claude-code', config);
|
||||
return hook.execute(context);
|
||||
}
|
||||
@@ -0,0 +1,139 @@
|
||||
/**
|
||||
* Memory Hooks Types
|
||||
*
|
||||
* Types for Claude Code lifecycle hooks that integrate with SkillKit memory.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../../types.js';
|
||||
import type { Learning, Observation } from '../types.js';
|
||||
|
||||
/**
|
||||
* Claude Code hook event types
|
||||
*/
|
||||
export type ClaudeCodeHookEvent =
|
||||
| 'SessionStart'
|
||||
| 'SessionResume'
|
||||
| 'SessionEnd'
|
||||
| 'PreToolUse'
|
||||
| 'PostToolUse'
|
||||
| 'UserPromptSubmit'
|
||||
| 'PreCompact'
|
||||
| 'Notification'
|
||||
| 'Stop';
|
||||
|
||||
/**
|
||||
* Tool use event for PostToolUse hook
|
||||
*/
|
||||
export interface ToolUseEvent {
|
||||
tool_name: string;
|
||||
tool_input: Record<string, unknown>;
|
||||
tool_result?: string;
|
||||
is_error?: boolean;
|
||||
duration_ms?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Session start event context
|
||||
*/
|
||||
export interface SessionStartContext {
|
||||
session_id: string;
|
||||
project_path: string;
|
||||
agent: AgentType;
|
||||
timestamp: string;
|
||||
working_directory?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Session end event context
|
||||
*/
|
||||
export interface SessionEndContext {
|
||||
session_id: string;
|
||||
project_path: string;
|
||||
agent: AgentType;
|
||||
timestamp: string;
|
||||
duration_ms?: number;
|
||||
tool_calls_count?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Memory hook configuration
|
||||
*/
|
||||
export interface MemoryHookConfig {
|
||||
enabled: boolean;
|
||||
autoInjectOnSessionStart: boolean;
|
||||
autoCaptureToolUse: boolean;
|
||||
autoCompressOnSessionEnd: boolean;
|
||||
minRelevanceForCapture: number;
|
||||
maxTokensForInjection: number;
|
||||
compressionThreshold: number;
|
||||
capturePatterns?: string[];
|
||||
excludeTools?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Default memory hook configuration
|
||||
*/
|
||||
export const DEFAULT_MEMORY_HOOK_CONFIG: MemoryHookConfig = {
|
||||
enabled: true,
|
||||
autoInjectOnSessionStart: true,
|
||||
autoCaptureToolUse: true,
|
||||
autoCompressOnSessionEnd: true,
|
||||
minRelevanceForCapture: 30,
|
||||
maxTokensForInjection: 2000,
|
||||
compressionThreshold: 50,
|
||||
capturePatterns: ['*'],
|
||||
excludeTools: ['Read', 'Glob', 'Grep'],
|
||||
};
|
||||
|
||||
/**
|
||||
* Session start hook result
|
||||
*/
|
||||
export interface SessionStartResult {
|
||||
injected: boolean;
|
||||
learnings: Learning[];
|
||||
tokenCount: number;
|
||||
formattedContent: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Tool use capture result
|
||||
*/
|
||||
export interface ToolUseCaptureResult {
|
||||
captured: boolean;
|
||||
observation?: Observation;
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Session end hook result
|
||||
*/
|
||||
export interface SessionEndResult {
|
||||
compressed: boolean;
|
||||
observationCount: number;
|
||||
learningCount: number;
|
||||
learnings: Learning[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook script output format for Claude Code
|
||||
*/
|
||||
export interface ClaudeCodeHookOutput {
|
||||
continue: boolean;
|
||||
message?: string;
|
||||
inject?: string;
|
||||
suppress?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Memory hook statistics
|
||||
*/
|
||||
export interface MemoryHookStats {
|
||||
sessionId: string;
|
||||
startedAt: string;
|
||||
observationsCaptured: number;
|
||||
learningsInjected: number;
|
||||
tokensUsed: number;
|
||||
toolCallsCaptured: number;
|
||||
errorsRecorded: number;
|
||||
solutionsRecorded: number;
|
||||
}
|
||||
@@ -1,8 +1,9 @@
|
||||
// Memory Module - Cross-Agent Session Memory System
|
||||
// Provides persistent memory across all AI coding agents
|
||||
|
||||
export * from './types.js';
|
||||
export { ObservationStore } from './observation-store.js';
|
||||
export {
|
||||
ObservationStore,
|
||||
type AutoCompressCallback,
|
||||
type ObservationStoreOptions,
|
||||
} from './observation-store.js';
|
||||
export { LearningStore } from './learning-store.js';
|
||||
export { MemoryIndexStore } from './memory-index.js';
|
||||
export {
|
||||
@@ -48,3 +49,25 @@ export {
|
||||
type InjectedMemory,
|
||||
type InjectionResult,
|
||||
} from './injector.js';
|
||||
|
||||
export * from './hooks/index.js';
|
||||
|
||||
export {
|
||||
ClaudeMdUpdater,
|
||||
createClaudeMdUpdater,
|
||||
updateClaudeMd,
|
||||
syncGlobalClaudeMd,
|
||||
type ClaudeMdUpdateOptions,
|
||||
type ClaudeMdUpdateResult,
|
||||
type ParsedClaudeMd,
|
||||
} from './claude-md-updater.js';
|
||||
|
||||
export {
|
||||
ProgressiveDisclosureManager,
|
||||
createProgressiveDisclosureManager,
|
||||
type IndexEntry,
|
||||
type TimelineEntry,
|
||||
type DetailsEntry,
|
||||
type ActivityPoint,
|
||||
type ProgressiveDisclosureOptions,
|
||||
} from './progressive-disclosure.js';
|
||||
|
||||
@@ -30,12 +30,10 @@ export function getMemoryPaths(projectPath: string): MemoryPaths {
|
||||
export function initializeMemoryDirectory(projectPath: string): MemoryPaths {
|
||||
const paths = getMemoryPaths(projectPath);
|
||||
|
||||
// Create project memory directory
|
||||
if (!existsSync(paths.projectMemoryDir)) {
|
||||
mkdirSync(paths.projectMemoryDir, { recursive: true });
|
||||
}
|
||||
|
||||
// Create global memory directory
|
||||
if (!existsSync(paths.globalMemoryDir)) {
|
||||
mkdirSync(paths.globalMemoryDir, { recursive: true });
|
||||
}
|
||||
|
||||
@@ -109,24 +109,19 @@ export class MemoryInjector {
|
||||
async getRelevantMemories(options: InjectionOptions = {}): Promise<InjectedMemory[]> {
|
||||
const opts = { ...DEFAULT_OPTIONS, ...options };
|
||||
|
||||
// Collect all learnings
|
||||
const projectLearnings = this.projectStore.getAll();
|
||||
const globalLearnings = opts.includeGlobal ? this.globalStore.getAll() : [];
|
||||
const allLearnings = [...projectLearnings, ...globalLearnings];
|
||||
|
||||
// Score each learning for relevance
|
||||
const scored = allLearnings.map((learning) => ({
|
||||
learning,
|
||||
...this.scoreLearning(learning, opts),
|
||||
}));
|
||||
|
||||
// Filter by minimum relevance
|
||||
const filtered = scored.filter((s) => s.relevanceScore >= opts.minRelevance);
|
||||
|
||||
// Sort by relevance (descending)
|
||||
filtered.sort((a, b) => b.relevanceScore - a.relevanceScore);
|
||||
|
||||
// Limit to max learnings
|
||||
return filtered.slice(0, opts.maxLearnings);
|
||||
}
|
||||
|
||||
@@ -145,7 +140,6 @@ export class MemoryInjector {
|
||||
patterns: [] as string[],
|
||||
};
|
||||
|
||||
// Match by frameworks from project context
|
||||
if (this.projectContext?.stack) {
|
||||
const projectFrameworks = this.extractFrameworkNames();
|
||||
const learningFrameworks = learning.frameworks || [];
|
||||
@@ -158,7 +152,6 @@ export class MemoryInjector {
|
||||
}
|
||||
}
|
||||
|
||||
// Match by explicitly requested tags
|
||||
if (options.tags && options.tags.length > 0) {
|
||||
const requestedTags = new Set(options.tags.map((t) => t.toLowerCase()));
|
||||
for (const tag of learning.tags) {
|
||||
@@ -169,7 +162,6 @@ export class MemoryInjector {
|
||||
}
|
||||
}
|
||||
|
||||
// Match by current task keywords
|
||||
if (options.currentTask) {
|
||||
const taskKeywords = this.extractKeywords(options.currentTask);
|
||||
const learningKeywords = [
|
||||
@@ -189,22 +181,17 @@ export class MemoryInjector {
|
||||
}
|
||||
}
|
||||
|
||||
// Match by patterns
|
||||
if (learning.patterns && learning.patterns.length > 0) {
|
||||
// Patterns are valuable - boost score
|
||||
score += learning.patterns.length * 5;
|
||||
matchedBy.patterns.push(...learning.patterns);
|
||||
}
|
||||
|
||||
// Boost by effectiveness if known
|
||||
if (learning.effectiveness !== undefined) {
|
||||
score += (learning.effectiveness / 100) * 20;
|
||||
}
|
||||
|
||||
// Boost by use count (popular learnings are likely valuable)
|
||||
score += Math.min(learning.useCount * 2, 15);
|
||||
|
||||
// Boost recent learnings
|
||||
const daysSinceUpdate = this.daysSince(learning.updatedAt);
|
||||
if (daysSinceUpdate < 7) {
|
||||
score += 10;
|
||||
@@ -212,10 +199,8 @@ export class MemoryInjector {
|
||||
score += 5;
|
||||
}
|
||||
|
||||
// Cap score at 100
|
||||
score = Math.min(score, 100);
|
||||
|
||||
// Estimate token count
|
||||
const tokenEstimate = this.estimateTokens(learning, options.disclosureLevel || 'preview');
|
||||
|
||||
return {
|
||||
@@ -304,7 +289,6 @@ export class MemoryInjector {
|
||||
const opts = { ...DEFAULT_OPTIONS, ...options };
|
||||
const allMemories = await this.getRelevantMemories(opts);
|
||||
|
||||
// Select memories within token budget
|
||||
const selected: InjectedMemory[] = [];
|
||||
let totalTokens = 0;
|
||||
let truncated = 0;
|
||||
@@ -314,7 +298,6 @@ export class MemoryInjector {
|
||||
selected.push(memory);
|
||||
totalTokens += memory.tokenEstimate;
|
||||
|
||||
// Increment use count
|
||||
if (memory.learning.scope === 'project') {
|
||||
this.projectStore.incrementUseCount(memory.learning.id);
|
||||
} else {
|
||||
@@ -325,7 +308,6 @@ export class MemoryInjector {
|
||||
}
|
||||
}
|
||||
|
||||
// Format the content
|
||||
const formattedContent = this.formatMemories(selected, opts.disclosureLevel || 'preview');
|
||||
|
||||
return {
|
||||
@@ -350,7 +332,6 @@ export class MemoryInjector {
|
||||
): Promise<InjectionResult> {
|
||||
const result = await this.inject(options);
|
||||
|
||||
// Reformat for specific agent
|
||||
result.formattedContent = this.formatForAgent(result.memories, agent, options.disclosureLevel);
|
||||
|
||||
return result;
|
||||
@@ -381,7 +362,6 @@ export class MemoryInjector {
|
||||
|
||||
switch (level) {
|
||||
case 'summary':
|
||||
// Just title and tags (already shown above)
|
||||
break;
|
||||
case 'preview':
|
||||
lines.push(learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''));
|
||||
|
||||
@@ -8,10 +8,6 @@ export class MemoryIndexStore {
|
||||
private data: MemoryIndex | null = null;
|
||||
|
||||
constructor(basePath: string, _isGlobal = false) {
|
||||
// Both global and project use .skillkit subdirectory
|
||||
// Global: ~/.skillkit/memory/index.yaml (basePath = homedir())
|
||||
// Project: <projectPath>/.skillkit/memory/index.yaml (basePath = projectPath)
|
||||
// Note: _isGlobal kept for API compatibility but basePath determines the actual path
|
||||
this.filePath = join(basePath, '.skillkit', 'memory', 'index.yaml');
|
||||
}
|
||||
|
||||
@@ -58,7 +54,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
|
||||
private extractKeywords(text: string): string[] {
|
||||
// Extract meaningful keywords from text
|
||||
const stopWords = new Set([
|
||||
'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
|
||||
'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
|
||||
@@ -79,12 +74,10 @@ export class MemoryIndexStore {
|
||||
indexLearning(learning: Learning): void {
|
||||
const data = this.load();
|
||||
|
||||
// Extract keywords from title and content
|
||||
const titleKeywords = this.extractKeywords(learning.title);
|
||||
const contentKeywords = this.extractKeywords(learning.content);
|
||||
const allKeywords = [...new Set([...titleKeywords, ...contentKeywords])];
|
||||
|
||||
// Index by keywords
|
||||
for (const keyword of allKeywords) {
|
||||
if (!data.entries[keyword]) {
|
||||
data.entries[keyword] = [];
|
||||
@@ -94,7 +87,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
}
|
||||
|
||||
// Index by tags
|
||||
for (const tag of learning.tags) {
|
||||
const normalizedTag = tag.toLowerCase();
|
||||
if (!data.tags[normalizedTag]) {
|
||||
@@ -105,7 +97,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
}
|
||||
|
||||
// Index by frameworks if present
|
||||
if (learning.frameworks) {
|
||||
for (const framework of learning.frameworks) {
|
||||
const normalizedFw = framework.toLowerCase();
|
||||
@@ -124,7 +115,6 @@ export class MemoryIndexStore {
|
||||
removeLearning(learningId: string): void {
|
||||
const data = this.load();
|
||||
|
||||
// Remove from keyword entries
|
||||
for (const keyword of Object.keys(data.entries)) {
|
||||
data.entries[keyword] = data.entries[keyword].filter((id) => id !== learningId);
|
||||
if (data.entries[keyword].length === 0) {
|
||||
@@ -132,7 +122,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
}
|
||||
|
||||
// Remove from tags
|
||||
for (const tag of Object.keys(data.tags)) {
|
||||
data.tags[tag] = data.tags[tag].filter((id) => id !== learningId);
|
||||
if (data.tags[tag].length === 0) {
|
||||
@@ -149,20 +138,16 @@ export class MemoryIndexStore {
|
||||
|
||||
if (keywords.length === 0) return [];
|
||||
|
||||
// Find IDs that match any keyword
|
||||
const matchCounts = new Map<string, number>();
|
||||
|
||||
for (const keyword of keywords) {
|
||||
// Exact match
|
||||
if (data.entries[keyword]) {
|
||||
for (const id of data.entries[keyword]) {
|
||||
matchCounts.set(id, (matchCounts.get(id) || 0) + 2);
|
||||
}
|
||||
}
|
||||
|
||||
// Partial match (keyword is substring of indexed word, but not exact match)
|
||||
for (const [indexed, ids] of Object.entries(data.entries)) {
|
||||
// Skip exact matches - they're already counted above with higher weight
|
||||
if (indexed === keyword) continue;
|
||||
if (indexed.includes(keyword) || keyword.includes(indexed)) {
|
||||
for (const id of ids) {
|
||||
@@ -172,7 +157,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by match count (most matches first)
|
||||
return [...matchCounts.entries()]
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.map(([id]) => id);
|
||||
@@ -192,7 +176,6 @@ export class MemoryIndexStore {
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by match count
|
||||
return [...matchCounts.entries()]
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.map(([id]) => id);
|
||||
@@ -210,7 +193,6 @@ export class MemoryIndexStore {
|
||||
return tagResults;
|
||||
}
|
||||
|
||||
// Combine results, prioritizing items that match both
|
||||
const keywordSet = new Set(keywordResults);
|
||||
const tagSet = new Set(tagResults);
|
||||
|
||||
@@ -250,10 +232,8 @@ export class MemoryIndexStore {
|
||||
}
|
||||
|
||||
rebuildIndex(learnings: Learning[]): void {
|
||||
// Clear existing index
|
||||
this.data = this.createEmpty();
|
||||
|
||||
// Re-index all learnings
|
||||
for (const learning of learnings) {
|
||||
this.indexLearning(learning);
|
||||
}
|
||||
|
||||
@@ -10,14 +10,37 @@ import type {
|
||||
} from './types.js';
|
||||
import type { AgentType } from '../types.js';
|
||||
|
||||
/**
|
||||
* Auto-compression callback type
|
||||
*/
|
||||
export type AutoCompressCallback = (observations: Observation[]) => Promise<void>;
|
||||
|
||||
/**
|
||||
* Observation store options
|
||||
*/
|
||||
export interface ObservationStoreOptions {
|
||||
compressionThreshold?: number;
|
||||
autoCompress?: boolean;
|
||||
onThresholdReached?: AutoCompressCallback;
|
||||
}
|
||||
|
||||
export class ObservationStore {
|
||||
private readonly filePath: string;
|
||||
private readonly projectPath: string;
|
||||
private data: ObservationStoreData | null = null;
|
||||
private sessionId: string;
|
||||
private compressionThreshold: number;
|
||||
private autoCompress: boolean;
|
||||
private onThresholdReached?: AutoCompressCallback;
|
||||
private compressionInProgress = false;
|
||||
|
||||
constructor(projectPath: string, sessionId?: string) {
|
||||
constructor(projectPath: string, sessionId?: string, options: ObservationStoreOptions = {}) {
|
||||
this.projectPath = projectPath;
|
||||
this.filePath = join(projectPath, '.skillkit', 'memory', 'observations.yaml');
|
||||
this.sessionId = sessionId || randomUUID();
|
||||
this.compressionThreshold = options.compressionThreshold ?? 50;
|
||||
this.autoCompress = options.autoCompress ?? true;
|
||||
this.onThresholdReached = options.onThresholdReached;
|
||||
}
|
||||
|
||||
private ensureDir(): void {
|
||||
@@ -83,9 +106,77 @@ export class ObservationStore {
|
||||
data.observations.push(observation);
|
||||
this.save();
|
||||
|
||||
void this.checkAutoCompression().catch(() => {
|
||||
// Silently ignore auto-compression errors to avoid disrupting add()
|
||||
});
|
||||
|
||||
return observation;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if auto-compression should trigger
|
||||
*/
|
||||
private async checkAutoCompression(): Promise<void> {
|
||||
if (!this.autoCompress || this.compressionInProgress) return;
|
||||
if (!this.onThresholdReached) return;
|
||||
|
||||
const count = this.count();
|
||||
if (count >= this.compressionThreshold) {
|
||||
this.compressionInProgress = true;
|
||||
try {
|
||||
const observations = this.getAll();
|
||||
await this.onThresholdReached(observations);
|
||||
} finally {
|
||||
this.compressionInProgress = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Set auto-compression callback
|
||||
*/
|
||||
setAutoCompressCallback(callback: AutoCompressCallback): void {
|
||||
this.onThresholdReached = callback;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enable/disable auto-compression
|
||||
*/
|
||||
setAutoCompress(enabled: boolean): void {
|
||||
this.autoCompress = enabled;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set compression threshold
|
||||
*/
|
||||
setCompressionThreshold(threshold: number): void {
|
||||
if (threshold < 1 || !Number.isInteger(threshold)) {
|
||||
throw new Error('Compression threshold must be a positive integer');
|
||||
}
|
||||
this.compressionThreshold = threshold;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get compression threshold
|
||||
*/
|
||||
getCompressionThreshold(): number {
|
||||
return this.compressionThreshold;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if threshold is reached
|
||||
*/
|
||||
isThresholdReached(): boolean {
|
||||
return this.count() >= this.compressionThreshold;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get project path
|
||||
*/
|
||||
getProjectPath(): string {
|
||||
return this.projectPath;
|
||||
}
|
||||
|
||||
getAll(): Observation[] {
|
||||
return this.load().observations;
|
||||
}
|
||||
|
||||
@@ -118,26 +118,18 @@ export class MemoryObserver {
|
||||
* Observe an event and potentially store it
|
||||
*/
|
||||
observe(event: ObservableEvent): Observation | null {
|
||||
// Check if we should capture this event type
|
||||
if (!this.shouldCapture(event)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Classify the event into an observation type
|
||||
const observationType = this.classifyEvent(event);
|
||||
|
||||
// Extract content from the event
|
||||
const content = this.extractContent(event);
|
||||
|
||||
// Score relevance
|
||||
const relevance = this.scoreRelevance(event);
|
||||
|
||||
// Check minimum relevance threshold
|
||||
if (relevance < this.config.minRelevance) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Store the observation
|
||||
return this.store.add(observationType, content, this.currentAgent, relevance);
|
||||
}
|
||||
|
||||
@@ -243,7 +235,6 @@ export class MemoryObserver {
|
||||
context,
|
||||
};
|
||||
|
||||
// Store pending error for potential solution matching
|
||||
const errorKey = this.generateErrorKey(error);
|
||||
this.pendingErrors.set(errorKey, event);
|
||||
|
||||
@@ -263,7 +254,6 @@ export class MemoryObserver {
|
||||
error: relatedError,
|
||||
};
|
||||
|
||||
// If we can match this to a pending error, increase relevance
|
||||
if (relatedError) {
|
||||
const errorKey = this.generateErrorKey(relatedError);
|
||||
this.pendingErrors.delete(errorKey);
|
||||
@@ -393,7 +383,6 @@ export class MemoryObserver {
|
||||
content.solution = event.output;
|
||||
}
|
||||
|
||||
// Generate tags based on event
|
||||
content.tags = this.generateTags(event);
|
||||
|
||||
return content;
|
||||
@@ -462,15 +451,12 @@ export class MemoryObserver {
|
||||
private generateTags(event: ObservableEvent): string[] {
|
||||
const tags: string[] = [];
|
||||
|
||||
// Add event type as tag
|
||||
tags.push(event.type.replace(/_/g, '-'));
|
||||
|
||||
// Add skill name if present
|
||||
if (event.skillName) {
|
||||
tags.push(event.skillName.toLowerCase().replace(/[^a-z0-9-]/g, '-'));
|
||||
}
|
||||
|
||||
// Add error-related tags
|
||||
if (event.error) {
|
||||
if (event.error.toLowerCase().includes('type')) tags.push('typescript');
|
||||
if (event.error.toLowerCase().includes('import')) tags.push('imports');
|
||||
@@ -480,7 +466,6 @@ export class MemoryObserver {
|
||||
tags.push('async');
|
||||
}
|
||||
|
||||
// Add file-related tags
|
||||
if (event.files) {
|
||||
for (const file of event.files) {
|
||||
if (file.endsWith('.ts') || file.endsWith('.tsx')) tags.push('typescript');
|
||||
@@ -498,16 +483,13 @@ export class MemoryObserver {
|
||||
* Score relevance of event
|
||||
*/
|
||||
private scoreRelevance(event: ObservableEvent): number {
|
||||
// Use custom scorer if provided
|
||||
if (this.config.relevanceScorer) {
|
||||
return this.config.relevanceScorer(event);
|
||||
}
|
||||
|
||||
// Default relevance scoring
|
||||
let score = 50; // Base score
|
||||
let score = 50;
|
||||
|
||||
switch (event.type) {
|
||||
// High relevance events
|
||||
case 'error_encountered':
|
||||
case 'task_failed':
|
||||
score = 85;
|
||||
@@ -515,7 +497,6 @@ export class MemoryObserver {
|
||||
|
||||
case 'solution_applied':
|
||||
score = 90;
|
||||
// Bonus if it matches a pending error
|
||||
if (event.error) {
|
||||
const errorKey = this.generateErrorKey(event.error);
|
||||
if (this.pendingErrors.has(errorKey)) {
|
||||
@@ -532,10 +513,8 @@ export class MemoryObserver {
|
||||
score = 80;
|
||||
break;
|
||||
|
||||
// Medium relevance events
|
||||
case 'file_modified':
|
||||
score = 60;
|
||||
// More files = higher relevance
|
||||
if (event.files && event.files.length > 3) {
|
||||
score = 70;
|
||||
}
|
||||
@@ -550,7 +529,6 @@ export class MemoryObserver {
|
||||
score = 50;
|
||||
break;
|
||||
|
||||
// Lower relevance events
|
||||
case 'task_start':
|
||||
score = 30;
|
||||
break;
|
||||
@@ -568,7 +546,6 @@ export class MemoryObserver {
|
||||
score = 50;
|
||||
}
|
||||
|
||||
// Adjust based on content richness
|
||||
if (event.context && event.context.length > 100) {
|
||||
score += 5;
|
||||
}
|
||||
@@ -577,7 +554,6 @@ export class MemoryObserver {
|
||||
score += 5;
|
||||
}
|
||||
|
||||
// Cap at 100
|
||||
return Math.min(score, 100);
|
||||
}
|
||||
|
||||
@@ -585,7 +561,6 @@ export class MemoryObserver {
|
||||
* Generate a key for matching errors to solutions
|
||||
*/
|
||||
private generateErrorKey(error: string): string {
|
||||
// Normalize error string for matching
|
||||
return error
|
||||
.toLowerCase()
|
||||
.replace(/[0-9]+/g, 'N') // Replace numbers
|
||||
|
||||
@@ -0,0 +1,458 @@
|
||||
/**
|
||||
* Progressive Disclosure System
|
||||
*
|
||||
* Implements 3-layer token-optimized retrieval for efficient context usage:
|
||||
* - Layer 1: Index (titles, timestamps, IDs) - ~50-100 tokens
|
||||
* - Layer 2: Timeline (context around observations) - ~200 tokens
|
||||
* - Layer 3: Details (full content) - ~500-1000 tokens
|
||||
*/
|
||||
|
||||
import type { Learning } from './types.js';
|
||||
import { LearningStore } from './learning-store.js';
|
||||
|
||||
/**
|
||||
* Index entry (Layer 1)
|
||||
* Minimal information for fast scanning
|
||||
*/
|
||||
export interface IndexEntry {
|
||||
id: string;
|
||||
title: string;
|
||||
timestamp: string;
|
||||
tags: string[];
|
||||
scope: 'project' | 'global';
|
||||
effectiveness?: number;
|
||||
useCount: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Timeline entry (Layer 2)
|
||||
* Context around the learning with activity timeline
|
||||
*/
|
||||
export interface TimelineEntry extends IndexEntry {
|
||||
excerpt: string;
|
||||
frameworks?: string[];
|
||||
patterns?: string[];
|
||||
sourceCount: number;
|
||||
lastUsed?: string;
|
||||
activityTimeline?: ActivityPoint[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Activity point for timeline
|
||||
*/
|
||||
export interface ActivityPoint {
|
||||
timestamp: string;
|
||||
type: 'created' | 'used' | 'updated' | 'rated';
|
||||
description?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Details entry (Layer 3)
|
||||
* Full content with all metadata
|
||||
*/
|
||||
export interface DetailsEntry extends TimelineEntry {
|
||||
content: string;
|
||||
sourceObservations?: string[];
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Progressive disclosure options
|
||||
*/
|
||||
export interface ProgressiveDisclosureOptions {
|
||||
includeGlobal?: boolean;
|
||||
minRelevance?: number;
|
||||
maxResults?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Token estimates per layer
|
||||
*/
|
||||
const TOKEN_ESTIMATES = {
|
||||
index: 50,
|
||||
timeline: 200,
|
||||
details: 600,
|
||||
};
|
||||
|
||||
/**
|
||||
* Progressive Disclosure Manager
|
||||
*
|
||||
* Provides 3-layer retrieval for optimal token usage.
|
||||
*/
|
||||
export class ProgressiveDisclosureManager {
|
||||
private projectStore: LearningStore;
|
||||
private globalStore: LearningStore;
|
||||
|
||||
constructor(projectPath: string, projectName?: string) {
|
||||
this.projectStore = new LearningStore('project', projectPath, projectName);
|
||||
this.globalStore = new LearningStore('global');
|
||||
}
|
||||
|
||||
/**
|
||||
* Layer 1: Get index of all learnings
|
||||
* Minimal tokens (~50-100 per entry)
|
||||
*/
|
||||
getIndex(options: ProgressiveDisclosureOptions = {}): IndexEntry[] {
|
||||
const projectLearnings = this.projectStore.getAll();
|
||||
const globalLearnings = options.includeGlobal ? this.globalStore.getAll() : [];
|
||||
const allLearnings = [...projectLearnings, ...globalLearnings];
|
||||
|
||||
return allLearnings
|
||||
.map((learning) => this.toIndexEntry(learning))
|
||||
.sort((a, b) => {
|
||||
const scoreA = (a.effectiveness ?? 50) + a.useCount * 5;
|
||||
const scoreB = (b.effectiveness ?? 50) + b.useCount * 5;
|
||||
return scoreB - scoreA;
|
||||
})
|
||||
.slice(0, options.maxResults ?? 50);
|
||||
}
|
||||
|
||||
/**
|
||||
* Layer 2: Get timeline entries for specific IDs
|
||||
* Medium tokens (~200 per entry)
|
||||
*/
|
||||
getTimeline(ids: string[], options: ProgressiveDisclosureOptions = {}): TimelineEntry[] {
|
||||
const entries: TimelineEntry[] = [];
|
||||
|
||||
for (const id of ids) {
|
||||
let learning = this.projectStore.getById(id);
|
||||
if (!learning && options.includeGlobal) {
|
||||
learning = this.globalStore.getById(id);
|
||||
}
|
||||
|
||||
if (learning) {
|
||||
entries.push(this.toTimelineEntry(learning));
|
||||
}
|
||||
}
|
||||
|
||||
return entries.slice(0, options.maxResults ?? 20);
|
||||
}
|
||||
|
||||
/**
|
||||
* Layer 3: Get full details for specific IDs
|
||||
* High tokens (~500-1000 per entry)
|
||||
*/
|
||||
getDetails(ids: string[], options: ProgressiveDisclosureOptions = {}): DetailsEntry[] {
|
||||
const entries: DetailsEntry[] = [];
|
||||
|
||||
for (const id of ids) {
|
||||
let learning = this.projectStore.getById(id);
|
||||
let store = this.projectStore;
|
||||
|
||||
if (!learning && options.includeGlobal) {
|
||||
learning = this.globalStore.getById(id);
|
||||
store = this.globalStore;
|
||||
}
|
||||
|
||||
if (learning) {
|
||||
store.incrementUseCount(id);
|
||||
entries.push(this.toDetailsEntry(learning));
|
||||
}
|
||||
}
|
||||
|
||||
return entries.slice(0, options.maxResults ?? 10);
|
||||
}
|
||||
|
||||
/**
|
||||
* Smart retrieval with automatic layer selection
|
||||
* Uses minimum tokens needed to satisfy the query.
|
||||
*
|
||||
* Note: tokensUsed reflects cumulative cost of the retrieval operation
|
||||
* (index lookup + any deeper layer fetches), not just the returned entries.
|
||||
* This is intentional since progressive disclosure requires scanning
|
||||
* the index first before fetching timeline/details.
|
||||
*/
|
||||
smartRetrieve(
|
||||
query: string,
|
||||
tokenBudget: number = 2000,
|
||||
options: ProgressiveDisclosureOptions = {}
|
||||
): {
|
||||
layer: 1 | 2 | 3;
|
||||
entries: IndexEntry[] | TimelineEntry[] | DetailsEntry[];
|
||||
tokensUsed: number;
|
||||
tokensRemaining: number;
|
||||
} {
|
||||
if (tokenBudget <= 0) {
|
||||
return {
|
||||
layer: 1,
|
||||
entries: [],
|
||||
tokensUsed: 0,
|
||||
tokensRemaining: 0,
|
||||
};
|
||||
}
|
||||
|
||||
const index = this.getIndex(options);
|
||||
|
||||
if (index.length === 0) {
|
||||
return {
|
||||
layer: 1,
|
||||
entries: [],
|
||||
tokensUsed: 0,
|
||||
tokensRemaining: tokenBudget,
|
||||
};
|
||||
}
|
||||
|
||||
const indexTokens = index.length * TOKEN_ESTIMATES.index;
|
||||
|
||||
if (tokenBudget < indexTokens) {
|
||||
const maxEntries = Math.floor(tokenBudget / TOKEN_ESTIMATES.index);
|
||||
const limitedIndex = index.slice(0, maxEntries);
|
||||
return {
|
||||
layer: 1,
|
||||
entries: limitedIndex,
|
||||
tokensUsed: limitedIndex.length * TOKEN_ESTIMATES.index,
|
||||
tokensRemaining: tokenBudget - limitedIndex.length * TOKEN_ESTIMATES.index,
|
||||
};
|
||||
}
|
||||
|
||||
const relevantIds = this.findRelevantIds(index, query, options.minRelevance ?? 0);
|
||||
|
||||
if (relevantIds.length === 0) {
|
||||
return {
|
||||
layer: 1,
|
||||
entries: index,
|
||||
tokensUsed: indexTokens,
|
||||
tokensRemaining: tokenBudget - indexTokens,
|
||||
};
|
||||
}
|
||||
|
||||
const remainingBudget = tokenBudget - indexTokens;
|
||||
const maxTimelineEntries = Math.floor(remainingBudget / TOKEN_ESTIMATES.timeline);
|
||||
|
||||
if (maxTimelineEntries >= 1) {
|
||||
const timelineIds = relevantIds.slice(0, Math.min(maxTimelineEntries, 10));
|
||||
const timeline = this.getTimeline(timelineIds, options);
|
||||
const timelineTokens = timeline.length * TOKEN_ESTIMATES.timeline;
|
||||
|
||||
const afterTimelineBudget = remainingBudget - timelineTokens;
|
||||
const maxDetailsEntries = Math.floor(afterTimelineBudget / TOKEN_ESTIMATES.details);
|
||||
|
||||
if (maxDetailsEntries >= 1) {
|
||||
const detailsIds = timelineIds.slice(0, Math.min(maxDetailsEntries, 5));
|
||||
const details = this.getDetails(detailsIds, options);
|
||||
const detailsTokens = details.length * TOKEN_ESTIMATES.details;
|
||||
|
||||
return {
|
||||
layer: 3,
|
||||
entries: details,
|
||||
tokensUsed: indexTokens + timelineTokens + detailsTokens,
|
||||
tokensRemaining: tokenBudget - (indexTokens + timelineTokens + detailsTokens),
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
layer: 2,
|
||||
entries: timeline,
|
||||
tokensUsed: indexTokens + timelineTokens,
|
||||
tokensRemaining: tokenBudget - (indexTokens + timelineTokens),
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
layer: 1,
|
||||
entries: index,
|
||||
tokensUsed: indexTokens,
|
||||
tokensRemaining: tokenBudget - indexTokens,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Estimate tokens for a given layer and count
|
||||
*/
|
||||
estimateTokens(layer: 1 | 2 | 3, count: number): number {
|
||||
const estimate = {
|
||||
1: TOKEN_ESTIMATES.index,
|
||||
2: TOKEN_ESTIMATES.timeline,
|
||||
3: TOKEN_ESTIMATES.details,
|
||||
};
|
||||
return estimate[layer] * count;
|
||||
}
|
||||
|
||||
/**
|
||||
* Format entries for injection
|
||||
*/
|
||||
formatForInjection(
|
||||
entries: IndexEntry[] | TimelineEntry[] | DetailsEntry[],
|
||||
layer: 1 | 2 | 3
|
||||
): string {
|
||||
if (entries.length === 0) return '';
|
||||
|
||||
const lines: string[] = ['<skillkit-memories>'];
|
||||
|
||||
switch (layer) {
|
||||
case 1:
|
||||
lines.push('<!-- Memory Index (summaries only) -->');
|
||||
for (const entry of entries as IndexEntry[]) {
|
||||
lines.push(`- [${entry.id.slice(0, 8)}] ${entry.title} (${entry.tags.join(', ')})`);
|
||||
}
|
||||
break;
|
||||
|
||||
case 2:
|
||||
lines.push('<!-- Memory Timeline (with context) -->');
|
||||
for (const entry of entries as TimelineEntry[]) {
|
||||
lines.push(`## ${entry.title}`);
|
||||
lines.push(`ID: ${entry.id.slice(0, 8)} | Tags: ${entry.tags.join(', ')}`);
|
||||
if (entry.frameworks && entry.frameworks.length > 0) {
|
||||
lines.push(`Frameworks: ${entry.frameworks.join(', ')}`);
|
||||
}
|
||||
lines.push('');
|
||||
lines.push(entry.excerpt);
|
||||
lines.push('');
|
||||
}
|
||||
break;
|
||||
|
||||
case 3:
|
||||
lines.push('<!-- Memory Details (full content) -->');
|
||||
for (const entry of entries as DetailsEntry[]) {
|
||||
lines.push(`## ${entry.title}`);
|
||||
lines.push(`ID: ${entry.id.slice(0, 8)} | Tags: ${entry.tags.join(', ')}`);
|
||||
if (entry.frameworks && entry.frameworks.length > 0) {
|
||||
lines.push(`Frameworks: ${entry.frameworks.join(', ')}`);
|
||||
}
|
||||
if (entry.patterns && entry.patterns.length > 0) {
|
||||
lines.push(`Patterns: ${entry.patterns.join(', ')}`);
|
||||
}
|
||||
lines.push('');
|
||||
lines.push(entry.content);
|
||||
lines.push('');
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
lines.push('</skillkit-memories>');
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
private toIndexEntry(learning: Learning): IndexEntry {
|
||||
return {
|
||||
id: learning.id,
|
||||
title: learning.title,
|
||||
timestamp: learning.updatedAt,
|
||||
tags: learning.tags,
|
||||
scope: learning.scope,
|
||||
effectiveness: learning.effectiveness,
|
||||
useCount: learning.useCount,
|
||||
};
|
||||
}
|
||||
|
||||
private toTimelineEntry(learning: Learning): TimelineEntry {
|
||||
const timeline = this.buildActivityTimeline(learning);
|
||||
|
||||
return {
|
||||
id: learning.id,
|
||||
title: learning.title,
|
||||
timestamp: learning.updatedAt,
|
||||
tags: learning.tags,
|
||||
scope: learning.scope,
|
||||
effectiveness: learning.effectiveness,
|
||||
useCount: learning.useCount,
|
||||
excerpt: learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''),
|
||||
frameworks: learning.frameworks,
|
||||
patterns: learning.patterns,
|
||||
sourceCount: learning.sourceObservations?.length ?? 0,
|
||||
lastUsed: learning.lastUsed,
|
||||
activityTimeline: timeline,
|
||||
};
|
||||
}
|
||||
|
||||
private toDetailsEntry(learning: Learning): DetailsEntry {
|
||||
const timeline = this.buildActivityTimeline(learning);
|
||||
|
||||
return {
|
||||
id: learning.id,
|
||||
title: learning.title,
|
||||
timestamp: learning.updatedAt,
|
||||
tags: learning.tags,
|
||||
scope: learning.scope,
|
||||
effectiveness: learning.effectiveness,
|
||||
useCount: learning.useCount,
|
||||
excerpt: learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''),
|
||||
frameworks: learning.frameworks,
|
||||
patterns: learning.patterns,
|
||||
sourceCount: learning.sourceObservations?.length ?? 0,
|
||||
lastUsed: learning.lastUsed,
|
||||
activityTimeline: timeline,
|
||||
content: learning.content,
|
||||
sourceObservations: learning.sourceObservations,
|
||||
};
|
||||
}
|
||||
|
||||
private buildActivityTimeline(learning: Learning): ActivityPoint[] {
|
||||
const timeline: ActivityPoint[] = [];
|
||||
|
||||
timeline.push({
|
||||
timestamp: learning.createdAt,
|
||||
type: 'created',
|
||||
description: `Learning created from ${learning.source}`,
|
||||
});
|
||||
|
||||
if (learning.updatedAt !== learning.createdAt) {
|
||||
timeline.push({
|
||||
timestamp: learning.updatedAt,
|
||||
type: 'updated',
|
||||
});
|
||||
}
|
||||
|
||||
if (learning.lastUsed) {
|
||||
timeline.push({
|
||||
timestamp: learning.lastUsed,
|
||||
type: 'used',
|
||||
description: `Used ${learning.useCount} times`,
|
||||
});
|
||||
}
|
||||
|
||||
if (learning.effectiveness !== undefined) {
|
||||
timeline.push({
|
||||
timestamp: learning.updatedAt,
|
||||
type: 'rated',
|
||||
description: `Effectiveness: ${learning.effectiveness}%`,
|
||||
});
|
||||
}
|
||||
|
||||
return timeline.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
|
||||
}
|
||||
|
||||
private findRelevantIds(index: IndexEntry[], query: string, minRelevance: number = 0): string[] {
|
||||
const queryWords = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
|
||||
const scored: Array<{ id: string; score: number }> = [];
|
||||
|
||||
for (const entry of index) {
|
||||
let score = 0;
|
||||
|
||||
const titleWords = entry.title.toLowerCase().split(/\s+/);
|
||||
for (const qw of queryWords) {
|
||||
if (titleWords.some((tw) => tw.includes(qw))) {
|
||||
score += 10;
|
||||
}
|
||||
}
|
||||
|
||||
const tags = entry.tags.map((t) => t.toLowerCase());
|
||||
for (const qw of queryWords) {
|
||||
if (tags.includes(qw)) {
|
||||
score += 20;
|
||||
}
|
||||
}
|
||||
|
||||
score += (entry.effectiveness ?? 50) / 10;
|
||||
score += Math.min(entry.useCount * 2, 20);
|
||||
|
||||
if (score >= minRelevance) {
|
||||
scored.push({ id: entry.id, score });
|
||||
}
|
||||
}
|
||||
|
||||
return scored
|
||||
.sort((a, b) => b.score - a.score)
|
||||
.map((s) => s.id);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a progressive disclosure manager
|
||||
*/
|
||||
export function createProgressiveDisclosureManager(
|
||||
projectPath: string,
|
||||
projectName?: string
|
||||
): ProgressiveDisclosureManager {
|
||||
return new ProgressiveDisclosureManager(projectPath, projectName);
|
||||
}
|
||||
@@ -0,0 +1,94 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { stripFrontmatter, parseSkillMd, discoverReferences } from '../references.js';
|
||||
|
||||
vi.mock('node:fs', () => ({
|
||||
existsSync: vi.fn(),
|
||||
readdirSync: vi.fn(),
|
||||
statSync: vi.fn(),
|
||||
readFileSync: vi.fn(),
|
||||
}));
|
||||
|
||||
import { existsSync, readdirSync, statSync } from 'node:fs';
|
||||
|
||||
const mockExistsSync = vi.mocked(existsSync);
|
||||
const mockReaddirSync = vi.mocked(readdirSync);
|
||||
const mockStatSync = vi.mocked(statSync);
|
||||
|
||||
describe('stripFrontmatter', () => {
|
||||
it('extracts frontmatter and body', () => {
|
||||
const raw = `---
|
||||
name: my-skill
|
||||
version: 1.0
|
||||
---
|
||||
# My Skill
|
||||
|
||||
Content here.`;
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter.name).toBe('my-skill');
|
||||
expect(result.frontmatter.version).toBe('1.0');
|
||||
expect(result.body).toContain('# My Skill');
|
||||
expect(result.body).toContain('Content here.');
|
||||
});
|
||||
|
||||
it('returns empty frontmatter when no delimiters', () => {
|
||||
const raw = '# Just content\n\nNo frontmatter.';
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter).toEqual({});
|
||||
expect(result.body).toBe(raw);
|
||||
});
|
||||
|
||||
it('handles empty frontmatter block', () => {
|
||||
const raw = '---\n---\nBody text';
|
||||
const result = stripFrontmatter(raw);
|
||||
expect(result.frontmatter).toEqual({});
|
||||
expect(result.body).toBe('Body text');
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseSkillMd', () => {
|
||||
it('parses raw content without skill dir', () => {
|
||||
const raw = `---
|
||||
name: test
|
||||
---
|
||||
Body content`;
|
||||
const result = parseSkillMd(raw);
|
||||
expect(result.frontmatter.name).toBe('test');
|
||||
expect(result.body).toBe('Body content');
|
||||
expect(result.references).toEqual([]);
|
||||
expect(result.raw).toBe(raw);
|
||||
});
|
||||
});
|
||||
|
||||
describe('discoverReferences', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it('finds files in reference directories', () => {
|
||||
mockExistsSync.mockImplementation((p) => {
|
||||
return String(p).endsWith('/examples');
|
||||
});
|
||||
mockStatSync.mockImplementation((p) => {
|
||||
const path = String(p);
|
||||
if (path.endsWith('/examples')) {
|
||||
return { isDirectory: () => true, isFile: () => false } as any;
|
||||
}
|
||||
return { isDirectory: () => false, isFile: () => true } as any;
|
||||
});
|
||||
mockReaddirSync.mockReturnValue(['demo.ts', 'readme.md'] as any);
|
||||
|
||||
const refs = discoverReferences('/fake/skill');
|
||||
expect(refs).toHaveLength(2);
|
||||
expect(refs[0]).toEqual({
|
||||
path: 'examples/demo.ts',
|
||||
type: 'example',
|
||||
name: 'demo.ts',
|
||||
});
|
||||
});
|
||||
|
||||
it('returns empty array when no reference dirs exist', () => {
|
||||
mockExistsSync.mockReturnValue(false);
|
||||
const refs = discoverReferences('/fake/skill');
|
||||
expect(refs).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './references.js';
|
||||
@@ -0,0 +1,105 @@
|
||||
import { readdirSync, statSync, existsSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
|
||||
export interface SkillReference {
|
||||
path: string;
|
||||
type: 'example' | 'doc' | 'resource' | 'asset';
|
||||
name: string;
|
||||
}
|
||||
|
||||
export interface ParsedSkillContent {
|
||||
frontmatter: Record<string, unknown>;
|
||||
body: string;
|
||||
references: SkillReference[];
|
||||
raw: string;
|
||||
}
|
||||
|
||||
const REFERENCE_DIRS = ['references', 'resources', 'docs', 'examples', 'assets', 'scripts'];
|
||||
|
||||
const DIR_TYPE_MAP: Record<string, SkillReference['type']> = {
|
||||
references: 'resource',
|
||||
resources: 'resource',
|
||||
docs: 'doc',
|
||||
examples: 'example',
|
||||
assets: 'asset',
|
||||
scripts: 'resource',
|
||||
};
|
||||
|
||||
export function discoverReferences(skillDir: string): SkillReference[] {
|
||||
const refs: SkillReference[] = [];
|
||||
|
||||
for (const dir of REFERENCE_DIRS) {
|
||||
const fullPath = join(skillDir, dir);
|
||||
if (!existsSync(fullPath)) continue;
|
||||
|
||||
try {
|
||||
const stat = statSync(fullPath);
|
||||
if (!stat.isDirectory()) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
const type = DIR_TYPE_MAP[dir] || 'resource';
|
||||
try {
|
||||
const entries = readdirSync(fullPath);
|
||||
for (const entry of entries) {
|
||||
const entryPath = join(fullPath, entry);
|
||||
try {
|
||||
const entryStat = statSync(entryPath);
|
||||
if (entryStat.isFile()) {
|
||||
refs.push({
|
||||
path: join(dir, entry),
|
||||
type,
|
||||
name: entry,
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return refs;
|
||||
}
|
||||
|
||||
export function stripFrontmatter(raw: string): { frontmatter: Record<string, unknown>; body: string } {
|
||||
const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
|
||||
if (!match) {
|
||||
const emptyMatch = raw.match(/^---\r?\n---\r?\n?([\s\S]*)$/);
|
||||
if (emptyMatch) {
|
||||
return { frontmatter: {}, body: emptyMatch[1] };
|
||||
}
|
||||
return { frontmatter: {}, body: raw };
|
||||
}
|
||||
|
||||
const fmBlock = match[1];
|
||||
const body = match[2];
|
||||
|
||||
const frontmatter: Record<string, unknown> = {};
|
||||
for (const line of fmBlock.split('\n')) {
|
||||
const colonIdx = line.indexOf(':');
|
||||
if (colonIdx === -1) continue;
|
||||
const key = line.slice(0, colonIdx).trim();
|
||||
const value = line.slice(colonIdx + 1).trim();
|
||||
if (key) {
|
||||
frontmatter[key] = value;
|
||||
}
|
||||
}
|
||||
|
||||
return { frontmatter, body };
|
||||
}
|
||||
|
||||
export function parseSkillMd(raw: string, skillDir?: string): ParsedSkillContent {
|
||||
const { frontmatter, body } = stripFrontmatter(raw);
|
||||
const references = skillDir ? discoverReferences(skillDir) : [];
|
||||
|
||||
return {
|
||||
frontmatter,
|
||||
body,
|
||||
references,
|
||||
raw,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { RelevanceRanker } from '../relevance.js';
|
||||
import type { RankableSkill } from '../relevance.js';
|
||||
|
||||
describe('RelevanceRanker', () => {
|
||||
const ranker = new RelevanceRanker();
|
||||
|
||||
const skills: RankableSkill[] = [
|
||||
{
|
||||
name: 'react-performance',
|
||||
description: 'Optimize React app performance',
|
||||
content: 'Full guide on React performance optimization',
|
||||
stars: 150,
|
||||
references: ['examples/demo.ts'],
|
||||
},
|
||||
{
|
||||
name: 'testing-basics',
|
||||
description: 'Unit testing fundamentals',
|
||||
stars: 10,
|
||||
},
|
||||
{
|
||||
name: 'empty-skill',
|
||||
},
|
||||
];
|
||||
|
||||
it('ranks skills by relevance score', () => {
|
||||
const results = ranker.rank(skills);
|
||||
expect(results).toHaveLength(3);
|
||||
expect(results[0].skill.name).toBe('react-performance');
|
||||
expect(results[0].score).toBeGreaterThan(results[1].score);
|
||||
});
|
||||
|
||||
it('gives max content score for description + content', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const full = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(full.breakdown.contentAvailability).toBe(40);
|
||||
});
|
||||
|
||||
it('gives partial content score for description only', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const partial = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(partial.breakdown.contentAvailability).toBe(20);
|
||||
});
|
||||
|
||||
it('gives zero content score for empty skill', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const empty = results.find((r) => r.skill.name === 'empty-skill')!;
|
||||
expect(empty.breakdown.contentAvailability).toBe(0);
|
||||
});
|
||||
|
||||
it('boosts exact name match on query', () => {
|
||||
const results = ranker.rank(skills, 'react-performance');
|
||||
const match = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(match.breakdown.queryMatch).toBe(30);
|
||||
});
|
||||
|
||||
it('gives partial query match for substring', () => {
|
||||
const results = ranker.rank(skills, 'react');
|
||||
const match = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
expect(match.breakdown.queryMatch).toBeGreaterThan(0);
|
||||
expect(match.breakdown.queryMatch).toBeLessThan(30);
|
||||
});
|
||||
|
||||
it('scores popularity via log scale', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const popular = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
const less = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(popular.breakdown.popularity).toBeGreaterThan(less.breakdown.popularity);
|
||||
});
|
||||
|
||||
it('scores references', () => {
|
||||
const results = ranker.rank(skills);
|
||||
const withRefs = results.find((r) => r.skill.name === 'react-performance')!;
|
||||
const noRefs = results.find((r) => r.skill.name === 'testing-basics')!;
|
||||
expect(withRefs.breakdown.referenceScore).toBeGreaterThan(0);
|
||||
expect(noRefs.breakdown.referenceScore).toBe(0);
|
||||
});
|
||||
|
||||
it('returns zero query match when no query provided', () => {
|
||||
const results = ranker.rank(skills);
|
||||
for (const r of results) {
|
||||
expect(r.breakdown.queryMatch).toBe(0);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './relevance.js';
|
||||
@@ -0,0 +1,92 @@
|
||||
export interface RankableSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
content?: string;
|
||||
stars?: number;
|
||||
installs?: number;
|
||||
references?: string[];
|
||||
}
|
||||
|
||||
export interface RankedSkill<T extends RankableSkill = RankableSkill> {
|
||||
skill: T;
|
||||
score: number;
|
||||
breakdown: ScoreBreakdown;
|
||||
}
|
||||
|
||||
export interface ScoreBreakdown {
|
||||
contentAvailability: number;
|
||||
queryMatch: number;
|
||||
popularity: number;
|
||||
referenceScore: number;
|
||||
}
|
||||
|
||||
const WEIGHTS = {
|
||||
contentAvailability: 40,
|
||||
queryMatch: 30,
|
||||
popularity: 15,
|
||||
references: 15,
|
||||
} as const;
|
||||
|
||||
export class RelevanceRanker {
|
||||
rank<T extends RankableSkill>(skills: T[], query?: string): RankedSkill<T>[] {
|
||||
const results = skills.map((skill) => {
|
||||
const breakdown = this.score(skill, query);
|
||||
const score =
|
||||
breakdown.contentAvailability +
|
||||
breakdown.queryMatch +
|
||||
breakdown.popularity +
|
||||
breakdown.referenceScore;
|
||||
return { skill, score, breakdown };
|
||||
});
|
||||
|
||||
results.sort((a, b) => b.score - a.score);
|
||||
return results;
|
||||
}
|
||||
|
||||
private score(skill: RankableSkill, query?: string): ScoreBreakdown {
|
||||
return {
|
||||
contentAvailability: this.scoreContent(skill),
|
||||
queryMatch: query ? this.scoreQuery(skill, query) : 0,
|
||||
popularity: this.scorePopularity(skill),
|
||||
referenceScore: this.scoreReferences(skill),
|
||||
};
|
||||
}
|
||||
|
||||
private scoreContent(skill: RankableSkill): number {
|
||||
let score = 0;
|
||||
if (skill.description && skill.description.length > 0) score += 20;
|
||||
if (skill.content && skill.content.length > 0) score += 20;
|
||||
return score;
|
||||
}
|
||||
|
||||
private scoreQuery(skill: RankableSkill, query: string): number {
|
||||
const q = query.toLowerCase();
|
||||
const name = skill.name.toLowerCase();
|
||||
|
||||
if (name === q) return WEIGHTS.queryMatch;
|
||||
|
||||
if (name.includes(q) || q.includes(name)) {
|
||||
return WEIGHTS.queryMatch * 0.7;
|
||||
}
|
||||
|
||||
const desc = (skill.description || '').toLowerCase();
|
||||
const content = (skill.content || '').toLowerCase();
|
||||
const searchable = `${name} ${desc} ${content}`;
|
||||
const words = q.split(/\s+/).filter(Boolean);
|
||||
const matched = words.filter((w) => searchable.includes(w)).length;
|
||||
|
||||
if (words.length === 0) return 0;
|
||||
return Math.round(WEIGHTS.queryMatch * (matched / words.length) * 0.6);
|
||||
}
|
||||
|
||||
private scorePopularity(skill: RankableSkill): number {
|
||||
const count = (skill.stars ?? 0) + (skill.installs ?? 0);
|
||||
if (count <= 0) return 0;
|
||||
return Math.min(WEIGHTS.popularity, Math.round(Math.log10(count + 1) * 5));
|
||||
}
|
||||
|
||||
private scoreReferences(skill: RankableSkill): number {
|
||||
if (!skill.references || skill.references.length === 0) return 0;
|
||||
return Math.min(WEIGHTS.references, skill.references.length * 5);
|
||||
}
|
||||
}
|
||||
@@ -11,8 +11,11 @@ import type {
|
||||
SearchOptions,
|
||||
SearchResult,
|
||||
FreshnessResult,
|
||||
RecommendHybridSearchOptions,
|
||||
RecommendHybridSearchResult,
|
||||
} from './types.js';
|
||||
import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
|
||||
import type { HybridSearchPipeline } from '../search/hybrid.js';
|
||||
|
||||
/**
|
||||
* Recommendation engine for matching skills to project profiles
|
||||
@@ -20,16 +23,39 @@ import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
|
||||
export class RecommendationEngine {
|
||||
private weights: ScoringWeights;
|
||||
private index: SkillIndex | null = null;
|
||||
private hybridPipeline: HybridSearchPipeline | null = null;
|
||||
|
||||
constructor(weights?: Partial<ScoringWeights>) {
|
||||
this.weights = { ...DEFAULT_SCORING_WEIGHTS, ...weights };
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize hybrid search pipeline for vector + keyword search
|
||||
*/
|
||||
async initHybridSearch(): Promise<void> {
|
||||
const { createHybridSearchPipeline } = await import('../search/hybrid.js');
|
||||
this.hybridPipeline = createHybridSearchPipeline();
|
||||
if (this.index) {
|
||||
this.hybridPipeline.loadSkillsIndex(this.index);
|
||||
}
|
||||
await this.hybridPipeline.initialize();
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if hybrid search is available
|
||||
*/
|
||||
isHybridSearchAvailable(): boolean {
|
||||
return this.hybridPipeline !== null && this.hybridPipeline.isInitialized();
|
||||
}
|
||||
|
||||
/**
|
||||
* Load skill index from cache or generate from local skills
|
||||
*/
|
||||
loadIndex(index: SkillIndex): void {
|
||||
this.index = index;
|
||||
if (this.hybridPipeline) {
|
||||
this.hybridPipeline.loadSkillsIndex(index);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -603,6 +629,71 @@ export class RecommendationEngine {
|
||||
return { relevance, matchedTerms, snippet };
|
||||
}
|
||||
|
||||
/**
|
||||
* Hybrid search combining vector embeddings and keyword matching
|
||||
*/
|
||||
async hybridSearch(options: RecommendHybridSearchOptions): Promise<RecommendHybridSearchResult[]> {
|
||||
const { query, limit = 10, hybrid = true, enableExpansion = false, enableReranking = false, filters } = options;
|
||||
|
||||
if (!hybrid || !this.hybridPipeline) {
|
||||
const basicResults = this.search({ query, limit, semantic: true, filters });
|
||||
return basicResults.map((r) => ({
|
||||
...r,
|
||||
hybridScore: r.relevance / 100,
|
||||
}));
|
||||
}
|
||||
|
||||
const response = await this.hybridPipeline.search({
|
||||
query,
|
||||
limit,
|
||||
enableExpansion,
|
||||
enableReranking,
|
||||
});
|
||||
|
||||
let results = response.results.map((r) => ({
|
||||
skill: r.skill,
|
||||
relevance: r.relevance,
|
||||
matchedTerms: r.matchedTerms,
|
||||
snippet: r.snippet,
|
||||
hybridScore: r.hybridScore,
|
||||
vectorSimilarity: r.vectorSimilarity,
|
||||
keywordScore: r.keywordScore,
|
||||
rrfScore: r.rrfScore,
|
||||
expandedTerms: r.expandedTerms,
|
||||
}));
|
||||
|
||||
if (filters?.tags && filters.tags.length > 0) {
|
||||
results = results.filter((r) =>
|
||||
r.skill.tags?.some((t) => filters.tags!.includes(t))
|
||||
);
|
||||
}
|
||||
if (filters?.verified) {
|
||||
results = results.filter((r) => r.skill.verified);
|
||||
}
|
||||
if (filters?.minScore) {
|
||||
results = results.filter((r) => r.relevance >= filters.minScore!);
|
||||
}
|
||||
|
||||
return results.slice(0, limit);
|
||||
}
|
||||
|
||||
/**
|
||||
* Build hybrid search index from skills
|
||||
*/
|
||||
async buildHybridIndex(
|
||||
onProgress?: (progress: { phase: string; current: number; total: number; message?: string }) => void
|
||||
): Promise<void> {
|
||||
if (!this.index) {
|
||||
throw new Error('No skill index loaded. Call loadIndex() first.');
|
||||
}
|
||||
|
||||
if (!this.hybridPipeline) {
|
||||
await this.initHybridSearch();
|
||||
}
|
||||
|
||||
await this.hybridPipeline!.buildIndex(this.index.skills, onProgress);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check freshness of installed skills against project dependencies
|
||||
*
|
||||
|
||||
@@ -326,3 +326,25 @@ export interface ReasoningRecommendationResult extends RecommendationResult {
|
||||
strategy: string;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Hybrid search options for RecommendationEngine
|
||||
*/
|
||||
export interface RecommendHybridSearchOptions extends SearchOptions {
|
||||
hybrid?: boolean;
|
||||
enableExpansion?: boolean;
|
||||
enableReranking?: boolean;
|
||||
semanticWeight?: number;
|
||||
keywordWeight?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hybrid search result with additional metadata for RecommendationEngine
|
||||
*/
|
||||
export interface RecommendHybridSearchResult extends SearchResult {
|
||||
hybridScore?: number;
|
||||
vectorSimilarity?: number;
|
||||
keywordScore?: number;
|
||||
rrfScore?: number;
|
||||
expandedTerms?: string[];
|
||||
}
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { CommunityRegistry } from '../community.js';
|
||||
|
||||
vi.mock('node:fs', () => ({
|
||||
existsSync: vi.fn(),
|
||||
readFileSync: vi.fn(),
|
||||
}));
|
||||
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
|
||||
const mockExistsSync = vi.mocked(existsSync);
|
||||
const mockReadFileSync = vi.mocked(readFileSync);
|
||||
|
||||
const SAMPLE_SKILLS_MD = `# SkillKit Community Skills Registry
|
||||
|
||||
## Code Quality
|
||||
|
||||
- [code-simplifier](https://github.com/anthropics/skills) - Simplifies and refines code
|
||||
- [code-review](https://github.com/anthropics/skills) - Automated code review
|
||||
|
||||
## Testing
|
||||
|
||||
- [testing-guide](https://github.com/anthropics/skills) - Unit testing fundamentals
|
||||
- [e2e-testing](https://github.com/anthropics/skills) - End-to-end testing with Playwright
|
||||
`;
|
||||
|
||||
describe('CommunityRegistry', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mockExistsSync.mockReturnValue(true);
|
||||
mockReadFileSync.mockReturnValue(SAMPLE_SKILLS_MD);
|
||||
});
|
||||
|
||||
it('parses SKILLS.md entries', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('code');
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results[0].registry).toBe('community');
|
||||
expect(results[0].name).toBe('code-simplifier');
|
||||
});
|
||||
|
||||
it('searches by description', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('Playwright');
|
||||
expect(results.length).toBe(1);
|
||||
expect(results[0].name).toBe('e2e-testing');
|
||||
});
|
||||
|
||||
it('searches by category', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('Testing');
|
||||
expect(results.length).toBe(2);
|
||||
});
|
||||
|
||||
it('respects limit', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('code', { limit: 1 });
|
||||
expect(results.length).toBe(1);
|
||||
});
|
||||
|
||||
it('returns empty when no match', async () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const results = await registry.search('nonexistent-xyz');
|
||||
expect(results.length).toBe(0);
|
||||
});
|
||||
|
||||
it('getAll returns all entries', () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const all = registry.getAll();
|
||||
expect(all.length).toBe(4);
|
||||
});
|
||||
|
||||
it('getCategories returns unique categories', () => {
|
||||
const registry = new CommunityRegistry('/fake/SKILLS.md');
|
||||
const cats = registry.getCategories();
|
||||
expect(cats).toContain('Code Quality');
|
||||
expect(cats).toContain('Testing');
|
||||
expect(cats.length).toBe(2);
|
||||
});
|
||||
|
||||
it('handles missing file gracefully', async () => {
|
||||
mockExistsSync.mockReturnValue(false);
|
||||
const registry = new CommunityRegistry('/missing/SKILLS.md');
|
||||
const results = await registry.search('anything');
|
||||
expect(results).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,97 @@
|
||||
import { readFileSync, existsSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import type { ExternalRegistry, ExternalSkill } from './index.js';
|
||||
|
||||
interface ParsedEntry {
|
||||
name: string;
|
||||
url: string;
|
||||
description: string;
|
||||
category: string;
|
||||
}
|
||||
|
||||
export class CommunityRegistry implements ExternalRegistry {
|
||||
name = 'community';
|
||||
private entries: ParsedEntry[] = [];
|
||||
private loaded = false;
|
||||
|
||||
constructor(private skillsMdPath?: string) {}
|
||||
|
||||
private load(): void {
|
||||
if (this.loaded) return;
|
||||
this.loaded = true;
|
||||
|
||||
const paths = this.skillsMdPath
|
||||
? [this.skillsMdPath]
|
||||
: [
|
||||
join(process.cwd(), 'registry', 'SKILLS.md'),
|
||||
join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'registry', 'SKILLS.md'),
|
||||
];
|
||||
|
||||
for (const path of paths) {
|
||||
if (!existsSync(path)) continue;
|
||||
try {
|
||||
const content = readFileSync(path, 'utf-8');
|
||||
this.entries = this.parse(content);
|
||||
return;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private parse(content: string): ParsedEntry[] {
|
||||
const results: ParsedEntry[] = [];
|
||||
let currentCategory = '';
|
||||
|
||||
for (const line of content.split('\n')) {
|
||||
const headerMatch = line.match(/^##\s+(.+)/);
|
||||
if (headerMatch) {
|
||||
currentCategory = headerMatch[1].trim();
|
||||
continue;
|
||||
}
|
||||
|
||||
const entryMatch = line.match(/^-\s+\[([^\]]+)\]\(([^)]+)\)\s*-\s*(.+)/);
|
||||
if (entryMatch) {
|
||||
results.push({
|
||||
name: entryMatch[1].trim(),
|
||||
url: entryMatch[2].trim(),
|
||||
description: entryMatch[3].trim(),
|
||||
category: currentCategory,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
async search(query: string, options?: { limit?: number }): Promise<ExternalSkill[]> {
|
||||
this.load();
|
||||
const limit = options?.limit ?? 20;
|
||||
const q = query.toLowerCase();
|
||||
|
||||
const matched = this.entries.filter(
|
||||
(e) =>
|
||||
e.name.toLowerCase().includes(q) ||
|
||||
e.description.toLowerCase().includes(q) ||
|
||||
e.category.toLowerCase().includes(q),
|
||||
);
|
||||
|
||||
return matched.slice(0, limit).map((e) => ({
|
||||
name: e.name,
|
||||
description: e.description,
|
||||
source: e.url,
|
||||
registry: this.name,
|
||||
}));
|
||||
}
|
||||
|
||||
getAll(): ParsedEntry[] {
|
||||
this.load();
|
||||
return [...this.entries];
|
||||
}
|
||||
|
||||
getCategories(): string[] {
|
||||
this.load();
|
||||
return [...new Set(this.entries.map((e) => e.category))];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,165 @@
|
||||
export interface ExternalSkill {
|
||||
name: string;
|
||||
description: string;
|
||||
source: string;
|
||||
registry: string;
|
||||
path?: string;
|
||||
stars?: number;
|
||||
updatedAt?: string;
|
||||
}
|
||||
|
||||
export interface ExternalRegistry {
|
||||
name: string;
|
||||
search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]>;
|
||||
}
|
||||
|
||||
export interface FederatedResult {
|
||||
skills: ExternalSkill[];
|
||||
registries: string[];
|
||||
total: number;
|
||||
query: string;
|
||||
}
|
||||
|
||||
export class RateLimitError extends Error {
|
||||
constructor(registry: string) {
|
||||
super(`Rate limited by ${registry} API. Authenticate with a token or wait before retrying.`);
|
||||
this.name = 'RateLimitError';
|
||||
}
|
||||
}
|
||||
|
||||
export class GitHubSkillRegistry implements ExternalRegistry {
|
||||
name = 'github';
|
||||
private baseUrl = 'https://api.github.com';
|
||||
|
||||
async search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]> {
|
||||
const limit = options?.limit ?? 20;
|
||||
const timeoutMs = options?.timeoutMs ?? 10_000;
|
||||
const searchQuery = `SKILL.md ${query} in:path,file`;
|
||||
|
||||
const controller = new AbortController();
|
||||
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
||||
|
||||
try {
|
||||
const headers: Record<string, string> = {
|
||||
Accept: 'application/vnd.github.v3+json',
|
||||
'User-Agent': 'skillkit-cli',
|
||||
};
|
||||
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
|
||||
if (token) {
|
||||
headers.Authorization = `Bearer ${token}`;
|
||||
}
|
||||
|
||||
const response = await fetch(
|
||||
`${this.baseUrl}/search/code?q=${encodeURIComponent(searchQuery)}&per_page=${limit}`,
|
||||
{
|
||||
headers,
|
||||
signal: controller.signal,
|
||||
},
|
||||
);
|
||||
clearTimeout(timer);
|
||||
|
||||
if (!response.ok) {
|
||||
if (response.status === 403) {
|
||||
throw new RateLimitError(this.name);
|
||||
}
|
||||
return [];
|
||||
}
|
||||
|
||||
const data = (await response.json()) as {
|
||||
items?: Array<{
|
||||
repository: {
|
||||
full_name: string;
|
||||
description?: string;
|
||||
html_url: string;
|
||||
stargazers_count?: number;
|
||||
updated_at?: string;
|
||||
};
|
||||
path: string;
|
||||
name: string;
|
||||
}>;
|
||||
};
|
||||
|
||||
if (!data.items) return [];
|
||||
|
||||
const seen = new Set<string>();
|
||||
const skills: ExternalSkill[] = [];
|
||||
|
||||
for (const item of data.items) {
|
||||
const repo = item.repository.full_name;
|
||||
if (seen.has(repo)) continue;
|
||||
seen.add(repo);
|
||||
|
||||
const pathParts = item.path.split('/');
|
||||
const skillName =
|
||||
pathParts.length > 1
|
||||
? pathParts[pathParts.length - 2]
|
||||
: repo.split('/').pop() || repo;
|
||||
|
||||
skills.push({
|
||||
name: skillName,
|
||||
description: item.repository.description || '',
|
||||
source: item.repository.html_url,
|
||||
registry: this.name,
|
||||
path: item.path,
|
||||
stars: item.repository.stargazers_count,
|
||||
updatedAt: item.repository.updated_at,
|
||||
});
|
||||
}
|
||||
|
||||
return skills;
|
||||
} catch (err) {
|
||||
clearTimeout(timer);
|
||||
if (err instanceof RateLimitError) throw err;
|
||||
return [];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export { CommunityRegistry } from './community.js';
|
||||
|
||||
export class FederatedSearch {
|
||||
private registries: ExternalRegistry[] = [];
|
||||
|
||||
addRegistry(registry: ExternalRegistry): void {
|
||||
this.registries.push(registry);
|
||||
}
|
||||
|
||||
async search(query: string, options?: { limit?: number }): Promise<FederatedResult> {
|
||||
const limit = options?.limit ?? 20;
|
||||
const results = await Promise.allSettled(
|
||||
this.registries.map((r) => r.search(query, { limit })),
|
||||
);
|
||||
|
||||
const allSkills: ExternalSkill[] = [];
|
||||
const activeRegistries: string[] = [];
|
||||
|
||||
for (let i = 0; i < results.length; i++) {
|
||||
const result = results[i];
|
||||
if (result.status === 'fulfilled' && result.value.length > 0) {
|
||||
allSkills.push(...result.value);
|
||||
activeRegistries.push(this.registries[i].name);
|
||||
} else if (result.status === 'rejected' && result.reason instanceof RateLimitError) {
|
||||
throw result.reason;
|
||||
}
|
||||
}
|
||||
|
||||
const seen = new Set<string>();
|
||||
const deduplicated: ExternalSkill[] = [];
|
||||
for (const skill of allSkills) {
|
||||
const key = `${skill.source}:${skill.name}`;
|
||||
if (!seen.has(key)) {
|
||||
seen.add(key);
|
||||
deduplicated.push(skill);
|
||||
}
|
||||
}
|
||||
|
||||
deduplicated.sort((a, b) => (b.stars ?? 0) - (a.stars ?? 0));
|
||||
|
||||
return {
|
||||
skills: deduplicated.slice(0, limit),
|
||||
registries: activeRegistries,
|
||||
total: deduplicated.length,
|
||||
query,
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
|
||||
import { SkillInjector } from '../injector.js';
|
||||
|
||||
const mockFetch = vi.fn();
|
||||
global.fetch = mockFetch;
|
||||
|
||||
describe('SkillInjector', () => {
|
||||
let injector: SkillInjector;
|
||||
|
||||
beforeEach(() => {
|
||||
injector = new SkillInjector(60_000);
|
||||
mockFetch.mockReset();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
injector.clearCache();
|
||||
});
|
||||
|
||||
const skillMd = `---
|
||||
name: test-skill
|
||||
version: 1.0
|
||||
---
|
||||
# Test Skill
|
||||
|
||||
This is the body content.`;
|
||||
|
||||
it('fetches and parses a SKILL.md from GitHub', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('owner/repo', 'test-skill');
|
||||
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
|
||||
expect(result.skillId).toBe('test-skill');
|
||||
expect(result.parsed.frontmatter.name).toBe('test-skill');
|
||||
expect(result.parsed.body).toContain('# Test Skill');
|
||||
expect(result.fetchedAt).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('returns cached result on subsequent calls', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
await injector.fetch('owner/repo', 'test-skill');
|
||||
const second = await injector.fetch('owner/repo', 'test-skill');
|
||||
expect(mockFetch).toHaveBeenCalledTimes(1);
|
||||
expect(second.parsed.body).toContain('# Test Skill');
|
||||
});
|
||||
|
||||
it('inject() returns body without frontmatter', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const body = await injector.inject('owner/repo', 'test-skill');
|
||||
expect(body).toContain('# Test Skill');
|
||||
expect(body).not.toContain('---');
|
||||
expect(body).not.toContain('name: test-skill');
|
||||
});
|
||||
|
||||
it('throws on invalid source format', async () => {
|
||||
await expect(injector.fetch('invalid', 'skill')).rejects.toThrow('Invalid source format');
|
||||
});
|
||||
|
||||
it('throws when SKILL.md not found after trying all paths', async () => {
|
||||
mockFetch.mockResolvedValue({ ok: false, status: 404 });
|
||||
|
||||
await expect(injector.fetch('owner/repo', 'missing')).rejects.toThrow('SKILL.md not found');
|
||||
});
|
||||
|
||||
it('tries multiple paths before failing', async () => {
|
||||
mockFetch
|
||||
.mockResolvedValueOnce({ ok: false, status: 404 })
|
||||
.mockResolvedValueOnce({ ok: false, status: 404 })
|
||||
.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('owner/repo', 'skill');
|
||||
expect(mockFetch).toHaveBeenCalledTimes(3);
|
||||
expect(result.parsed.body).toContain('# Test Skill');
|
||||
});
|
||||
|
||||
it('reports cache stats', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
await injector.fetch('owner/repo', 'skill');
|
||||
await injector.fetch('owner/repo', 'skill');
|
||||
|
||||
const stats = injector.cacheStats();
|
||||
expect(stats.size).toBe(1);
|
||||
expect(stats.hits).toBe(1);
|
||||
expect(stats.misses).toBe(1);
|
||||
});
|
||||
|
||||
it('parses full GitHub URLs as source', async () => {
|
||||
mockFetch.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
text: async () => skillMd,
|
||||
});
|
||||
|
||||
const result = await injector.fetch('https://github.com/owner/repo', 'skill');
|
||||
expect(result.source).toEqual({ owner: 'owner', repo: 'repo' });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
export * from './injector.js';
|
||||
@@ -0,0 +1,99 @@
|
||||
import { MemoryCache } from '../cache/memory.js';
|
||||
import { parseSkillMd } from '../parser/references.js';
|
||||
import type { ParsedSkillContent } from '../parser/references.js';
|
||||
|
||||
export interface RuntimeSkillSource {
|
||||
owner: string;
|
||||
repo: string;
|
||||
}
|
||||
|
||||
export interface FetchedSkill {
|
||||
source: RuntimeSkillSource;
|
||||
skillId: string;
|
||||
parsed: ParsedSkillContent;
|
||||
fetchedAt: number;
|
||||
}
|
||||
|
||||
function parseSource(source: string): RuntimeSkillSource {
|
||||
const parts = source.replace(/^https?:\/\/github\.com\//, '').split('/');
|
||||
if (parts.length < 2) {
|
||||
throw new Error(`Invalid source format: "${source}". Expected "owner/repo".`);
|
||||
}
|
||||
return { owner: parts[0], repo: parts[1] };
|
||||
}
|
||||
|
||||
export class SkillInjector {
|
||||
private cache: MemoryCache<FetchedSkill>;
|
||||
|
||||
constructor(cacheTtlMs?: number) {
|
||||
this.cache = new MemoryCache<FetchedSkill>({
|
||||
maxSize: 200,
|
||||
ttlMs: cacheTtlMs ?? 24 * 60 * 60 * 1000,
|
||||
});
|
||||
}
|
||||
|
||||
async fetch(source: string, skillId: string): Promise<FetchedSkill> {
|
||||
const cacheKey = `${source}:${skillId}`;
|
||||
const cached = this.cache.get(cacheKey);
|
||||
if (cached) return cached;
|
||||
|
||||
const { owner, repo } = parseSource(source);
|
||||
const raw = await this.fetchRawSkillMd(owner, repo, skillId);
|
||||
const parsed = parseSkillMd(raw);
|
||||
|
||||
const result: FetchedSkill = {
|
||||
source: { owner, repo },
|
||||
skillId,
|
||||
parsed,
|
||||
fetchedAt: Date.now(),
|
||||
};
|
||||
|
||||
this.cache.set(cacheKey, result);
|
||||
return result;
|
||||
}
|
||||
|
||||
async inject(source: string, skillId: string): Promise<string> {
|
||||
const fetched = await this.fetch(source, skillId);
|
||||
return fetched.parsed.body;
|
||||
}
|
||||
|
||||
private async fetchRawSkillMd(owner: string, repo: string, skillId: string): Promise<string> {
|
||||
const paths = [
|
||||
`${skillId}/SKILL.md`,
|
||||
`skills/${skillId}/SKILL.md`,
|
||||
`SKILL.md`,
|
||||
];
|
||||
|
||||
const headers: Record<string, string> = {
|
||||
Accept: 'application/vnd.github.v3.raw',
|
||||
'User-Agent': 'skillkit-runtime',
|
||||
};
|
||||
|
||||
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
|
||||
if (token) {
|
||||
headers.Authorization = `Bearer ${token}`;
|
||||
}
|
||||
|
||||
for (const path of paths) {
|
||||
const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
|
||||
try {
|
||||
const response = await fetch(url, { headers });
|
||||
if (response.ok) {
|
||||
return await response.text();
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`SKILL.md not found in ${owner}/${repo} for skill "${skillId}"`);
|
||||
}
|
||||
|
||||
clearCache(): void {
|
||||
this.cache.clear();
|
||||
}
|
||||
|
||||
cacheStats() {
|
||||
return this.cache.stats();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,217 @@
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { EmbeddingService } from '../embeddings.js';
|
||||
import type { SkillSummary } from '../../recommend/types.js';
|
||||
|
||||
describe('EmbeddingService', () => {
|
||||
describe('cosineSimilarity', () => {
|
||||
let service: EmbeddingService;
|
||||
|
||||
beforeEach(() => {
|
||||
service = new EmbeddingService();
|
||||
});
|
||||
|
||||
it('should return 1 for identical vectors', () => {
|
||||
const a = new Float32Array([1, 0, 0]);
|
||||
const b = new Float32Array([1, 0, 0]);
|
||||
|
||||
const similarity = service.cosineSimilarity(a, b);
|
||||
expect(similarity).toBeCloseTo(1, 5);
|
||||
});
|
||||
|
||||
it('should return 0 for orthogonal vectors', () => {
|
||||
const a = new Float32Array([1, 0, 0]);
|
||||
const b = new Float32Array([0, 1, 0]);
|
||||
|
||||
const similarity = service.cosineSimilarity(a, b);
|
||||
expect(similarity).toBeCloseTo(0, 5);
|
||||
});
|
||||
|
||||
it('should return -1 for opposite vectors', () => {
|
||||
const a = new Float32Array([1, 0, 0]);
|
||||
const b = new Float32Array([-1, 0, 0]);
|
||||
|
||||
const similarity = service.cosineSimilarity(a, b);
|
||||
expect(similarity).toBeCloseTo(-1, 5);
|
||||
});
|
||||
|
||||
it('should handle normalized vectors', () => {
|
||||
const a = new Float32Array([0.5, 0.5, 0.5, 0.5]);
|
||||
const b = new Float32Array([0.5, 0.5, 0.5, 0.5]);
|
||||
|
||||
const similarity = service.cosineSimilarity(a, b);
|
||||
expect(similarity).toBeCloseTo(1, 5);
|
||||
});
|
||||
|
||||
it('should throw for mismatched dimensions', () => {
|
||||
const a = new Float32Array([1, 0]);
|
||||
const b = new Float32Array([1, 0, 0]);
|
||||
|
||||
expect(() => service.cosineSimilarity(a, b)).toThrow('Vector dimensions mismatch');
|
||||
});
|
||||
|
||||
it('should return 0 for zero vectors', () => {
|
||||
const a = new Float32Array([0, 0, 0]);
|
||||
const b = new Float32Array([1, 0, 0]);
|
||||
|
||||
const similarity = service.cosineSimilarity(a, b);
|
||||
expect(similarity).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('initialization state', () => {
|
||||
it('should not be initialized by default', () => {
|
||||
const service = new EmbeddingService();
|
||||
expect(service.isInitialized()).toBe(false);
|
||||
});
|
||||
|
||||
it('should return default dimensions', () => {
|
||||
const service = new EmbeddingService();
|
||||
expect(service.getDimensions()).toBe(768);
|
||||
});
|
||||
});
|
||||
|
||||
describe('skill text building', () => {
|
||||
it('should handle skill with all fields', async () => {
|
||||
const service = new EmbeddingService();
|
||||
const skill: SkillSummary = {
|
||||
name: 'test-skill',
|
||||
description: 'A test skill',
|
||||
tags: ['tag1', 'tag2'],
|
||||
compatibility: {
|
||||
frameworks: ['react'],
|
||||
languages: ['typescript'],
|
||||
libraries: ['lodash'],
|
||||
},
|
||||
popularity: 100,
|
||||
quality: 80,
|
||||
verified: true,
|
||||
};
|
||||
|
||||
const buildSkillText = (s: SkillSummary): string => {
|
||||
const parts: string[] = [s.name];
|
||||
if (s.description) parts.push(s.description);
|
||||
if (s.tags?.length) parts.push(s.tags.join(' '));
|
||||
if (s.compatibility?.frameworks?.length) parts.push(s.compatibility.frameworks.join(' '));
|
||||
if (s.compatibility?.languages?.length) parts.push(s.compatibility.languages.join(' '));
|
||||
if (s.compatibility?.libraries?.length) parts.push(s.compatibility.libraries.join(' '));
|
||||
return parts.join(' ').toLowerCase();
|
||||
};
|
||||
|
||||
const text = buildSkillText(skill);
|
||||
|
||||
expect(text).toContain('test-skill');
|
||||
expect(text).toContain('a test skill');
|
||||
expect(text).toContain('tag1');
|
||||
expect(text).toContain('react');
|
||||
expect(text).toContain('typescript');
|
||||
expect(text).toContain('lodash');
|
||||
});
|
||||
|
||||
it('should handle skill with minimal fields', () => {
|
||||
const skill: SkillSummary = {
|
||||
name: 'minimal-skill',
|
||||
tags: [],
|
||||
popularity: 0,
|
||||
quality: 50,
|
||||
verified: false,
|
||||
};
|
||||
|
||||
const buildSkillText = (s: SkillSummary): string => {
|
||||
const parts: string[] = [s.name];
|
||||
if (s.description) parts.push(s.description);
|
||||
if (s.tags?.length) parts.push(s.tags.join(' '));
|
||||
return parts.join(' ').toLowerCase();
|
||||
};
|
||||
|
||||
const text = buildSkillText(skill);
|
||||
|
||||
expect(text).toBe('minimal-skill');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('EmbeddingService chunking', () => {
|
||||
it('should split text into chunks', () => {
|
||||
const chunkText = (
|
||||
text: string,
|
||||
config = { maxTokens: 100, overlapPercent: 15, minChunkSize: 10 }
|
||||
) => {
|
||||
const lines = text.split('\n');
|
||||
const chunks: { content: string; startLine: number; endLine: number }[] = [];
|
||||
const avgCharsPerToken = 4;
|
||||
const maxCharsPerChunk = config.maxTokens * avgCharsPerToken;
|
||||
const overlapChars = Math.floor(maxCharsPerChunk * (config.overlapPercent / 100));
|
||||
|
||||
let currentChunk: string[] = [];
|
||||
let currentChars = 0;
|
||||
let startLine = 0;
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const lineChars = line.length + 1;
|
||||
|
||||
if (currentChars + lineChars > maxCharsPerChunk && currentChunk.length > 0) {
|
||||
const content = currentChunk.join('\n');
|
||||
if (content.length >= config.minChunkSize) {
|
||||
chunks.push({ content, startLine, endLine: i - 1 });
|
||||
}
|
||||
|
||||
const overlapLines: string[] = [];
|
||||
let overlapCharsCount = 0;
|
||||
for (let j = currentChunk.length - 1; j >= 0 && overlapCharsCount < overlapChars; j--) {
|
||||
overlapLines.unshift(currentChunk[j]);
|
||||
overlapCharsCount += currentChunk[j].length + 1;
|
||||
}
|
||||
|
||||
currentChunk = overlapLines;
|
||||
currentChars = overlapCharsCount;
|
||||
startLine = i - overlapLines.length;
|
||||
}
|
||||
|
||||
currentChunk.push(line);
|
||||
currentChars += lineChars;
|
||||
}
|
||||
|
||||
if (currentChunk.length > 0) {
|
||||
const content = currentChunk.join('\n');
|
||||
if (content.length >= config.minChunkSize) {
|
||||
chunks.push({ content, startLine, endLine: lines.length - 1 });
|
||||
}
|
||||
}
|
||||
|
||||
return chunks;
|
||||
};
|
||||
|
||||
const longText = Array(50).fill('This is a line of text for testing.').join('\n');
|
||||
const chunks = chunkText(longText);
|
||||
|
||||
expect(chunks.length).toBeGreaterThan(1);
|
||||
chunks.forEach((chunk) => {
|
||||
expect(chunk.content.length).toBeLessThanOrEqual(400);
|
||||
expect(chunk.startLine).toBeGreaterThanOrEqual(0);
|
||||
expect(chunk.endLine).toBeGreaterThanOrEqual(chunk.startLine);
|
||||
});
|
||||
});
|
||||
|
||||
it('should not chunk short text', () => {
|
||||
const chunkText = (
|
||||
text: string,
|
||||
config = { maxTokens: 800, overlapPercent: 15, minChunkSize: 100 }
|
||||
) => {
|
||||
const lines = text.split('\n');
|
||||
if (text.length < config.maxTokens * 4) {
|
||||
if (text.length >= config.minChunkSize) {
|
||||
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
|
||||
}
|
||||
return [];
|
||||
}
|
||||
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
|
||||
};
|
||||
|
||||
const shortText = 'This is a short text that should not be chunked.';
|
||||
const chunks = chunkText(shortText, { maxTokens: 800, overlapPercent: 15, minChunkSize: 10 });
|
||||
|
||||
expect(chunks.length).toBe(1);
|
||||
expect(chunks[0].content).toBe(shortText);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,100 @@
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { QueryExpander, expandQuerySimple } from '../expansion.js';
|
||||
|
||||
describe('QueryExpander', () => {
|
||||
let expander: QueryExpander;
|
||||
|
||||
beforeEach(() => {
|
||||
expander = new QueryExpander();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
expander.clearCache();
|
||||
});
|
||||
|
||||
describe('expandQuerySimple (without LLM)', () => {
|
||||
it('should expand "auth" to authentication-related terms', () => {
|
||||
const result = expandQuerySimple('auth');
|
||||
|
||||
expect(result.original).toBe('auth');
|
||||
expect(result.variations.length).toBeGreaterThan(0);
|
||||
expect(result.variations.some((v) => v.includes('authentication'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should expand "api" to related terms', () => {
|
||||
const result = expandQuerySimple('api');
|
||||
|
||||
expect(result.original).toBe('api');
|
||||
expect(result.variations.some((v) => v.includes('rest') || v.includes('endpoint'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should expand "test" to testing-related terms', () => {
|
||||
const result = expandQuerySimple('testing');
|
||||
|
||||
expect(result.original).toBe('testing');
|
||||
expect(result.variations.some((v) => v.includes('test') || v.includes('unit'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should handle queries without synonyms', () => {
|
||||
const result = expandQuerySimple('xyz123unique');
|
||||
|
||||
expect(result.original).toBe('xyz123unique');
|
||||
expect(result.variations).toEqual([]);
|
||||
expect(result.weights).toEqual([2.0]);
|
||||
});
|
||||
|
||||
it('should give original query weight of 2.0', () => {
|
||||
const result = expandQuerySimple('auth');
|
||||
|
||||
expect(result.weights[0]).toBe(2.0);
|
||||
for (let i = 1; i < result.weights.length; i++) {
|
||||
expect(result.weights[i]).toBe(1.0);
|
||||
}
|
||||
});
|
||||
|
||||
it('should limit variations to 3', () => {
|
||||
const result = expandQuerySimple('auth');
|
||||
expect(result.variations.length).toBeLessThanOrEqual(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('expand (fallback without LLM)', () => {
|
||||
it('should return expanded query without LLM initialization', async () => {
|
||||
const result = await expander.expand('auth');
|
||||
|
||||
expect(result.original).toBe('auth');
|
||||
expect(result.variations.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should cache results', async () => {
|
||||
const result1 = await expander.expand('auth');
|
||||
const result2 = await expander.expand('auth');
|
||||
|
||||
expect(result1).toEqual(result2);
|
||||
});
|
||||
|
||||
it('should handle case-insensitive caching', async () => {
|
||||
const result1 = await expander.expand('Auth');
|
||||
const result2 = await expander.expand('AUTH');
|
||||
|
||||
expect(result1.original).toBe('Auth');
|
||||
expect(result2.original).toBe('AUTH');
|
||||
});
|
||||
});
|
||||
|
||||
describe('clearCache', () => {
|
||||
it('should clear the expansion cache', async () => {
|
||||
await expander.expand('auth');
|
||||
expander.clearCache();
|
||||
|
||||
const result = await expander.expand('auth');
|
||||
expect(result).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('isInitialized', () => {
|
||||
it('should return false when not initialized with LLM', () => {
|
||||
expect(expander.isInitialized()).toBe(false);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,244 @@
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
import type { SkillSummary, SkillIndex } from '../../recommend/types.js';
|
||||
|
||||
const mockSkills: SkillSummary[] = [
|
||||
{
|
||||
name: 'react-auth',
|
||||
description: 'Authentication utilities for React applications',
|
||||
tags: ['react', 'auth', 'authentication'],
|
||||
compatibility: {
|
||||
frameworks: ['react'],
|
||||
languages: ['typescript', 'javascript'],
|
||||
libraries: ['next-auth'],
|
||||
},
|
||||
popularity: 500,
|
||||
quality: 80,
|
||||
verified: true,
|
||||
},
|
||||
{
|
||||
name: 'vue-forms',
|
||||
description: 'Form validation library for Vue',
|
||||
tags: ['vue', 'forms', 'validation'],
|
||||
compatibility: {
|
||||
frameworks: ['vue'],
|
||||
languages: ['typescript', 'javascript'],
|
||||
libraries: [],
|
||||
},
|
||||
popularity: 300,
|
||||
quality: 75,
|
||||
verified: false,
|
||||
},
|
||||
{
|
||||
name: 'api-testing',
|
||||
description: 'API testing utilities for REST endpoints',
|
||||
tags: ['testing', 'api', 'rest'],
|
||||
compatibility: {
|
||||
frameworks: [],
|
||||
languages: ['typescript'],
|
||||
libraries: ['jest', 'supertest'],
|
||||
},
|
||||
popularity: 400,
|
||||
quality: 85,
|
||||
verified: true,
|
||||
},
|
||||
{
|
||||
name: 'login-helper',
|
||||
description: 'Helper functions for login and authentication flows',
|
||||
tags: ['auth', 'login', 'oauth'],
|
||||
compatibility: {
|
||||
frameworks: ['react', 'vue'],
|
||||
languages: ['typescript'],
|
||||
libraries: [],
|
||||
},
|
||||
popularity: 200,
|
||||
quality: 70,
|
||||
verified: false,
|
||||
},
|
||||
];
|
||||
|
||||
const mockIndex: SkillIndex = {
|
||||
version: 1,
|
||||
lastUpdated: new Date().toISOString(),
|
||||
skills: mockSkills,
|
||||
sources: [],
|
||||
};
|
||||
|
||||
vi.mock('better-sqlite3', () => {
|
||||
return {
|
||||
default: vi.fn().mockImplementation(() => {
|
||||
throw new Error("Cannot find module 'better-sqlite3'");
|
||||
}),
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock('sqlite-vec', () => {
|
||||
return {
|
||||
load: vi.fn(),
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock('node-llama-cpp', () => {
|
||||
return {
|
||||
getLlama: vi.fn().mockImplementation(() => {
|
||||
throw new Error("Cannot find package 'node-llama-cpp'");
|
||||
}),
|
||||
};
|
||||
});
|
||||
|
||||
describe('HybridSearchPipeline', () => {
|
||||
let HybridSearchPipeline: typeof import('../hybrid.js').HybridSearchPipeline;
|
||||
let createHybridSearchPipeline: typeof import('../hybrid.js').createHybridSearchPipeline;
|
||||
let pipeline: InstanceType<typeof HybridSearchPipeline>;
|
||||
|
||||
beforeEach(async () => {
|
||||
const module = await import('../hybrid.js');
|
||||
HybridSearchPipeline = module.HybridSearchPipeline;
|
||||
createHybridSearchPipeline = module.createHybridSearchPipeline;
|
||||
pipeline = createHybridSearchPipeline();
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
if (pipeline) {
|
||||
await pipeline.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
describe('initialization', () => {
|
||||
it('should create a pipeline', () => {
|
||||
expect(pipeline).toBeInstanceOf(HybridSearchPipeline);
|
||||
});
|
||||
|
||||
it('should not be initialized before calling initialize()', () => {
|
||||
expect(pipeline.isInitialized()).toBe(false);
|
||||
});
|
||||
|
||||
it('should be initialized after calling initialize()', async () => {
|
||||
await pipeline.initialize();
|
||||
expect(pipeline.isInitialized()).toBe(true);
|
||||
});
|
||||
|
||||
it('should load skills index', async () => {
|
||||
pipeline.loadSkillsIndex(mockIndex);
|
||||
const stats = pipeline.getStats();
|
||||
expect(stats.skillCount).toBe(mockSkills.length);
|
||||
});
|
||||
});
|
||||
|
||||
describe('search (keyword-only fallback)', () => {
|
||||
beforeEach(async () => {
|
||||
pipeline.loadSkillsIndex(mockIndex);
|
||||
await pipeline.initialize();
|
||||
});
|
||||
|
||||
it('should find skills matching query', async () => {
|
||||
const response = await pipeline.search({ query: 'authentication' });
|
||||
|
||||
expect(response.results.length).toBeGreaterThan(0);
|
||||
expect(response.results.some((r) => r.skill.name === 'react-auth')).toBe(true);
|
||||
});
|
||||
|
||||
it('should find skills by tag', async () => {
|
||||
const response = await pipeline.search({ query: 'react' });
|
||||
|
||||
expect(response.results.length).toBeGreaterThan(0);
|
||||
expect(response.results.some((r) => r.skill.tags?.includes('react'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should respect limit parameter', async () => {
|
||||
const response = await pipeline.search({ query: 'auth', limit: 2 });
|
||||
|
||||
expect(response.results.length).toBeLessThanOrEqual(2);
|
||||
});
|
||||
|
||||
it('should include timing information', async () => {
|
||||
const response = await pipeline.search({ query: 'test' });
|
||||
|
||||
expect(typeof response.timing.totalMs).toBe('number');
|
||||
expect(response.timing.totalMs).toBeGreaterThanOrEqual(0);
|
||||
expect(response.timing.keywordSearchMs).toBeGreaterThanOrEqual(0);
|
||||
});
|
||||
|
||||
it('should include stats', async () => {
|
||||
const response = await pipeline.search({ query: 'auth' });
|
||||
|
||||
expect(response.stats.candidatesFromKeyword).toBeGreaterThan(0);
|
||||
expect(response.stats.totalMerged).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should return original query in response', async () => {
|
||||
const response = await pipeline.search({ query: 'authentication' });
|
||||
|
||||
expect(response.query.original).toBe('authentication');
|
||||
});
|
||||
});
|
||||
|
||||
describe('search with expansion', () => {
|
||||
beforeEach(async () => {
|
||||
pipeline.loadSkillsIndex(mockIndex);
|
||||
await pipeline.initialize();
|
||||
});
|
||||
|
||||
it('should expand query and find more results', async () => {
|
||||
const response = await pipeline.search({
|
||||
query: 'auth',
|
||||
enableExpansion: true,
|
||||
});
|
||||
|
||||
expect(response.results.length).toBeGreaterThan(0);
|
||||
expect(response.query.expanded).toBeDefined();
|
||||
});
|
||||
|
||||
it('should include expanded terms in response', async () => {
|
||||
const response = await pipeline.search({
|
||||
query: 'auth',
|
||||
enableExpansion: true,
|
||||
});
|
||||
|
||||
if (response.query.expanded) {
|
||||
expect(response.query.expanded.original).toBe('auth');
|
||||
expect(response.query.expanded.weights[0]).toBe(2.0);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('getStats', () => {
|
||||
it('should return stats before initialization', () => {
|
||||
const stats = pipeline.getStats();
|
||||
expect(stats.initialized).toBe(false);
|
||||
expect(stats.skillCount).toBe(0);
|
||||
});
|
||||
|
||||
it('should return updated stats after loading index', async () => {
|
||||
pipeline.loadSkillsIndex(mockIndex);
|
||||
await pipeline.initialize();
|
||||
|
||||
const stats = pipeline.getStats();
|
||||
expect(stats.initialized).toBe(true);
|
||||
expect(stats.skillCount).toBe(mockSkills.length);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('hybridSearch helper', () => {
|
||||
let hybridSearch: typeof import('../hybrid.js').hybridSearch;
|
||||
|
||||
beforeEach(async () => {
|
||||
const module = await import('../hybrid.js');
|
||||
hybridSearch = module.hybridSearch;
|
||||
});
|
||||
|
||||
it('should perform search on skills array', async () => {
|
||||
const response = await hybridSearch(mockSkills, 'react');
|
||||
|
||||
expect(response.results.length).toBeGreaterThan(0);
|
||||
expect(response.query.original).toBe('react');
|
||||
});
|
||||
|
||||
it('should respect options', async () => {
|
||||
const response = await hybridSearch(mockSkills, 'auth', {
|
||||
limit: 1,
|
||||
});
|
||||
|
||||
expect(response.results.length).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,276 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
computeRRFScore,
|
||||
fuseWithRRF,
|
||||
normalizeScores,
|
||||
weightedCombine,
|
||||
applyPositionAwareBlending,
|
||||
getRankFromScore,
|
||||
mergeRankings,
|
||||
type RankerResult,
|
||||
type RRFInput,
|
||||
} from '../rrf.js';
|
||||
|
||||
describe('RRF (Reciprocal Rank Fusion)', () => {
|
||||
describe('computeRRFScore', () => {
|
||||
it('should compute RRF score for a single rank', () => {
|
||||
const score = computeRRFScore([1], 60);
|
||||
expect(score).toBeCloseTo(1 / 61, 5);
|
||||
});
|
||||
|
||||
it('should sum RRF scores for multiple ranks', () => {
|
||||
const score = computeRRFScore([1, 2, 3], 60);
|
||||
const expected = 1 / 61 + 1 / 62 + 1 / 63;
|
||||
expect(score).toBeCloseTo(expected, 5);
|
||||
});
|
||||
|
||||
it('should use custom k value', () => {
|
||||
const scoreK60 = computeRRFScore([1], 60);
|
||||
const scoreK30 = computeRRFScore([1], 30);
|
||||
expect(scoreK30).toBeGreaterThan(scoreK60);
|
||||
});
|
||||
|
||||
it('should return 0 for empty ranks', () => {
|
||||
const score = computeRRFScore([]);
|
||||
expect(score).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('fuseWithRRF', () => {
|
||||
it('should fuse results from multiple rankers', () => {
|
||||
const inputs: RRFInput[] = [
|
||||
{
|
||||
source: 'vector',
|
||||
results: [
|
||||
{ skillName: 'skill-a', score: 0.9 },
|
||||
{ skillName: 'skill-b', score: 0.8 },
|
||||
{ skillName: 'skill-c', score: 0.7 },
|
||||
],
|
||||
},
|
||||
{
|
||||
source: 'keyword',
|
||||
results: [
|
||||
{ skillName: 'skill-b', score: 90 },
|
||||
{ skillName: 'skill-a', score: 80 },
|
||||
{ skillName: 'skill-d', score: 70 },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
const rankings = fuseWithRRF(inputs, 60);
|
||||
|
||||
expect(rankings.length).toBe(4);
|
||||
expect(rankings[0].skillName).toBe('skill-a');
|
||||
expect(rankings[1].skillName).toBe('skill-b');
|
||||
});
|
||||
|
||||
it('should include rank information from each source', () => {
|
||||
const inputs: RRFInput[] = [
|
||||
{
|
||||
source: 'vector',
|
||||
results: [{ skillName: 'skill-a', score: 0.9 }],
|
||||
},
|
||||
{
|
||||
source: 'keyword',
|
||||
results: [{ skillName: 'skill-a', score: 90 }],
|
||||
},
|
||||
];
|
||||
|
||||
const rankings = fuseWithRRF(inputs);
|
||||
|
||||
expect(rankings[0].ranks).toHaveLength(2);
|
||||
expect(rankings[0].ranks.map((r) => r.source)).toContain('vector');
|
||||
expect(rankings[0].ranks.map((r) => r.source)).toContain('keyword');
|
||||
});
|
||||
|
||||
it('should handle skills appearing in only one ranker', () => {
|
||||
const inputs: RRFInput[] = [
|
||||
{
|
||||
source: 'vector',
|
||||
results: [{ skillName: 'skill-a', score: 0.9 }],
|
||||
},
|
||||
{
|
||||
source: 'keyword',
|
||||
results: [{ skillName: 'skill-b', score: 90 }],
|
||||
},
|
||||
];
|
||||
|
||||
const rankings = fuseWithRRF(inputs);
|
||||
|
||||
expect(rankings).toHaveLength(2);
|
||||
const skillAInfo = rankings.find((r) => r.skillName === 'skill-a');
|
||||
const skillBInfo = rankings.find((r) => r.skillName === 'skill-b');
|
||||
expect(skillAInfo?.ranks).toHaveLength(1);
|
||||
expect(skillBInfo?.ranks).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('normalizeScores', () => {
|
||||
it('should normalize scores to 0-1 range', () => {
|
||||
const results: RankerResult[] = [
|
||||
{ skillName: 'a', score: 100 },
|
||||
{ skillName: 'b', score: 50 },
|
||||
{ skillName: 'c', score: 0 },
|
||||
];
|
||||
|
||||
const normalized = normalizeScores(results);
|
||||
|
||||
expect(normalized[0].score).toBe(1);
|
||||
expect(normalized[1].score).toBe(0.5);
|
||||
expect(normalized[2].score).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle all same scores', () => {
|
||||
const results: RankerResult[] = [
|
||||
{ skillName: 'a', score: 50 },
|
||||
{ skillName: 'b', score: 50 },
|
||||
];
|
||||
|
||||
const normalized = normalizeScores(results);
|
||||
|
||||
expect(normalized[0].score).toBe(1);
|
||||
expect(normalized[1].score).toBe(1);
|
||||
});
|
||||
|
||||
it('should return empty array for empty input', () => {
|
||||
const normalized = normalizeScores([]);
|
||||
expect(normalized).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('weightedCombine', () => {
|
||||
it('should combine results with weights', () => {
|
||||
const inputs: RRFInput[] = [
|
||||
{
|
||||
source: 'vector',
|
||||
results: [
|
||||
{ skillName: 'a', score: 100 },
|
||||
{ skillName: 'b', score: 50 },
|
||||
],
|
||||
},
|
||||
{
|
||||
source: 'keyword',
|
||||
results: [
|
||||
{ skillName: 'b', score: 100 },
|
||||
{ skillName: 'a', score: 50 },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
const combined = weightedCombine(inputs, { vector: 0.6, keyword: 0.4 });
|
||||
|
||||
expect(combined).toHaveLength(2);
|
||||
const skillA = combined.find((r) => r.skillName === 'a')!;
|
||||
const skillB = combined.find((r) => r.skillName === 'b')!;
|
||||
expect(skillA.score).toBeCloseTo(0.6 * 1 + 0.4 * 0, 5);
|
||||
expect(skillB.score).toBeCloseTo(0.6 * 0 + 0.4 * 1, 5);
|
||||
});
|
||||
|
||||
it('should default to weight 1 for unknown sources', () => {
|
||||
const inputs: RRFInput[] = [
|
||||
{
|
||||
source: 'unknown',
|
||||
results: [{ skillName: 'a', score: 100 }],
|
||||
},
|
||||
];
|
||||
|
||||
const combined = weightedCombine(inputs, {});
|
||||
|
||||
expect(combined[0].score).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('applyPositionAwareBlending', () => {
|
||||
it('should apply different weights based on position', () => {
|
||||
const retrievalScores = new Map([
|
||||
['a', 0.9],
|
||||
['b', 0.8],
|
||||
['c', 0.7],
|
||||
['d', 0.6],
|
||||
]);
|
||||
|
||||
const rerankerScores = new Map([
|
||||
['a', 0.5],
|
||||
['b', 0.6],
|
||||
['c', 0.7],
|
||||
['d', 0.8],
|
||||
]);
|
||||
|
||||
const sortedSkills = ['a', 'b', 'c', 'd'];
|
||||
|
||||
const blended = applyPositionAwareBlending(
|
||||
retrievalScores,
|
||||
rerankerScores,
|
||||
sortedSkills
|
||||
);
|
||||
|
||||
const scoreA = blended.get('a')!;
|
||||
expect(scoreA).toBeCloseTo(0.9 * 0.75 + 0.5 * 0.25, 5);
|
||||
|
||||
const scoreD = blended.get('d')!;
|
||||
expect(scoreD).toBeCloseTo(0.6 * 0.6 + 0.8 * 0.4, 5);
|
||||
});
|
||||
|
||||
it('should handle missing scores', () => {
|
||||
const retrievalScores = new Map([['a', 0.9]]);
|
||||
const rerankerScores = new Map<string, number>();
|
||||
const sortedSkills = ['a'];
|
||||
|
||||
const blended = applyPositionAwareBlending(
|
||||
retrievalScores,
|
||||
rerankerScores,
|
||||
sortedSkills
|
||||
);
|
||||
|
||||
expect(blended.get('a')).toBeCloseTo(0.9 * 0.75, 5);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getRankFromScore', () => {
|
||||
it('should return correct rank for a skill', () => {
|
||||
const results: RankerResult[] = [
|
||||
{ skillName: 'a', score: 90 },
|
||||
{ skillName: 'b', score: 80 },
|
||||
{ skillName: 'c', score: 70 },
|
||||
];
|
||||
|
||||
expect(getRankFromScore('a', results)).toBe(1);
|
||||
expect(getRankFromScore('b', results)).toBe(2);
|
||||
expect(getRankFromScore('c', results)).toBe(3);
|
||||
});
|
||||
|
||||
it('should return length+1 for missing skill', () => {
|
||||
const results: RankerResult[] = [
|
||||
{ skillName: 'a', score: 90 },
|
||||
{ skillName: 'b', score: 80 },
|
||||
];
|
||||
|
||||
expect(getRankFromScore('missing', results)).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('mergeRankings', () => {
|
||||
it('should merge primary and secondary rankings with weights', () => {
|
||||
const primary = [
|
||||
{ skillName: 'a', rrfScore: 0.1, ranks: [{ source: 'primary', rank: 1 }] },
|
||||
{ skillName: 'b', rrfScore: 0.05, ranks: [{ source: 'primary', rank: 2 }] },
|
||||
];
|
||||
|
||||
const secondary = [
|
||||
{ skillName: 'b', rrfScore: 0.1, ranks: [{ source: 'secondary', rank: 1 }] },
|
||||
{ skillName: 'c', rrfScore: 0.05, ranks: [{ source: 'secondary', rank: 2 }] },
|
||||
];
|
||||
|
||||
const merged = mergeRankings(primary, secondary, 0.7);
|
||||
|
||||
expect(merged).toHaveLength(3);
|
||||
const skillA = merged.find((r) => r.skillName === 'a')!;
|
||||
const skillB = merged.find((r) => r.skillName === 'b')!;
|
||||
const skillC = merged.find((r) => r.skillName === 'c')!;
|
||||
|
||||
expect(skillA.rrfScore).toBeCloseTo(0.1 * 0.7, 5);
|
||||
expect(skillB.rrfScore).toBeCloseTo(0.05 * 0.7 + 0.1 * 0.3, 5);
|
||||
expect(skillC.rrfScore).toBeCloseTo(0.05 * 0.3, 5);
|
||||
});
|
||||
});
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user