MCP Server

The Skillsmith MCP server integrates with MCP-compatible clients, enabling natural language skill discovery and 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

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

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

Advanced Configuration

For more control, you can specify additional options:

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

API Key Configuration

The Skillsmith API provides access to 14,000+ curated skills, indexed daily from 20,000+ on 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: Claude Settings

Add to your ~/.claude/settings.json:

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

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"

Namespace Audit Tools (Team+)

These tools detect and resolve namespace collisions across your local skills, commands, agents, and CLAUDE.md files. Available on the Team and Enterprise tiers. Free and Individual receive a typed error if invoked.

skill_inventory_audit

Audit the local ~/.claude/ inventory for 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
}

Three pass-modes control depth and ONNX cost:

• preventative (default for community/individual once unlocked) — 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 as power_user; deeper audit-history retention.
• off — short-circuits to an empty result.

Example prompts:

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

apply_namespace_rename

Apply a rename suggestion from a prior skill_inventory_audit result; 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"

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 (Team+)
• Govern — skill_audit (Team+), audit_export, audit_query, siem_export (Enterprise)
• Retire — uninstall_skill

Troubleshooting

Server Not Starting

Tools Not Available

Enable Debug Logging

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