@skillsmith/mcp-server

@skillsmith/mcp-server

Important: The bare skillsmith package on npm is not this project. Install @skillsmith/mcp-server for the MCP server or @skillsmith/cli for CLI usage.

MCP (Model Context Protocol) server for agent skill publishing, installation, and lifecycle management.

Part of Skillsmith: a lifecycle layer for agent skills across teams.

What's New in v0.7.7

• search's limit parameter actually works now: previously advertised in the tool description but silently dropped — no limit field existed in the input schema at all. Now threaded through both the API and local-fallback paths, clamped to [1, 100].
• skill_compare and skill_recommend fixed: compare now resolves any skill search/get_skill can find (was local-cache-only); recommend no longer 400s or silently zeroes on an empty derived stack — both return a structured, actionable result instead.
• skill_updates scoped to your installed skills: was running an unfiltered registry-wide scan (updatesAvailable: 2833 for a handful of installs); now bounded to the local manifest, sharing derivation with skill_outdated so the two can't drift apart again.
• Trust-tier vocabulary fixed: mapTrustTierFromDb was silently collapsing official and unverified to unknown; all TrustTier values now round-trip correctly across search, get_skill, skill_recommend, skill_compare, and skill_suggest.
• New local security-acceptance allowlist: mark a reviewed false-positive finding as accepted so it stops re-surfacing in future audits, without affecting rug-pull/hostile-update detection.
• private_registry_manage gains install: installs a previously-published private-registry skill to disk, closing the publish→install gap.

See CHANGELOG.md for previous releases.

Auto-Update Notifications

The MCP server checks for updates on startup and notifies you when a newer version is available:

[skillsmith] Update available: 0.7.3 → 0.7.4
Restart your MCP client to use the latest version.

To disable update checks, set SKILLSMITH_AUTO_UPDATE_CHECK=false in your environment.

Local-first by design. Skillsmith caches the registry in a local SQLite database at ~/.skillsmith/skills.db, shared across the MCP server, the CLI, and the VS Code extension. Search is FTS5 (SQLite's built-in keyword search) by default; semantic search is opt-in (SKILLSMITH_USE_HNSW=true) and runs over local ONNX embeddings (an open ML model format that runs on CPU — no API call). Inside the Local Skill Database walks through the schema, the FTS5 / HNSW search paths, and how sync keeps the cache fresh.

Installation

npm install @skillsmith/mcp-server

Quick Start

Skillsmith works with any MCP-compatible AI agent. Pick the snippet for your client. SMI-4580: snippets are sourced from @skillsmith/cli/templates/mcp-server.template.snippets.ts so this README and the website docs cannot drift.

Claude Code — ~/.claude/settings.json

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

Restart Claude Code after editing settings.json.

Skillsmith contributors: If you're working inside the skillsmith monorepo, do NOT add the above global ~/.claude/settings.json entry. The project's .mcp.json already configures the skillsmith MCP server via scripts/mcp-skillsmith-launcher.sh. Adding a global entry causes Claude Code to attempt a second connection that also announces as skillsmith-mcp, resulting in "Failed to reconnect to skillsmith" errors. Remove the global entry; the project entry takes precedence.

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_...",
        "SKILLSMITH_CLIENT": "cursor"
      }
    }
  }
}

Cursor 2.4+ required. Reload the window after saving. SKILLSMITH_CLIENT routes installs to ~/.cursor/skills instead of the default ~/.claude/skills.

Recommended: npm install -g @skillsmith/mcp-server first, then point command at the installed skillsmith-mcp binary — run which skillsmith-mcp after installing to get the exact path (it's platform/npm-prefix specific, e.g. /opt/homebrew/bin/skillsmith-mcp on macOS/Homebrew; Linux and Windows paths differ). The npx form above still works as a fallback, but re-resolves the package on every launch — expect a slower cold start, and watch for EBADENGINE (Cursor bundles its own Node, sometimes older than the >=22.22 this package requires) or ENOTEMPTY errors on repeated installs.

GitHub Copilot (VS Code) — .vscode/mcp.json (workspace)

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

VS Code 1.108+ required. Workspace-scoped (commit to repo if team-shared, or use user settings.json instead).

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "${env:SKILLSMITH_API_KEY}"
      }
    }
  }
}

