SuperSkill

Name: SuperSkill
Author: Permanu

Local project memory, rule-pack routing and worktree cache tools for coding agents

By Permanu TypeScript Local · stdio Knowledge and memory Developer tools

GitHub npm Website

40 popularity score ★ 19 ↓ 311/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add superskill -- npx -y --prefer-online superskill@latest

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "superskill": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "superskill@latest"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "superskill": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "superskill@latest"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "superskill": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "superskill@latest"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.superskill]
command = "npx"
args = ["-y", "--prefer-online", "superskill@latest"]

Gemini CLITerminal

gemini mcp add --scope user superskill npx -- -y --prefer-online superskill@latest

Settings 7

`VAULT_PATH`	Optional: Folder of the markdown vault; must be under your home directory. Default ~/Vaults/ai.
`MAX_INJECT_TOKENS`	Optional: Token cap for injected context, default 1500, clamped 100-50000.
`SESSION_TTL_HOURS`	Optional: Hours before an agent session without heartbeat expires, default 2.
`SUPERSKILL_MAX_RESPONSE_BYTES`	Optional: Byte budget per MCP response, default 65536, max 10 MiB.
`SUPERSKILL_TELEMETRY`	Optional: 1 opts in to local-only telemetry, 0 turns recording off.
`SUPERSKILL_CACHE_ROOT`	Optional: Root folder for shared worktree caches; defaults to the platform cache folder.
`SUPERSKILL_FORCE_MCP`	Optional: Set to 1 to force server mode instead of the CLI.

What it does

SuperSkill is a local stdio MCP server, plus a CLI from the same npm package, that sits between a coding agent and the project it works on. Its main tool, `superskill`, takes a task description, picks curated rule packs by language, phase and specialty (for example Go, QA, security review), and returns a short brief and a rule plan cut to a token budget, with a record of what was picked and what was left out.

Around that it keeps a per-project memory: a markdown vault under `projects/<slug>/` (by default in `~/Vaults/ai`) holding decisions, tasks, learnings, sessions and notes, with an SQLite FTS5 index and link graph built from it. Notes can be opened in Obsidian, and `knowledge_viz` writes Mermaid architecture and code notes into the vault. Further tools cover spec, ticket and evidence gates, a tree-sitter code graph (`impact`, `claims`), sharing package and compiler caches across git worktrees, a read-only disk-space report, and a watchdog that reviews past agent sessions.

In version 0.15.1 the server registers 52 tools; the docs' tool table lists 51 and leaves out `skill_validate` (src/core/registry.ts). Calls are rate-limited per server in a 60-second window: 30 write calls, 60 reads and 10 expensive diagnostics, after which it returns `RATE_LIMITED` (src/mcp-server.ts).

What it needs

Runtime	Node.js 22+

Node.js 22.16 or later on the 22.x line, or Node 24+, built with SQLite FTS5; official Node 22.13 to 22.15 builds lack FTS5 and cannot run knowledge search. npx for the launch command. The vault folder (`VAULT_PATH`) must sit under your home directory. Running `superskill skill init` inside a repository is the docs' first step and makes vault tools find the project without naming it.

Limits

Vault access is confined to the current project's folder; cross-project search is refused, and a workspace that has not been registered cannot use implicit project memory. Responses over 64 KiB by default (`SUPERSKILL_MAX_RESPONSE_BYTES`, up to 10 MiB) come back as a truncated JSON preview. Context injection is capped at 1500 tokens by default (`MAX_INJECT_TOKENS`, 100 to 50000). The docs' launcher uses `superskill@latest` with `--prefer-online`, so each start fetches the newest release and may fail to start offline. The makers say the secret and prompt-injection scans are heuristics and that rule-pack effect on model output is unproven.

Who it suits

Suits a developer who runs coding agents (Claude Code, Cursor, OpenCode, Codex CLI) on their own machine and wants project decisions, tasks and session notes kept as local markdown, with rule packs chosen per task instead of a large skill catalogue. It also fits teams juggling many git worktrees who want shared caches and cleanup reports. It is a large tool surface (52 tools) that writes to your home directory and client configs, so someone who only wants a simple notes or memory store, or cannot run Node 22.16+, should pick something smaller.

Tools 52

