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 v1.x.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": "npx",
      "args": ["-y", "@skillsmith/mcp-server"],
      "env": {
        "SKILLSMITH_CLIENT": "cursor",
        "SKILLSMITH_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

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 to get the exact path — it is 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 and may hit EBADENGINE (Cursor bundles its own Node, sometimes older than the >=22.22 this package requires) or ENOTEMPTY on repeated installs.

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.

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	$55/user/mo	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

Claude Code doesn't show Skillsmith tools

The MCP server isn't configured or Claude Code needs to restart.

Verify ~/.claude/settings.json has the skillsmith configuration
Restart Claude Code completely (quit and reopen)
Ask Claude: "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.