Supports ${env:VAR} interpolation; export SKILLSMITH_API_KEY in your shell instead of inlining the secret.

Codex CLI — ~/.codex/config.toml (TOML, not JSON)

[mcp_servers.skillsmith]
command = "npx"
args = ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"]

[mcp_servers.skillsmith.env]
SKILLSMITH_API_KEY = "sk_live_..."

Codex reads ~/.agents/skills. When installing via Skillsmith CLI, pass --client agents.

Cross-agent (open standard) — ~/.agents/mcp.json

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_..."
      }
    }
  }
}

Read by any agent honouring the cross-agent skill convention.

Get your API key at https://skillsmith.app/account (free Community tier available).

After adding to your MCP client settings and restarting, try asking:

"Search for testing skills"
"Find verified skills for git workflows"
"Install the commit skill"
"Compare jest-helper and vitest-helper"

Live Skill Registry

The Skillsmith API provides access to hundreds of thousands of indexed skills that are:

• Indexed daily from GitHub repositories
• Security screened hourly for vulnerabilities and malicious patterns
• Quality scored based on documentation, structure, and community feedback
• Categorized by trust tier (Verified, Community, Experimental)

Skills are served from api.skillsmith.app and cached locally for 24 hours.

Note (v0.3.8): Fixed critical bug where the MCP server defaulted to offline mode for all users. Search now correctly connects to the production API.

Why Configure an API Key?

Without an API key, you're limited to 10 total requests (trial mode). With a free Community account, you get 30 requests/minute with access to all live skills.

Benefits of API key:

• Access to live indexed skills (not just cached)
• Higher rate limits based on your tier
• Usage tracking on your dashboard
• Priority during high-traffic periods

API Key Configuration

Step 1: Get your API key from https://skillsmith.app/account

Step 2: Add to your Claude settings at ~/.claude/settings.json:

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Step 3: Restart your MCP client

Security Note: Never paste your API key in chat. Configure it via the settings file above. For testing, set the env var using the appropriate command for your platform:

Platform	Command
Mac/Linux	!export SKILLSMITH_API_KEY='your-key-here'
Windows PowerShell	!$env:SKILLSMITH_API_KEY='your-key-here'
Windows CMD	!set SKILLSMITH_API_KEY=your-key-here

The ! prefix in Claude Code runs the command without exposing the output.

Rate Limits by Tier

Tier	Rate Limit	Monthly Cost	Best For
Trial	10 total	Free	Quick evaluation
Community	30/min	Free	Personal projects
Individual	60/min	$9.99/mo	Active developers
Team	120/min	$25/user/mo	Development teams
Enterprise	300/min	$55/user/mo	Large organizations

All tiers include:

• Full access to skill search, details, and recommendations
• Security screening results
• Quality scores and trust tier information

API Configuration

Variable	Default	Description
SKILLSMITH_API_KEY	-	Personal API key for usage tracking
SKILLSMITH_API_URL	https://api.skillsmith.app/functions/v1	API endpoint
SKILLSMITH_OFFLINE_MODE	false	Use local database instead
SKILLSMITH_TELEMETRY	true	Enable anonymous telemetry

Available Tools

