hotskills

hotskills

Pre-configured skill management for Claude Code — discover, activate, and invoke skills from skills.sh and GitHub with built-in security gating, audit-API integration, and per-project allow-lists.

Status

v0.1.x — published on npm as hotskills and consumed by the plugin via npx -y hotskills. All six MCP tools, the four-layer security gate stack, the three Claude Code hooks, and the two slash commands are wired up. Full test coverage: 287 server tests + 44 hook bash assertions + a stdio E2E that runs against the published bin (scripts/e2e-npx.sh).

Install

The MCP server is published on npm; the plugin's .mcp.json launches it via npx -y hotskills, so there's no local build step.

In Claude Code:

/plugin install <path-to-this-repo>

Or for one-off use without permanent install:

claude --plugin-dir <path-to-this-repo>

Then run /hotskills-setup once (or claude mcp add -s user hotskills -- npx -y hotskills directly) to register the MCP server in your user or project scope.

You'll see five new things in the session:

• The hotskills MCP server with six tools (hotskills.search, .activate, .deactivate, .list, .invoke, .audit).
• Two slash commands: /hotskills and /hotskills-setup.
• Three hooks (PostCompact, SessionStart, UserPromptSubmit) that re-inject the activated-skills reminder so the model retains awareness across compaction.

First-time setup

Run once per machine:

/hotskills-setup

This creates ~/.config/hotskills/config.json with a sensible default security policy, auto-activates vercel-labs/skills:find-skills globally, patches your project's .gitignore to exclude .hotskills/state.json, and verifies that the audit API + skills.sh API are reachable.

Prerequisites

• Node.js ≥ 22 — the MCP server is ESM with native node:test. npx (bundled with npm) launches the server.
• git ≥ 2.25 — only required if you configure GitHub-typed sources (uses --filter=blob:none --sparse).
• jq — required by the hook script (scripts/inject-reminders.sh).

How it works

1. Discovery. hotskills.search "react" queries the skills.sh API (fuzzy match across name/source/slug) and decorates each result with audit data and a gate preview. Multi-word queries ("code review") are normalized to hyphenated form (code-review) before the API call, since skills.sh treats whitespace as end-of-query. Results are cached on disk for 1 hour.
2. Security gating. hotskills.activate runs the four-layer gate stack: whitelist → audit (snyk/socket/etc.) → heuristic (opt-in static scanner) → install threshold + author allowlist. First BLOCK short-circuits.
3. Materialization. Allowed skills are materialized to ~/.config/hotskills/cache/skills/<source>/<owner>/<repo>/<slug>/ — using vendored blob.ts for skills.sh: IDs or git sparse-checkout for github: IDs.
4. Manifest fast-path. Re-activation with the same content SHA-256 returns reused: true without any network. Concurrent activators converge on a single materialization via O_EXCL locks.
5. Allow-list persistence. Activated skills are written to <project>/.hotskills/config.json. State (opportunistic flag, session id) lives in state.json (gitignored).
6. Compaction-survival. A hook script emits <system-reminder> blocks on PostCompact, SessionStart, and UserPromptSubmit so the model keeps awareness of activated skills after /clear or context compaction.

Tools

Tool	Purpose
hotskills.search { query, sources?, limit? }	Cache-first ranked search; returns skill_id, installs, audit, gate_status
hotskills.activate { skill_id, install_count?, force_whitelist? }	Gate → materialize → manifest → allow-list. Returns {skill_id, path, manifest, reused}
hotskills.invoke { skill_id }	Reads SKILL.md, substitutes ${SKILL_PATH}, enumerates scripts/ + references/
hotskills.list { scope? }	Activated skills (project, global, or merged)
hotskills.deactivate { skill_id, scope? }	Removes from allow-list; cache directory is preserved
hotskills.audit { skill_id }	Cached audit data + gate preview

Slash commands

• /hotskills (no args) — show activated skills for the current project, prompt for a query.
• /hotskills [query] — ranked search with audit/gate status.
• /hotskills [query] --auto — auto-activate the top gate-passing result.
• /hotskills [query] --source <owner/repo> — restrict search to a single source.
• /hotskills --whitelist <skill_id> — bypass all gates for one skill (with mandatory warning).
• /hotskills-setup — first-time onboarding (idempotent on re-run).

Hooks