superskill

# SuperSkill

The runtime intelligence layer for AI agent skills.

[![npm](https://img.shields.io/npm/v/superskill)](https://www.npmjs.com/package/superskill)
[![license](https://img.shields.io/badge/license-AGPL--3.0-blue)](https://www.gnu.org/licenses/agpl-3.0)
[![skills](https://img.shields.io/badge/built--in_skills-87-purple)](https://github.com/permanu/superskill)
[![tools](https://img.shields.io/badge/AI%20tools-11-green)](https://github.com/permanu/superskill)

## The Problem

[skills.sh](https://skills.sh) solved skill discovery and installation — 90,000+ skills, 40+ agents, one standard. But installation is static. You browse, pick, install, and hope you chose right.

When you have 15 skills installed and say "write tests for my Go API" — which one loads? What about the three competing TDD skills? What if the model's context window can't fit them all?

**skills.sh is where you find skills. SuperSkill is what loads the right one at the right time.**

## How It Works

1. **Install skills however you want** — `npx skills add`, manual download, or use the 87 built-in skills
2. **Describe your task** — "write tests for my Go API"
3. **SuperSkill scores, resolves, and loads** — trigger-based matching picks the best skill, resolves collisions, respects your context budget

SuperSkill scans your installed skills (from `~/.cursor/skills/`, `~/.cursor/skills/`, etc.), merges them with its built-in catalog, and routes tasks to the best match at runtime.

## What SuperSkill Adds

| Layer | What it does | Why you need it |
|-------|-------------|----------------|
| **Router** | Task description → best matching skill | No manual browsing or memorizing skill names |
| **Arbiter** | 3 TDD skills installed? Profile picks the winner | Prevents collision chaos and token waste |
| **Scanner** | Discovers installed skills from any source | Works with skills.sh, manual installs, or built-in |
| **Memory** | Remembers activations within a session | No redundant fetches for simila