Tool	Description	Tier
search	Search for skills with filters	Community
get_skill	Get detailed skill information	Community
install_skill	Install a skill to ~/.claude/skills	Community
uninstall_skill	Remove an installed skill	Community
skill_recommend	Get contextual skill recommendations	Community
skill_validate	Validate a skill's structure	Community
skill_compare	Compare skills side-by-side	Community
skill_suggest	Suggest skills based on project context (counts against monthly quota)	Community
skill_outdated	Check installed skills for staleness and dependency status	Community
index_local	Index skills from a local directory	Community
skill_publish	Prepare a skill for publishing	Community
skill_rescan	Re-scan an installed skill's content	Community
skill_recover_source	Recover the canonical GitHub source of locally-installed skills (read-only report + candidates)	Community
inventory_push	Push this machine's installed-skill inventory to your Skillsmith account for the web dashboard (read-only; requires skillsmith login)	Community
skill_updates	Check registry for newer skill versions	Individual+
skill_diff	Section-level diff between skill versions	Individual+
skill_pack_audit	Audit all skills in a directory	Individual+
skill_audit	Check skills for security advisories	Team+
skill_inventory_audit	Audit local ~/.claude/ inventory for namespace collisions; returns rename + edit suggestions	Team+
apply_namespace_rename	Apply a rename suggestion from an inventory audit (apply/custom/skip)	Team+
apply_recommended_edit	Apply a recommended prose edit from an inventory audit (gated on APPLY_TEMPLATE_REGISTRY)	Team+
undo_apply	Session-scoped undo for the most recent apply_namespace_rename / apply_recommended_edit changeset(s), restored from the apply tool's own backup	Team+
team_workspace	Manage team workspaces (create, list, get, delete)	Team+
share_skill	Add, remove, or list skills in a team workspace	Team+
publish_private	Mark a skill as private to your team	Team+
team_analytics_dashboard	Per-user tool usage counts, top tools, daily trend	Team+
team_usage_report	Weekly/monthly usage summary with period comparison	Team+
audit_export	Export audit log events for a time range	Enterprise
audit_query	Query audit logs with filters	Enterprise
siem_export	Export audit events for SIEM ingestion	Enterprise
analytics_dashboard	Recommendation accuracy, adoption curves, team aggregation	Enterprise
usage_report	Comprehensive usage report with all metrics	Enterprise
configure_sso	Configure SSO/SAML integration (set, test, remove)	Enterprise
sso_settings	View current SSO/SAML configuration	Enterprise
private_registry_publish	Publish a skill to your private registry	Enterprise
private_registry_manage	Manage private registry skills (list, get, deprecate)	Enterprise
rbac_manage	Manage RBAC roles (create, list, get, delete)	Enterprise
rbac_assign_role	Assign or revoke roles for users	Enterprise
rbac_create_policy	Create and manage RBAC access policies	Enterprise
webhook_configure	Configure HMAC-SHA256 signed webhooks for skill events (in preview — availability pending production migration)	Enterprise
api_key_manage	Manage API keys for programmatic access (in preview — availability pending production migration)	Enterprise

| compliance_report | Generate SOC2, CycloneDX SBOM, or JSON compliance reports | Enterprise |

Tool Parameters

search

Search for skills matching a query.

Parameter	Type	Required	Description
query	string	Conditional	Search term (min 3 characters); required unless a filter (category/trust_tier/min_score) is provided
category	string	No	Filter by category (development, testing, devops, etc.)
trust_tier	string	No	Filter by trust level (verified, community, experimental)
min_score	number	No	Minimum quality score (0-100)
limit	number	No	Max results (default 10)

Response fields include: repository_url, homepage_url (when declared by the skill author), and compatibility tags (LLMs, IDEs, platforms supported).

get_skill

Get detailed information about a specific skill.

Parameter	Type	Required	Description
id	string	Yes	Skill ID in format author/name

Response fields include: also_installed — an array of skills frequently co-installed alongside this one (surfaced once ≥5 co-installs are observed). Each entry contains skillId, name, description, and installCount.

install_skill

Install a skill to your local environment.

Parameter	Type	Required	Description
id	string	Yes	Skill ID to install

uninstall_skill

Remove an installed skill.

Parameter	Type	Required	Description
id	string	Yes	Skill ID to uninstall

skill_recommend

Get skill recommendations based on context.

