MCP Server

The Skillsmith MCP server integrates with MCP-compatible clients, enabling natural language skill installation and lifecycle management.

Overview

MCP (Model Context Protocol) servers extend your AI assistant's capabilities by providing additional tools. The Skillsmith MCP server adds tools for searching, installing, and managing skills.

Configuration

Basic Setup

Pick the snippet for your MCP client and add it to the matching config file. Every snippet uses the same shape — only the config-file path (and, for Codex/Hermes, the format) differs.

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

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "<paste output of: which skillsmith-mcp (macOS/Linux) or where skillsmith-mcp (Windows)>",
      "env": {
        "SKILLSMITH_CLIENT": "cursor"
      }
    }
  }
}

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

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

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

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

{
  "mcp": {
    "@skillsmith/mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "@skillsmith/mcp-server"],
      "enabled": true
    }
  }
}

mcp_servers:
  @skillsmith/mcp-server:
    command: "npx"
    args: ["-y", "@skillsmith/mcp-server"]

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

{
  "mcpServers": {
    "@skillsmith/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_CLIENT": "antigravity"
      }
    }
  }
}

Advanced Configuration

For more control, add extra options to the env block of whichever client snippet you used above — keep that snippet's own command and args (or, for Cursor, its resolved-path command) and just add to its env. Example (Claude Code shape shown):

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_LOG_LEVEL": "debug",
        "SKILLSMITH_CACHE_TTL": "3600"
      }
    }
  }
}

This env-block pattern applies as shown to every JSON-shaped client (Claude Code, Cursor, Copilot, Windsurf, Antigravity, cross-agent). OpenCode uses an environment key instead of env (with command as an array); Codex, Grok, and Hermes use TOML/YAML, not JSON — add the same variables under each format's own env table/mapping instead.

API Key Configuration

The Skillsmith API provides access to thousands of skills, indexed daily by scanning SKILL.md files across GitHub and security screened hourly for vulnerabilities. Configure your API key for higher rate limits and usage tracking.

Why Use an API Key?

• Live indexed skills - Access skills as they're discovered and screened
• Higher rate limits - Up to 600 requests/minute on Enterprise tier
• Usage dashboard - Track your API usage at www.skillsmith.app/account
• Priority access - During high-traffic periods

Setup

Step 1: Create an account and get your API key at www.skillsmith.app/account

Step 2: Configure your API key using one of these methods:

Method A: Config File (Recommended)

Create ~/.skillsmith/config.json - works on all platforms:

mkdir -p ~/.skillsmith && cat > ~/.skillsmith/config.json << 'EOF'
{
  "apiKey": "sk_live_your_key_here"
}
EOF

Method B: MCP Client Config

Add SKILLSMITH_API_KEY to the env block of whichever client snippet you used above — keep that snippet's own command and args (or, for Cursor, its resolved-path command) and just add the key. Example (Claude Code shape shown):

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

This env-block pattern applies as shown to every JSON-shaped client (Claude Code, Cursor, Copilot, Windsurf, Antigravity, cross-agent). OpenCode uses an environment key instead of env (with command as an array); Codex, Grok, and Hermes use TOML/YAML, not JSON — add the same variable under each format's own env table/mapping instead.

Step 3: Restart your MCP client to load the updated configuration.

Rate Limits by Tier

Other Environment Variables

Available Tools

The MCP server provides the following tools:

search

Search for skills in the registry.

// Tool: search
// Parameters:
{
  "query": "testing",           // Search term (required)
  "category": "development",    // Category filter
  "trust_tier": "verified",     // Trust tier filter
  "min_score": 70,              // Minimum quality score
  "limit": 10                   // Max results
}

Results include repository_url and homepage_url when declared by the skill author, plus compatibility tags indicating supported LLMs, IDEs, and platforms.

Example prompts:

• "Use Skillsmith to search for testing skills"
• "Ask Skillsmith for verified skills tagged git workflows"
• "Use Skillsmith to find devops skills with quality score above 80"

get_skill

Get detailed information about a specific skill.

// Tool: get_skill
// Parameters:
{
  "id": "community/jest-helper"  // Skill ID (required)
}

The response includes an also_installed array — skills that users frequently install alongside this one. Each entry contains skillId, name, description, and installCount. Only surfaces once a skill pair has reached 5 or more co-installs.

Example prompts:

• "Use Skillsmith to show details for community/jest-helper"
• "Ask Skillsmith what the git-commit skill does"

install_skill

Install a skill to the local environment.

// Tool: install_skill
// Parameters:
{
  "id": "community/jest-helper",  // Skill ID (required)
  "path": "~/.claude/skills",     // Installation path
  "force": false                  // Overwrite existing
}

