Skip to main content

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

  1. Create a free account (GitHub OAuth)
  2. Visit your CLI Token page to generate a key
  3. 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)

Add the API key directly to your ~/.claude/settings.json:

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

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 1,000 30/min
Individual $9.99/mo 10,000 60/min
Team $25/user/mo 100,000 120/min
Enterprise $55/user/mo Unlimited 300/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.

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

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

Next Steps

Need Help?

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