Parameter	Type	Required	Description
context	string	Yes	Description of your project or needs
limit	number	No	Max recommendations (default 5)

skill_validate

Validate a skill's SKILL.md file.

Parameter	Type	Required	Description
path	string	Yes	Path to skill directory or SKILL.md

skill_compare

Compare multiple skills side-by-side.

Parameter	Type	Required	Description
skill_ids	string[]	Yes	Array of skill IDs to compare (2-5)

skill_suggest

Proactively suggest relevant skills based on current project context. Counts against your monthly API quota.

Parameter	Type	Required	Description
project_path	string	Yes	Absolute path to the project directory
current_file	string	No	File currently being edited
recent_commands	string[]	No	Recent terminal commands (last 5)
error_message	string	No	Recent error message, if any
installed_skills	string[]	No	Currently installed skill IDs (for filtering)
limit	number	No	Max suggestions to return (default 3, max 10)
session_id	string	No	Session identifier (optional, for informational purposes)

skill_outdated

Check installed skills for available updates and dependency satisfaction status.

Parameter	Type	Required	Description
include_deps	boolean	No	Include dependency satisfaction status (default: true)

skill_diff

Show a section-level diff between two versions of a skill. Returns added, removed, and modified headings along with a change type (major/minor/patch) and update recommendation. Requires Individual tier or higher.

Parameter	Type	Required	Description
skillId	string	Yes	Registry skill identifier (e.g. author/skill-name)
oldContent	string	Yes	Previous SKILL.md content
newContent	string	Yes	Updated SKILL.md content
oldRiskScore	number	No	Risk score of the old version (0–100)
newRiskScore	number	No	Risk score of the new version (0–100)
hasLocalModifications	boolean	No	Whether the installed skill has local edits (default: false)
trustTier	string	No	Registry trust tier: verified, community, experimental (default: community)

skill_audit

Check installed skills for known security advisories. Requires Team tier or higher. The advisory system is in early access.

Parameter	Type	Required	Description
skillIds	string[]	No	Specific skill IDs to audit (omit to return all skills with active advisories)

index_local

Index local skills from ~/.claude/skills/ directory.

Parameter	Type	Required	Description
force	boolean	No	Force re-indexing even if cache is valid (default: false)
skillsDir	string	No	Custom skills directory path (defaults to ~/.claude/skills/)

Trust Tiers

Tier	Description
verified	Official platform skills
community	Community-reviewed skills
experimental	New/beta skills
unknown	Unverified skills

Environment Variables

Variable	Description	Default
SKILLSMITH_DB_PATH	Database file location	~/.skillsmith/skills.db
SKILLSMITH_TELEMETRY_ENABLED	Enable anonymous telemetry	false
SKILLSMITH_USE_WASM	Force WASM SQLite driver (sql.js)	false
SKILLSMITH_ERROR_LOG_DISABLE	Disable structured error logging to disk (set to '1' or 'true' to opt-out)	unset (logging ON)
SKILLSMITH_LOG_LEVEL	Filter log verbosity: debug, info, warn, error	warn
POSTHOG_API_KEY	PostHog API key (required if telemetry enabled)	-
SKILLSMITH_API_KEY_HMAC_SECRET	HMAC secret for hashing Custom Integration API keys before DB storage. Required if you invoke webhook_configure or api_key_manage. See setup below.	-

Custom Integration Setup (Team+ admins)

The webhook_configure and api_key_manage tools hash secrets server-side via HMAC-SHA-256 before persisting to the shared api_keys table. The HMAC key lives in SKILLSMITH_API_KEY_HMAC_SECRET rather than as a hardcoded constant — defense-in-depth so a leaked DB cannot be reverse-cracked offline.

Distribution model: identical to SUPABASE_SERVICE_ROLE_KEY. The same secret value must be set on every MCP host that creates or verifies Custom Integration API keys, otherwise hashes computed on host A won't match hashes verified on host B.

Error Logging (SMI-5615)

