Skip to main content
Glama

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.

npm license

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 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 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

Apache-2.0 — LICENSE · NOTICE

Copyright 2026 Permanu (Atharva Pandey)

Available Tools

52 tools
brainstormC
Destructive

Start or continue a brainstorm document for a project.

Inputs: topic (required), content (required), project, workspace_path.

captureB
Destructive

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.

claimsA
Read-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_refsB
Destructive

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.

decideC
Destructive

Log an architectural/design decision to the project's decisions directory.

Inputs: title (required), decision (required), context, project, +3 more.

deprecateB
Destructive

Mark a vault item (ADR, learning, etc.) as deprecated with an optional reason.

Inputs: path (required), reason, workspace_path.

doctorB
Read-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_factsA
Destructive

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.

evidenceB
Destructive

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.

extractB
Destructive

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.

gateA
Read-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_contextA
Read-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_projectB
Read-only

Search the current project's vault only. Cross-project search is denied.

Inputs: query (required), limit, workspace_path.

graph_traverseA
Read-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_reportA
Read-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.

impactA
Read-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.

initA
Destructive

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.

learnB
Destructive

Capture and query learnings. Learnings persist discoveries across sessions. Stored as individual files in projects//learnings/.

Inputs: action (required), tag, tags, limit, +7 more.

project_contextB
Read-only

Get the context document for a project. Auto-detects project from CWD if not specified.

Inputs: project, max_tokens, detail_level, workspace_path.

pruneA
Destructive

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.

readA
Read-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.

resumeA
Read-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.

rollbackB
Destructive

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.

sessionA
DestructiveIdempotent

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_installA
Destructive

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_installedA
Read-only

List skills installed locally from GitHub repos.

Inputs: no named parameters.

skill_removeA
Destructive

Remove an installed skill by name.

Inputs: name (required).

skill_validateA
Read-only

Validate a native skill file against Anthropic or portable requirements without modifying it.

Inputs: path, profile, workspace_path.

snapshot_repo_stateB
Destructive

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.

specA
Destructive

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.

statsB
Read-only

Show content statistics for a project — file counts, task breakdown, growth monitoring.

Inputs: project, workspace_path.

statusA
Read-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.

taskB
Destructive

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.

templateA
Read-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.

ticketsB
Destructive

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.

watchdogA
Destructive

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_activateA
Idempotent

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_applyA
Destructive

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_auditA
Read-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_envA
Read-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_gcA
Destructive

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_statusB
Read-only

Worktree cache status: policy/hook state, per-worktree safety, cache bytes, optional budget check.

Inputs: json, budget, workspace_path.

worktree_uninstallA
Destructive

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.

writeC
Destructive

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

    B3.1/5.0

    Scored across 52 tools

    Disambiguation2/5

    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 Consistency3/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Provides 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 PyPI
      20
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables 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