SuperSkill
Summary: SuperSkill is a local-first, project-jailed knowledge vault + coding-agent orchestrator exposing ~55 MCP tools for memory, planning/evidence gates, code-graph analysis, skill routing, worktree cache sharing, and hygiene/watchdog maintenance.
Vault memory —
read/write/searchmarkdown notes,capture/extract/decide/learn/brainstorm/link/deprecate,templatescaffolding,pruneretention,stats.Project context —
project_context,generate_context(scans a git repo into a draft),snapshot_repo_state,env_facts,cred_refs,rollbackcheckpoints.Sessions & coordination —
session(register/heartbeat/complete/list),resume, multi-agent workspace claiming.Knowledge graph —
graph_related,graph_traverse(lazy node/children/resolve/open),graph_cross_project(current project only),knowledge_rebuild,knowledge_viz,qa_viz.Deterministic skill routing —
superskillroutes a task to curated packs/rules by language, files and phase;skill_install/skill_list_installed/skill_removefor GitHub skills with audits.Spec → ticket → evidence gates —
spec(create/approve/freeze),tickets(topologicalready),evidence(jsonl log at HEAD),gate(fail-closed verification).Code graph —
impact(EXTRACTED/INFERRED callers and paths),claims(verify file/symbol/import claims as verified|refuted|unverifiable).Worktree cache sharing —
worktree_env,worktree_status,worktree_audit,worktree_activate,worktree_apply,worktree_gc(quarantine + undo),worktree_uninstall.Ops & hygiene —
hygiene_report(read-only space reclaim report),watchdog(session dig/fix/status),doctor(health check).Setup & observability —
init,register(repo→slug map),status, opt-in localtelemetry.Safety posture — vault IO jailed to
projects/<slug>/,.superskill/gitignored, read-only/destructive hints on every tool, dry-run-first and reversible destructive ops.
Allows scanning a git repository to generate project context, snapshot repository state (branch, dirty files, last commit), and manage rollback checkpoints using commit hashes.
Integrates with Obsidian vaults by storing project knowledge as Markdown and generating a knowledge-graph.canvas file for visual exploration of the project graph.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SuperSkill score and load the best skill for testing my Go API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: skill-curator-mcp
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 clientsOne 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. ConceptsEvidence gates — spec → tickets → evidence →
gate check, deterministic and non-zero on failure. WorkflowsProject-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 graphCode graph — tree-sitter WASM
impactandclaims, with every edge tagged EXTRACTED or INFERRED. Code graphObsidian-native memory —
graph vizwrites Mermaid architecture notes, code notes, a project dashboard, and Bases views. ObsidianWorktree 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 |
Install, first run, MCP configuration per client, upgrade, uninstall | |
Constitution, the plan, flows, gates, code graph, vault, project isolation, packs | |
Every command and flag: vault, project memory, knowledge graph, skills, gates, code graph, setup, telemetry, hygiene, watchdog | |
The MCP tool surface and its parameters | |
Gates walkthrough (spec → tickets → evidence → gate) and rule planning | |
Vault FTS + edges, lazy traversal, code-graph impact/claims, confidence model | |
Viewing your memory: | |
Worktree cache sharing: usage, safety, CLI reference, troubleshooting | |
Read-only space report across caches, worktrees, docker, xcode, scratch | |
Session review and environment optimization | |
Environment variables and harness hooks | |
Vault jail, secret scanner, audit gate, prompt-injection scan, rate limits | |
Client setup matrix, support contracts, hooks, CI | |
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 validateRule 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)
Available Tools
52 toolsbrainstormCDestructive
Start or continue a brainstorm document for a project.
Inputs: topic (required), content (required), project, workspace_path.
captureBDestructive
Batch-capture multiple insights from a conversation into individual vault items. Each item gets its own file with auto-numbering. Supports any content type (learning, decision, adr, prd, research, etc.).
Inputs: items (required), project, workspace_path.
claimsARead-only
Verify structured claims against a deterministic code-graph scan of a root (default cwd). Kinds: file-exists {path}, symbol-exists {name,file?}, symbol-exported {name,file}, import-resolves {from,specifier}, no-other-importers {file}, no-other-callers {symbol,file?}. Returns verified|refuted|unverifiable with node ids and edge confidence; hard verdicts require EXTRACTED facts.
Inputs: claims (required), root, workspace_path.
cred_refsBDestructive
Store pointers to where credentials are documented (not the credentials themselves). E.g., 'Django admin creds are in tests/live/test_all_endpoints.py'.
Inputs: action (required), name, notes, project, +2 more.
decideCDestructive
Log an architectural/design decision to the project's decisions directory.
Inputs: title (required), decision (required), context, project, +3 more.
deprecateBDestructive
Mark a vault item (ADR, learning, etc.) as deprecated with an optional reason.
Inputs: path (required), reason, workspace_path.
doctorBRead-only
One-shot health check: install vs running MCP servers, vault + project mapping, project graph isolation (must stay gitignored/project-local), rules catalog, compile toolchains, telemetry, MCP clients.
Inputs: fast.
env_factsADestructive
Store and query stable environment facts for a project (e.g., auth backend, env file locations, local URLs, required env vars). Not for secrets — use cred_refs for that.
Inputs: action (required), key, value, context, +2 more.
evidenceBDestructive
Record and read ticket evidence. Actions: add, list. Evidence is appended to projects//evidence/.jsonl with command, exit code, truncated output, commit, and timestamp.
Inputs: action (required), ticket (required), ts, cwd, +7 more.
extractBDestructive
Extract decisions, learnings, or other items from a source document into individual vault files. Each extracted item gets its own file with a backlink to the source.
Inputs: items (required), source (required), project, workspace_path.
gateARead-only
Deterministic evidence gate. Checks a spec (fields complete, frozen, hash intact) or a ticket (acceptance present, spec frozen and unchanged, evidence recorded at HEAD, review evidence when required). Returns pass/fail with the missing items.
Inputs: target (required), cwd, head, project, +1 more.
generate_contextARead-only
Scan a git repo and generate a draft context.md. Returns the draft — does NOT write to vault. Human reviews before committing.
Inputs: project_path (required), slug.
graph_cross_projectBRead-only
Search the current project's vault only. Cross-project search is denied.
Inputs: query (required), limit, workspace_path.
graph_traverseARead-only
Traverse the project index without loading bodies. node|children return metadata; resolve finds relevant notes, skills, rules, files and symbols with size estimates; open retrieves one file or symbol span capped at 4096 UTF-8 bytes by default.
Inputs: action (required), id, full, task, +4 more.
hygiene_reportARead-only
Read-only machine-wide space hygiene report across mapped repos: build caches, git worktrees, docker, xcode, and agent scratch. Marks entries that are DUE for cleanup with reasons and exact remediation commands. Reports only — deletes nothing.
Inputs: due, sizes, categories, workspace_path.
impactARead-only
Deterministic code-graph impact for a file or symbol: EXTRACTED definitions, importers, INFERRED callers, and the shortest graph path to a second target. Read-only; no LLM.
Inputs: target (required), to, root, workspace_path.
initADestructive
Initialize superskill for the current project. Detects stack, indexes the in-repo catalog, builds the project-local knowledge graph, and registers the repo in the vault map for auto-detection. Does not scrape skills.sh.
Inputs: slug, bridge.
knowledge_rebuildA
Rebuild this project's SQLite FTS5 + edges index from markdown. Source of truth stays the files.
Inputs: project, workspace_path.
knowledge_vizC
Write architecture notes and code notes (Obsidian-native markdown) and rebuild the project index.
Inputs: project, workspace_path.
learnBDestructive
Capture and query learnings. Learnings persist discoveries across sessions. Stored as individual files in projects//learnings/.
Inputs: action (required), tag, tags, limit, +7 more.
linkADestructive
Create a forward link between two vault notes. Appends a [[wikilink]] to the source note, enabling graph_related to discover the connection.
Inputs: source (required), target (required), project, workspace_path.
project_contextBRead-only
Get the context document for a project. Auto-detects project from CWD if not specified.
Inputs: project, max_tokens, detail_level, workspace_path.
pruneADestructive
Archive or delete stale vault content based on retention policies. Use mode='dry-run' first to preview.
Inputs: all, mode, project, sessions_days, +2 more.
readARead-only
Read a file or directory listing from the AI knowledge vault.
Inputs: path (required), depth, max_bytes, workspace_path.
registerA
Map a repo to a vault project so vault-backed commands auto-detect the slug (writes the vault project-map.json locator; project knowledge stays jailed under projects//).
Inputs: path, slug.
resumeARead-only
Get resume context for continuing work — recent sessions, interrupted work, in-progress tasks, suggested next steps. Call this at session start to understand what happened before.
Inputs: limit, format, project, workspace_path.
rollbackBDestructive
Manage rollback checkpoints. Store commit hashes with purpose/scope so rollback is safer. Mark when follow-up work starts after a checkpoint.
Inputs: action (required), scope, project, purpose, +3 more.
searchBRead-only
Full-text search (SQLite FTS5 porter stemming) scoped to this project. Structured mode still matches frontmatter.
Inputs: query (required), mode, limit, project, +2 more.
sessionADestructiveIdempotent
Register, update, or query active agent sessions for multi-agent coordination. On complete, persists a session note to the vault.
Inputs: action (required), tool, blocked, outcome, +11 more.
skill_installADestructive
Install skills from a GitHub repo (e.g. owner/repo or full URL). Resolves the skill list and gen/socket/snyk audits via skills.sh; fail-audit skills are blocked, and the unaudited GitHub fallback is used only when skills.sh is unreachable.
Inputs: source (required), select_skills, allow_unaudited.
skill_list_installedARead-only
List skills installed locally from GitHub repos.
Inputs: no named parameters.
skill_removeADestructive
Remove an installed skill by name.
Inputs: name (required).
skill_validateARead-only
Validate a native skill file against Anthropic or portable requirements without modifying it.
Inputs: path, profile, workspace_path.
snapshot_repo_stateBDestructive
Snapshot current git state (branch, dirty files, last commit) into the vault. Helps avoid repeating repo discovery across sessions.
Inputs: branch, project, dirty_files, last_commit, +1 more.
specADestructive
Manage deterministic plan specs. Actions: create, status, approve, freeze, list. Specs use a fixed skeleton (goal, non-goals, constraints, context, files, acceptance, risks, rollback). Approve requires zero gaps; freeze pins a content hash and makes the spec immutable.
Inputs: action (required), goal, spec, risks, +10 more.
statsBRead-only
Show content statistics for a project — file counts, task breakdown, growth monitoring.
Inputs: project, workspace_path.
statusARead-only
Show superskill knowledge graph state: loaded skills, weights, recent sessions.
Inputs: no named parameters.
superskillB
Route a task to curated in-repo packs and verified rules selected by language, keywords, symbols and file hints. Phase selects methodology packs and budget, not individual rule eligibility. Does not scrape skills.sh or execute plan flows/gates.
Inputs: task, files, phase, detail, +4 more.
taskBDestructive
Manage project tasks. Supports add, list, update, and board (kanban) views. Tasks are stored as individual files in projects//tasks/.
Inputs: action (required), tags, limit, title, +7 more.
telemetryA
Local, opt-in rule-selection telemetry: status/enable/disable/report/clear. Mutations require explicit user authorization and confirm=true. Events never leave the machine; prompts are stored only as truncated hashes.
Inputs: top, action, confirm.
templateARead-only
Get pre-filled templates for common vault item types (adr, prd, decision, learning, spec, rfc, roadmap, competitive-analysis, incident, research, vision, strategy). Use to scaffold new documents.
Inputs: type, action, variables.
ticketsBDestructive
Manage tickets derived from a frozen spec. Actions: create, list, board, ready, update. Tickets carry acceptance criteria, blocked_by, a requires_review flag, and an evidence slot. ready returns unblocked tickets in deterministic topological order.
Inputs: action (required), spec, limit, status, +4 more.
watchdogADestructive
Session review + environment optimization. action='dig' analyzes a session, a window of sessions, or the machine environment and returns severity-ranked findings with evidence and proposals (digests for agent reasoning, persisted to the vault as watchdog notes). action='fix' applies approved repairs — dry-run by default; file reclamation is quarantined and reversible. action='status' lists past digs and pending findings.
Inputs: action (required), tool, apply, count, +13 more.
worktree_activateAIdempotent
Install the shared build-cache policy for this repo: policy file in .git/superskill, guarded post-checkout hook, and host session hooks. Call with confirm=false first to preview; only pass confirm=true after the user agrees. Nothing is ever deleted.
Inputs: confirm (required), json, seed, hooks, +4 more.
worktree_applyADestructive
Apply selected audit recommendation items (policy/hook/seed/tool-prune) after user consent. Requires confirm=true to mutate; without it returns the plan. Never removes worktrees or user files.
Inputs: item, json, confirm, all_safe, +1 more.
worktree_auditARead-only
Read-only audit of git worktrees and build-cache duplication for this repo. Reports safety verdicts and recommendation items. Never deletes anything.
Inputs: json, sizes, worktree, workspace_path.
worktree_envARead-only
Resolve shared-cache environment variables for the current git worktree (cache dirs + hit-enabling flags). Use before running installs/builds in a worktree.
Inputs: json, shell, providers, timeout_ms, +1 more.
worktree_gcADestructive
Reclaim rebuildable build-cache entries (project-wise or --all). Default is a dry-run report. Mutations require confirm=true; deletions are quarantine-only (reversible via undo). Filters: tool, older_than, newer_than, min_size, max_size, tier, include, exclude, keep_latest, project, all, undo, journal_id, purge.
Inputs: all, json, tier, tool, +14 more.
worktree_statusBRead-only
Worktree cache status: policy/hook state, per-worktree safety, cache bytes, optional budget check.
Inputs: json, budget, workspace_path.
worktree_uninstallADestructive
Remove worktree-cache integration for this repo: host session hooks, post-checkout hook, policy metadata. Caches are untouched unless purge_local=true AND confirm=true (then this repo's cache namespace is quarantined, still reversible).
Inputs: json, confirm, purge_local, workspace_path.
writeCDestructive
Write or append to a file in the AI knowledge vault.
Inputs: path (required), content (required), mode, frontmatter, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Many tools overlap in purpose: capture, extract, learn, decide, task, and brainstorm all store different knowledge artifacts, while status, stats, doctor, telemetry, hygiene_report, watchdog, resume, and session all report on project/session state. Descriptions help somewhat, but an agent faces multiple plausible choices for common actions like recalling context, recording knowledge, or checking health.
Naming mixes single-word nouns and verbs (spec, tickets, gate, read, write) with prefixed snake_case families (worktree_*, skill_*, graph_*, knowledge_*). The groupings are readable, but there is no single consistent verb_noun pattern across all 52 tools.
52 tools is far beyond the typical concise MCP surface and exceeds the rubric's 50+ extreme mismatch threshold. Even with broad knowledge, skill, worktree, and hygiene domains, this many tools creates a high selection burden and likely includes low-frequency operations better exposed as actions within fewer multiplexed tools.
The surface is extensive and covers most domains it names: vault read/write/search/link/capture/extract, skill install/list/remove/validate, worktree lifecycle, spec/ticket/evidence/gate workflows, graph traversal, and session coordination. Only minor gaps exist, such as explicit edit/delete operations for individual vault notes beyond deprecate/prune, but agents can work around them.
Maintenance
Related MCP Connectors
Intent execution engine for autonomous agent task routing
One place to build, share, and govern the skills and tools your AI agents use at work.
Discover, compare, route, and execute machine-accessible capabilities for AI agents.
Search and load agent skills on demand from a shared skill store.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceProvides dynamic, context-aware code assistant skills through hybrid RAG (vector + knowledge graph), enabling runtime skill discovery, automatic toolchain-based recommendations, and on-demand loading from multiple git repositories.63 PyPI20MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to intelligently match tasks to skills through semantic embeddings, track skill effectiveness, detect skill gaps, and discover new skills from external sources.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides context-aware skill selection for AI agents, reducing token usage by 85-98% and improving accuracy through semantic retrieval, session memory, and feedback learning.1MIT
- AlicenseAqualityDmaintenanceRoutes SKILL.md libraries to any MCP client, enabling task matching and skill loading with embedding-based scoring, keyword fallback, and context-window discipline.528 npmMIT