The MCP server automatically logs errors to disk in a structured, redacted format for debugging and post-incident analysis.

Log Location: ~/.skillsmith/logs/skillsmith-mcp-<YYYY-MM-DD>.jsonl

Log Format: One JSON-line record per error event, with fields:

• ts — ISO 8601 timestamp
• level — log level (debug, info, warn, error)
• surface — invocation surface (mcp, cli, or vscode)
• event — short machine-readable category tag
• msg — human-readable message (redacted)
• err — normalized error object with name, message, and first 20 stack frames (all redacted)
• correlationId — trace ID that links related log entries, telemetry events, and API calls within a single skill invocation
• toolOrCommand — MCP tool name being executed
• skillId — skill ID when applicable
• version — MCP server package version
• pid — process ID
• details — additional structured context beyond the fields above, when provided (redacted)

Automatic Redaction: Secrets, tokens, API keys, passwords, connection strings, and PEM keys are automatically redacted before any record is written to disk (SMI-883). This redaction applies to the message, error stack, and any structured context, so logs are always safe to inspect or share without manual review.

Rotation & Retention: Log files rotate daily (one file per UTC calendar date) and are capped at ~10MB each, with .1/.2 continuation files for larger days. Files older than 14 days are automatically deleted on server startup.

Console Mirror: The warn and error levels always mirror to stderr in real-time (matching the level), so terminal output is never silent. Log files add redacted persistence on top, not instead of console output.

Control Logging:

Set either variable to disable or filter logging:

# Disable error logging entirely
export SKILLSMITH_ERROR_LOG_DISABLE=1

# Enable debug-level verbosity for more detail
export SKILLSMITH_LOG_LEVEL=debug

Valid log levels: debug, info, warn, error (default: warn). Higher levels are included (e.g., warn also logs error).

If the variable is missing or shorter than 32 characters when these tools are invoked, the call fails fast with:

SKILLSMITH_API_KEY_HMAC_SECRET must be set to a 32+ character random secret
before integration tools can be used. Generate one via: openssl rand -base64 48

First-time provisioning (Skillsmith admin, once per organization):

openssl rand -base64 48

Distribute that value through the same secure channel used for SUPABASE_SERVICE_ROLE_KEY (e.g., 1Password vault, encrypted onboarding email). Each Team-tier admin sets it on their own MCP host alongside their other secrets:

// ~/.claude/settings.json
{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "-p", "@skillsmith/mcp-server", "skillsmith-mcp"],
      "env": {
        "SKILLSMITH_API_KEY": "sk_live_your_personal_key",
        "SKILLSMITH_LICENSE_KEY": "sklic_your_team_license",
        "SUPABASE_SERVICE_ROLE_KEY": "eyJ...your_service_role_jwt",
        "SKILLSMITH_API_KEY_HMAC_SECRET": "<the shared 32+ char secret>"
      }
    }
  }
}

Rotation: replace the secret on every host in lockstep. Existing rows in the api_keys table become unverifiable after rotation, so coordinate with affected admins or invalidate keys explicitly. As of 2026-04-26 the table has zero rows, so the first rotation post-launch is free.

If you only use Community/Individual tools (search, install, recommend, etc.), this variable is not needed.

WASM Fallback (v0.3.18+)

The MCP server automatically falls back to a WASM-based SQLite driver (sql.js) when native better-sqlite3 is unavailable. This ensures the server works in environments where native modules can't be compiled.

The fallback is automatic—no configuration needed. To force WASM mode:

export SKILLSMITH_USE_WASM=true

Telemetry

Skillsmith includes optional, anonymous telemetry to help improve the product. Telemetry is disabled by default.

To enable telemetry:

export SKILLSMITH_TELEMETRY_ENABLED=true
export POSTHOG_API_KEY=your_api_key

See PRIVACY.md for full details on what data is collected and how it's used.

License

Elastic License 2.0

Links

• GitHub
• Issues