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.

1. skill init detects 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 existing AGENTS.md / CLAUDE.md.
2. setup finds 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-agnostic superskill skill at ~/.agents/skills/superskill/SKILL.md so hosts with skill discovery list it. Use --dry-run to preview, --clients claude-code,cursor to target, --force to overwrite.
3. 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 impact and claims, with every edge tagged EXTRACTED or INFERRED. Code graph
• Obsidian-native memory — graph viz writes 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 quarantine by default, never deletes. 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 test                  # vitest
npm run build             # tsc
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.

License

Apache-2.0 — LICENSE · NOTICE

Copyright 2026 Permanu (Atharva Pandey)