Example prompts:

• "Use Skillsmith to install jest-helper"
• "Ask Skillsmith to install community/git-commit"

uninstall_skill

Remove an installed skill.

// Tool: uninstall_skill
// Parameters:
{
  "id": "community/jest-helper"  // Skill ID (required)
}

Example prompts:

• "Use Skillsmith to uninstall jest-helper"
• "Ask Skillsmith to remove community/git-commit"

recommend

Get personalized skill recommendations.

// Tool: recommend
// Parameters:
{
  "context": "react",     // Technology context
  "limit": 5              // Max recommendations
}

Example prompts:

• "Ask Skillsmith to recommend skills for my React project"
• "Use Skillsmith to find skills that help with Node.js development"

compare

Compare multiple skills side-by-side.

// Tool: compare
// Parameters:
{
  "skill_ids": ["jest-helper", "vitest-helper"]  // 2-5 skill IDs
}

Example prompts:

• "Use Skillsmith to compare jest-helper and vitest-helper"
• "Ask Skillsmith to compare these testing skills side-by-side"

validate

Validate a skill's structure.

// Tool: validate
// Parameters:
{
  "path": "./my-skill"  // Path to skill directory
}

Example prompts:

• "Use Skillsmith to validate my skill at ./my-skill"
• "Ask Skillsmith to check if this skill structure is correct"

publish_private

Mark a skill private on this device, hiding it from your own community search results. Team tier. See Private Skills for the full picture — it's a single-device setting, not shared with teammates.

// Tool: publish_private
// Parameters:
{
  "skillId": "author/name"  // Skill ID to mark private (required)
}

Example prompts:

• "Use Skillsmith to mark my-internal-skill private"

private_registry_publish

Publish a skill version to your organization's shared private registry as a pending submission — a team admin has to approve it before anyone (including you) can install it. Enterprise tier. See Private Registry for the full approval workflow and access-control model.

// Tool: private_registry_publish
// Parameters:
{
  "skillId": "author/name",       // Skill ID (required)
  "version": "1.0.0",             // Semver version (required)
  "content": { "SKILL.md": "..." } // Packaged skill files (required)
}

Example prompts:

• "Use Skillsmith to publish version 1.0.0 of my-org/deploy-helper to the private registry"

private_registry_manage

Manage your organization's private registry — list, get, install, deprecate, and review skills via the action parameter (including submissions, approve, and reject for reviewing pending publishes). The namespace action returns your team's registry namespace (the required skill_id publish prefix). Enterprise tier. Full tool reference: Private Registry.

// Tool: private_registry_manage
// Parameters:
{
  "action": "list",  // list | get | install | deprecate | undeprecate |
                      // namespace | submissions | approve | reject
  "skillId": "author/name"  // required for most actions
}

Example prompts:

• "Ask Skillsmith to list pending submissions in the private registry"
• "Use Skillsmith to approve my-org/deploy-helper version 1.0.0"

Local Namespace-Collision Audit Tools

These tools detect and resolve namespace collisions across your local skills, commands, agents, and CLAUDE.md files, plus the durable undo mechanism and the separate manifest-identity-repair tool that round out the apply family. skill_inventory_audit, apply_namespace_rename, and apply_recommended_edit are all available on every tier today — Team/Enterprise tier-gating for these tools is not yet enforced. undo_apply and apply_manifest_reconcile are Community tier.

skill_inventory_audit

Audit every installed AI coding client's skill inventory (Claude Code, Cursor, Copilot, and every other Skillsmith-supported client) — plus Claude Code's own commands, agents, and CLAUDE.md trigger rules — for local namespace collisions; returns rename and edit suggestions.

// Tool: skill_inventory_audit
// Parameters:
{
  "audit_mode": "preventative"  // optional: preventative | power_user | governance | off
                                // defaults to ~/.skillsmith/config.json or tier default
}

Four pass-modes control depth and ONNX cost:

• preventative (default for Free/Individual) — exact-name collisions + generic-token flags. No ONNX model load.
• power_user (default for Team) — adds semantic-overlap pass via OverlapDetector.
• governance (default for Enterprise) — same checks as power_user; reserved as the Enterprise default.
• off — short-circuits to an empty result.

Example prompts:

• "Use Skillsmith to audit my installed skills for local namespace collisions"
• "Ask Skillsmith to run a deep collision audit on my ~/.claude inventory"

apply_namespace_rename

Apply a rename suggestion from a prior local namespace-collision audit (skill_inventory_audit); persists overrides via the namespace-overrides ledger.