superskill: Picks rule packs for a task and returns a brief plus a budgeted rule plan
read: Reads a vault file or lists a vault folder
write: Writes, appends or prepends to a vault file; appends by default
search: Full-text search over this project's vault notes
project_context: Returns the project's context document, found from the working directory
generate_context: Scans a repository and returns a draft context.md without saving it
decide: Records an architecture decision note
task: Adds, lists and updates project tasks or shows the board
learn: Saves or lists learnings
brainstorm: Starts or continues a brainstorm note
session: Registers, heartbeats, completes or lists agent sessions
resume: Shows recent sessions, unfinished work and next steps
stats: Counts the project's vault content
prune: Archives or deletes stale vault content by retention rules, dry run first
deprecate: Marks a vault item deprecated with a reason
init: Sets up SuperSkill for the current project
status: Shows knowledge-graph state: skills, weights, recent sessions
telemetry: Shows, enables, disables, reports or clears local usage telemetry
register: Maps a repository to a vault project
doctor: Runs a health check over install, vault, graph, catalog and clients
skill_install: Installs skills from a GitHub repository
skill_validate: Checks a native skill file against a profile without changing it
skill_list_installed: Lists installed skills
skill_remove: Removes an installed skill
link: Adds a wikilink between two vault notes
extract: Splits a source document into separate vault notes
capture: Saves several insights as separate vault notes
template: Gives prefilled templates for vault note types
graph_related: Finds notes related to one note in this project
graph_traverse: Walks project metadata and opens content in byte pages
graph_cross_project: Project-scoped search; other projects are refused
knowledge_rebuild: Rebuilds the search and link index from the markdown
knowledge_viz: Writes Mermaid architecture notes and code notes
snapshot_repo_state: Saves branch, changed files and last commit into the vault
env_facts: Stores or looks up stable facts about the environment
cred_refs: Stores pointers to where credentials are documented
rollback: Keeps rollback checkpoints for commits
spec: Creates, approves, freezes and lists plan specs
tickets: Creates and tracks tickets from frozen specs
evidence: Records or reads evidence for a ticket
gate: Checks whether a spec or ticket has the evidence it needs
impact: Finds definitions, importers and callers of code from a code graph
claims: Checks structured claims about code against a code-graph scan
worktree_status: Reports git worktree health and shared cache size
worktree_audit: Gives a safety verdict and cache duplication per worktree
worktree_env: Works out the shared-cache environment for this worktree
worktree_activate: Writes the repo cache policy and installs a post-checkout git hook
worktree_apply: Applies audit items or restores quarantined files after confirmation
worktree_gc: Reports old caches; quarantines or purges them after confirmation
worktree_uninstall: Removes the hooks and adapters it installed
hygiene_report: Reports disk space worth reclaiming, without deleting anything
watchdog: Reviews agent session traces and can apply approved fixes

Popularity

40 popularity score, on our list (the bar is 36)

★ 19 ↓ 311/wk

GitHub stars	19	15.6 points
Stars in 30 days	+6	4.2 points
npm downloads, last week	311	20 points

Measured 2026-11-07. How the score works.

Where it is published

Code	permanu/superskill ★ 19
npm	superskill 0.17.0, 2026-11-04

What it can reach

Runs	On your machine
Reaches	Files on your machine, Your code, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	Apache-2.0 (npm)
Last code change	2026-11-04

Runs on your machine over stdio and needs no account or key. Tools write markdown into the vault (default ~/Vaults/ai, limited to the current project's folder, with path traversal and symlink escapes rejected) and log each vault write's path and size to ~/.superskill/audit/vault-writes.jsonl. `write` refuses content that looks like provider keys or tokens. Worktree tools can install a git post-checkout hook and quarantine or purge cache folders when called with confirm: true; `prune` can delete vault content. `skill_install` downloads skills from GitHub and contacts skills.sh. Its docs say that when a client starts the server it updates its own launcher entries and instruction blocks in that client's config files. Telemetry is off unless enabled and stays local.

Over time

GitHub stars 19 +6 (+46 %)

1913

13 Oct 20267 Nov 2026

npm downloads a week 311 +40 (+15 %)

1.4k7

30 Mar 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 40 +1 (+2 %)

4029

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![SuperSkill on EveryMCPServer](https://everymcpserver.com/badge/superskill.svg)](https://everymcpserver.com/servers/superskill)

Connect your client

Add in one click

Or add it by command or config

Settings 7

What it does

What it needs

Limits

Who it suits

Tools 52

Similar servers

SuperLocalMemory

Claude-Mem

basemind

projectmem

Entroly

MegaMemory