SuperSkill
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. ·
Documentation
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)