// Tool: apply_namespace_rename
// Parameters:
{
  "audit_id": "01HXY...",       // ULID from skill_inventory_audit
  "suggestion_id": "rename-1",
  "mode": "apply"               // apply | custom | skip
  // if mode === "custom", also pass: "custom_name": "my-new-name"
}

Example prompts:

• "Use Skillsmith to apply the suggested rename for skill X from the last audit"
• "Ask Skillsmith to skip the rename suggestion for the test-runner collision"

apply_recommended_edit

Apply a recommended prose edit (e.g. add_domain_qualifier) from an audit result; gated behind an allow-list registry.

// Tool: apply_recommended_edit
// Parameters:
{
  "audit_id": "01HXY...",
  "edit_id": "edit-1",
  "confirm": true               // explicit confirmation required
}

Only edits in the APPLY_TEMPLATE_REGISTRY allow-list are accepted. Free-form prose edits are rejected.

Example prompts:

• "Use Skillsmith to apply the suggested domain-qualifier edit to my skill description"

undo_apply

Undo the most recent apply_namespace_rename / apply_recommended_edit changeset(s) made in the current MCP server session, restoring each file from the backup the apply tool wrote before it changed anything.

// Tool: undo_apply
// Parameters:
{
  "count": 1               // optional, defaults to 1 — undo the N most-recent changesets
  // or: "suggestion_id": "rename-1"   // undo one specific changeset by id (mutually exclusive with count)
}

Session-scoped: once the server process restarts, its undo history is gone. Refuses (rather than overwrites) when the file has changed since the apply, the backup is missing, or the restore target falls outside the confined skill roots — treat those as normal, expected outcomes.

Example prompts:

• "Undo the last skill rename you applied"

apply_manifest_reconcile

Repair a corrupted or ambiguous ~/.skillsmith/manifest.json entry through a supported path — never a hand-edit. Use after skill_outdated reports identity-mismatch or local-drift, or after skill_recover_source found low or no confidence.

// Tool: apply_manifest_reconcile
// Parameters:
{
  "action": "mark_local",   // mark_local | relink | drop_entry | verify | revert
  "name": "my-skill"        // required for mark_local/relink/drop_entry; optional for verify (batch) and revert
  // relink also requires: "id": "author/name", "source": "github:author/name"
  // revert accepts either "ledgerEntryId" (precise) or "name" (by most-recent, refuses if ambiguous)
}

Five actions: mark_local stops tracking an entry against the registry (source: 'unknown' + provenance: 'local', written together); relink asserts an explicit, registry-validated id/source pair — it never infers an identity on its own; drop_entry hard-removes an entry whose install path no longer resolves; verify re-checks on-disk content against the registry's current content hash for one entry or, by default, every entry, writing verifiedAt only on a match; revert is a durable, cross-session undo of a prior reconcile on a single entry — unlike undo_apply, it survives an unrelated skill install happening in between and works across server restarts.

Example prompts:

• "skill_outdated says the commit skill's identity doesn't match what's installed — mark it as my own local skill"
• "Undo that last manifest reconcile"

Usage Examples

Discovering Skills

You: "I need help with testing in my project. What skills are available?"

Assistant: [Uses search tool] I found several testing skills:
- jest-helper: Comprehensive Jest testing utilities
- vitest-helper: Vitest integration and helpers
- playwright-utils: End-to-end testing with Playwright
...

Installing and Using Skills

You: "Install the jest-helper skill and show me how to use it"

Assistant: [Uses install_skill tool] I've installed jest-helper to
~/.claude/skills/jest-helper. This skill provides...

Comparing Options

You: "Should I use jest-helper or vitest-helper for my Vite project?"

Assistant: [Uses compare tool] Here's a comparison:
| Feature       | jest-helper | vitest-helper |
| Vite support  | Limited     | Native        |
| Speed         | Moderate    | Fast          |
...

Trust Tiers

Lifecycle Tutorials

The MCP tools listed above bind to natural-language prompts in your agent runtime. The lifecycle tutorials show worked examples of each stage (Claude Code is the worked-example runtime; the same MCP tools work in any MCP-capable agent):

• Discover — search, skill_recommend
• Evaluate — get_skill, skill_compare, skill_diff
• Install & use — install_skill, skill_validate
• Maintain — skill_updates, skill_outdated, skill_inventory_audit
• Govern — skill_audit, compliance_report (Team+), audit_export, audit_query, siem_export (Enterprise)
• Uninstall — uninstall_skill
• Cross-machine skill inventory — view installed skills across devices

Troubleshooting

Server Not Starting

Tools Not Available

Enable Debug Logging

{
  "mcpServers": {
    "skillsmith": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_LOG_LEVEL": "debug"
      }
    }
  }
}