SuperSkill MCP server
Commit Nov 10, 2026An orchestrator for coding agents that provides deterministic rule planning, a project-jailed knowledge graph, and curated skill packs.
Also known as permanu/superskill
- Stars
- 19
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is SuperSkill MCP?
SuperSkill is an orchestrator for coding agents that provides deterministic rule planning, a project-jailed knowledge graph, and curated skill packs.
Summary generated from the project's README
About SuperSkill MCP server
SuperSkill acts as a local-first orchestrator for coding agents, providing a structured environment for deterministic rule planning and project-specific knowledge. Instead of relying on massive, generic skill databases, it uses curated packs tailored to specific languages or phases like TDD, SRE, or security. The system maintains a project-jailed vault where markdown files serve as the source of truth, indexed via a local SQLite FTS5 search engine to ensure agents have context without being overwhelmed by data dumps.
Developers use this tool by installing it via npm and running the setup command to register the MCP server with supported clients like Claude Code or Cursor. It operates through a single binary that functions as both a command-line interface and an MCP server. The architecture emphasizes security through vault isolation, secret scanning, and prompt-injection protection. It requires Node 22.16+ or Node 24+ to ensure the necessary SQLite features are available for knowledge graph searches.
What you can do with it
- 1Automated code reviewsAn AI client can perform an 18-axis review of a specific scope or the entire project using the review shortcut.
- 2Session monitoring and fixingA developer can use the watchdog tool to review session traces and receive severity-ranked findings with proposed fixes.
Written from the project's README. Every use case is checked against a quote from it.
How to install SuperSkill MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SuperSkill MCP in Claude Code
$ claude mcp add superskill -- npx -y superskillInstall SuperSkill MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"superskill": {
"command": "npx",
"args": [
"-y",
"superskill"
]
}
}
}Install SuperSkill MCP in VS Code
.vscode/mcp.json
{
"servers": {
"superskill": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"superskill"
]
}
}
}Install SuperSkill MCP in VS Code CLI
$ code --add-mcp '{"name":"superskill","type":"stdio","command":"npx","args":["-y","superskill"]}'Install SuperSkill MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"superskill": {
"command": "npx",
"args": [
"-y",
"superskill"
]
}
}
}Install SuperSkill MCP in Codex
$ codex mcp add superskill -- npx -y superskillInstall SuperSkill MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.superskill] command = "npx" args = ["-y", "superskill"]
Install SuperSkill MCP in Gemini CLI
$ gemini mcp add -s user superskill npx -- -y superskillInstall SuperSkill MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"superskill": {
"command": "npx",
"args": [
"-y",
"superskill"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepermanu/superskill is public and reachablegithub.com/permanu/superskill ↗Pass
- Package names this repository as its sourcesuperskill names permanu/superskill as sourcenpmjs.com/package/superskill ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/permanu/superskill ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from superskillPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSuperSkill
One-entry orchestrator for coding agents: deterministic rule planning, evidence gates, a project-jailed vault, a local knowledge graph, and safe cache sharing across agent worktrees. Curated packs — not a dump of 90k remote skills.
Prompt normally. Call superskill with the task. It diagnoses, then loads a combination — Go → Go pack, QA → QA, security bug → review + security — and returns a system brief plus a deterministic rule plan. Defaults: careful-minimal, algorithm-correct, systems thinking. Open design branches grill the human (HITL). Factory packs (plan, TDD, verify, SRE, grill, design/UI) are ours — UI work lazily pulls the design pack without being asked.
Everything is local-first: the vault is markdown under projects/<slug>/, the search index is derived SQLite, and vault IO is jailed to the current project.
Requires Node 22.16+ on the 22.x line, or Node 24+, with SQLite FTS5 enabled. Official Node 22.13–22.15 builds lack FTS5 and cannot run knowledge search.
The documentation guides are the manual; this README is the hub.
Why
Marketplace skill dumps fill the window with advice that does not know this system. Review and security need:
- Vertical — this project's ADRs, learnings, sessions
- Horizontal — callers, sibling paths, co-activations
- Fresh — session complete +
learn
SuperSkill injects a system brief from the project graph, jails vault IO to projects/<this-slug>/, and keeps .superskill/ gitignored so each developer's trajectory stays private.
Quick start
npm install -g superskill # Node 22.16+ (22.x), or 24+
# in your repo
superskill skill init # detect stack, index the in-repo catalog, build .superskill/graph.json
superskill setup # register MCP + instructions in supported detected clients
One binary, two faces: superskill <command> runs everything you run yourself (setup, doctor, skill, graph, worktree, …), and bare superskill in a terminal shows the help. With no arguments over piped stdio — how AI clients launch it — the same binary starts the MCP server. superskill-cli remains a permanent alias, and SUPERSKILL_FORCE_MCP=1 forces server mode.
skill initdetects the stack, indexes the in-repo catalog (not skills.sh), writes.superskill/graph.json(project-local, gitignored), registers the repo in the vault map (project-map.json) so vault commands auto-detect without-p, appends.superskill/to.gitignore, and adds a short SuperSkill block to an existingAGENTS.md/CLAUDE.md.setupfinds installed clients and writes the MCP entry, instruction file, and slash commands (/review,/worktree,/watchdog,/superskill) for each host that supports them — plus the harness-agnosticsuperskillskill at~/.agents/skills/superskill/SKILL.mdso hosts with skill discovery list it. Use--dry-runto preview,--clients claude-code,cursorto target,--forceto overwrite.- Describe the task — or use a shortcut:
/review [scope](18-axis review; empty scope = whole project),/worktree [status|audit|gc],/watchdog [dig|fix],/superskill <task>. The router picks packs by language, phase, and specialists; content is budgeted, and review/audit/diff/defect tasks (and security bugs) also get the vault brief plus a caller protocol.
Verify any time with superskill doctor: install vs running MCP servers, vault + project mapping, project graph isolation (fails if .superskill/ is tracked), catalog validation, compile toolchains, telemetry, and MCP clients.
Full install, MCP client snippets, upgrade, and uninstall: Getting started. Setup support is defined in the harness matrix.
What it does
- Deterministic skill routing — a task becomes packs plus a budgeted rule plan with an audit trail (
selected,explain,dropped,budget); no catalog dumps. Concepts - Evidence gates — spec → tickets → evidence →
gate check, deterministic and non-zero on failure. Workflows - Project-jailed vault and knowledge graph — markdown under
projects/<slug>/is the source of truth; SQLite FTS5 + edges is derived; agents traverse lazily instead of loading dumps. Knowledge graph - Code graph — tree-sitter WASM
impactandclaims, with every edge tagged EXTRACTED or INFERRED. Code graph - Obsidian-native memory —
graph vizwrites Mermaid architecture notes, code notes, a project dashboard, and Bases views. Obsidian - Worktree cache sharing — share safe caches (package stores, compiler caches), isolate build state, seed fresh worktrees copy-on-write; reports and recoverable quarantine by default, with explicit purge controls. Worktrees
- Space hygiene — a read-only report of what is worth reclaiming and the exact command to reclaim it. Hygiene
- Watchdog — session-trace review pinned against the repo, returning severity-ranked findings with evidence and proposals. Watchdog
- Local-first and safe — vault jail, secret scanner, fail-closed skill audits, prompt-injection scan, MCP write rate limits, opt-in local telemetry. Security
- Two faces, one binary — every command runs as
superskill <command>; clients launch the same binary as the MCP server. Commands · MCP tools
Documentation
| Guide | What it covers |
|---|---|
| Getting started | Install, first run, MCP configuration per client, upgrade, uninstall |
| Concepts | Constitution, the plan, flows, gates, code graph, vault, project isolation, packs |
| CLI reference | Every command and flag: vault, project memory, knowledge graph, skills, gates, code graph, setup, telemetry, hygiene, watchdog |
| MCP tools | The MCP tool surface and its parameters |
| Workflows | Gates walkthrough (spec → tickets → evidence → gate) and rule planning |
| Knowledge graph | Vault FTS + edges, lazy traversal, code-graph impact/claims, confidence model |
| Obsidian | Viewing your memory: graph viz, the project dashboard, Bases views, graph scoping |
| Worktrees | Worktree cache sharing: usage, safety, CLI reference, troubleshooting |
| Space hygiene | Read-only space report across caches, worktrees, docker, xcode, scratch |
| Watchdog | Session review and environment optimization |
| Configuration | Environment variables and harness hooks |
| Security | Vault jail, secret scanner, audit gate, prompt-injection scan, rate limits |
| Harness integration | Client setup matrix, support contracts, hooks, CI |
| Diagram conventions | Rules for the generated architecture diagrams (HLD/LLD/DFD/ERD) |
Everything is also indexed from the docs home.
Contributing
git clone https://github.com/permanu/superskill.git
cd superskill
npm install
npm run lint # tsc --noEmit
npm run build # explicit tsc + vendored parser build
npm test # rebuild, then Vitest including built CLI/MCP tests
npm run test:coverage # rebuild, test, enforce coverage thresholds
npm run validate:rules # node dist/rules/cli.js validate
Rule authoring follows docs/authoring/CONTRACT.md: one falsifiable decision per file, primary sources required, compilable Bad/Good snippets, and status: verified only after independent verification. See CONTRIBUTING.md for the PR workflow.
For native SKILL.md files, use the template and the skill validate profile. Structural validation and unit fixtures establish only the deterministic cases they exercise; even a green result does not establish model effectiveness or compatibility with every harness. Model behavior remains unproven until separate evaluations complete; fixtures or runner scaffolding alone are not a paid-model result. Only report behavior for the exact tested model/harness matrix. See Anthropic's skill-authoring best practices.
License
Copyright 2026 Permanu (Atharva Pandey)
SuperSkill MCP questions
How do I add SuperSkill MCP to Claude Code?
Run claude mcp add superskill -- npx -y superskill in your terminal. Add --scope user to make it available in every project.
How do I add SuperSkill MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What is the primary function of SuperSkill?
It acts as a one-entry orchestrator for coding agents, providing deterministic rule planning, evidence gates, a project-jailed vault, and a local knowledge graph.
How is the project data stored and secured?
Data is stored in a local-first markdown vault under projects/<slug>/ and the search index is derived from SQLite FTS5, with vault IO jailed to the current project.
What are the Node.js version requirements?
You need Node 22.16+ on the 22.x line, or Node 24+, with SQLite FTS5 enabled.