Configuration Guide

New here?

Start with the 5-Minute Setup to get Skillsmith running quickly, then come back here to configure API keys and advanced options.

Configure API keys, verify your installation, and troubleshoot common issues.

Verify Installation

MCP Server Verification

Ask your assistant to verify the Skillsmith server is running:

"List available MCP tools"
# You should see skillsmith tools like search, install, recommend

CLI Verification

Check the CLI is installed correctly:

skillsmith --version
# Output: @skillsmith/cli v0.8.x

skillsmith --help
# Shows available commands

API Key Configuration

The MCP server works out of the box without configuration, providing community-tier access (30 requests/minute). For higher rate limits and usage tracking on your account dashboard, configure your personal API key.

Why Configure an API Key?

Without a personal API key, the MCP server uses a shared anonymous key. Your requests will work but won't appear on your Account Dashboard. To track usage and get tier-based rate limits, add your API key to the MCP server configuration.

Get and Configure Your API Key

Option 1: CLI Login (Recommended — one command)

npm install -g @skillsmith/cli
skillsmith login

This opens www.skillsmith.app/account/cli-token in your browser. Generate a key, copy it, and paste it when prompted. The key is stored securely in your OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Store).

For CI/headless environments, use SKILLSMITH_API_KEY as an environment variable instead.

Option 2: Manual Config File

Create a free account (GitHub OAuth)
Visit your CLI Token page to generate a key
Create ~/.skillsmith/config.json:

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

Option 3: MCP Client Settings (MCP server only)

Skillsmith is MCP-compatible — pick the snippet for your agent. Every snippet uses the same shape; the only differences are the config-file path and (for Codex/Hermes) the format.

Claude Code — ~/.claude/settings.json

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

Cursor — ~/.cursor/mcp.json

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

Cursor 2.4+ required, Node >=22.22 (Cursor's own bundled Node meets this). Setup: run npm install -g @skillsmith/mcp-server, then run which skillsmith-mcp (macOS/Linux) or where skillsmith-mcp (Windows) and paste that path into command above — Cursor's bundled Node cannot resolve packages via npx (a real ENOENT on a missing Resources/app/resources/lib directory), so pointing directly at the installed binary is the only form confirmed to work inside Cursor. SKILLSMITH_CLIENT routes installs to ~/.cursor/skills instead of the default ~/.claude/skills. Prefer to try npx first anyway? Replace command with "npx" and add "args": ["-y", "@skillsmith/mcp-server"] — simpler, but may hit the same ENOENT, plus EBADENGINE or ENOTEMPTY on repeated installs. After saving: enable the server in Cursor's Settings → MCP panel and start a new chat — a correctly-configured entry still shows disconnected until toggled on there — then reload the window.

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

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

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/mcp-server": {
      "command": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_API_KEY": "${env:SKILLSMITH_API_KEY}"
      }
    }
  }
}

Supports ${env:VAR} interpolation for secrets in this config.

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

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

[mcp_servers.@skillsmith/mcp-server.env]
SKILLSMITH_API_KEY = "sk_live_your_key_here"

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

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

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

OpenCode — ~/.config/opencode/opencode.json

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

OpenCode also reads .claude/skills and .agents/skills for skill discovery. Note the OpenCode-specific entry shape: command is an array and the env-var field is named environment, not env.

Hermes (Nous Research) — ~/.hermes/config.yaml (YAML)

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

Hermes config is YAML. Hermes has no SessionStart hook equivalent — nudge/attribution is unsupported on this harness.

Grok Build (xAI) — ~/.grok/config.toml (TOML)

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

[mcp_servers.@skillsmith/mcp-server.env]
SKILLSMITH_API_KEY = "sk_live_your_key_here"

Grok Build uses TOML under a [mcp_servers.NAME] table, the same convention as Codex CLI above.

Google Antigravity — ~/.gemini/config/mcp_config.json

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

One config file is shared across the Antigravity CLI, IDE, and 2.0. A workspace-scoped alternative also exists at .agents/mcp_config.json (project root) if you prefer not to register the server globally. SKILLSMITH_CLIENT routes installs to ~/.gemini/config/skills instead of the default ~/.claude/skills.

Shell Exports Don't Work

Running export SKILLSMITH_API_KEY=... in your terminal does NOT pass the variable to MCP servers. MCP servers run as subprocesses and don't inherit your shell environment. Use one of the methods above instead.

Rate Limits by Tier

Tier	Price	Requests/Month	Rate Limit
Trial (no account)	Free	10 total	10/min
Community	Free	100	100/min
Individual	$9.99/mo	1,000	200/min
Team	$25/user/mo	10,000	300/min
Enterprise	Custom	Unlimited	600/min

Rate limits are per-minute and reset automatically. See Pricing for full details.

Understanding Skill IDs

Skills are identified by their full ID in the format author/name:

ID Format	Example	Description
`author/name`	`community/jest-helper`	Full skill identifier
`name`	`jest-helper`	Short form (searches all authors)

Troubleshooting

"skillsmith: command not found"

The CLI isn't installed globally or isn't in your PATH.

# Reinstall globally
npm install -g @skillsmith/cli

# Or use npx instead
npx @skillsmith/cli search testing

My AI agent doesn't show Skillsmith tools

The MCP server isn't configured for your client, or your agent needs to restart.

Verify your MCP client's config file (see Option 3 above for the exact path and format) has the skillsmith configuration
Restart your agent completely (quit and reopen)
Ask your agent: "List available MCP tools"

"Permission denied" when installing skills

The skills directory doesn't exist or has wrong permissions.

# Create the directory with correct permissions
mkdir -p ~/.claude/skills
chmod 755 ~/.claude/skills

Skills installed but not showing in Claude Code

Claude Code may need to refresh its skill cache.

Verify skills are in ~/.claude/skills/
Start a new Claude Code session
Skills should appear automatically

Next Steps

CLI Reference - Learn all CLI commands
MCP Server - Configure advanced server options
Skill Authoring - Create your own skills
API Reference - Build integrations with the Skillsmith API

Need Help?

If you encounter any issues during setup, check out our GitHub Issues.