yusufkaraaslan--skill_seekers/docs/reference/ENVIRONMENT_VARIABLES.md

# Environment Variables Reference - Skill Seekers

> **Version:** 3.7.0  
> **Last Updated:** 2026-02-16  
> **Complete environment variable reference**

---

## Table of Contents

- [Overview](#overview)
- [API Keys](#api-keys)
- [Platform Configuration](#platform-configuration)
- [LLM Provider Selection](#llm-provider-selection)
- [Paths and Directories](#paths-and-directories)
- [Scraping Behavior](#scraping-behavior)
- [Enhancement Settings](#enhancement-settings)
- [GitHub Configuration](#github-configuration)
- [Vector Database Settings](#vector-database-settings)
- [Debug and Development](#debug-and-development)
- [MCP Server Settings](#mcp-server-settings)
- [Examples](#examples)

---

## Overview

Skill Seekers uses environment variables for:
- API authentication (Claude, Gemini, OpenAI, GitHub)
- Configuration paths
- Output directories
- Behavior customization
- Debug settings

Variables are read at runtime and override default settings.

---

## API Keys

### ANTHROPIC_API_KEY

**Purpose:** Claude AI API access for enhancement and upload.

**Format:** `sk-ant-api03-...`

**Used by:**
- `skill-seekers enhance` (API mode)
- `skill-seekers upload` (Claude target)
- AI enhancement features

**Example:**
```bash
export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Alternative:** Use `--api-key` flag per command.

---

### GOOGLE_API_KEY

**Purpose:** Google Gemini API access for upload.

**Format:** `AIza...`

**Used by:**
- `skill-seekers upload` (Gemini target)

**Example:**
```bash
export GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

### OPENAI_API_KEY

**Purpose:** OpenAI (and OpenAI-compatible) API access for enhancement, upload, and embeddings.

**Format:** `sk-...`

**Used by:**
- `skill-seekers create` / `scan` / `enhance` (AI enhancement, API mode)
- `skill-seekers upload` (OpenAI target)
- Embedding generation for vector DBs

**Example:**
```bash
export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

> Combine with `OPENAI_BASE_URL` + `OPENAI_MODEL` to route enhancement through any
> OpenAI-compatible provider (OpenRouter, Groq, Cerebras, Mistral, NVIDIA NIM).
> See [LLM Provider Selection](#llm-provider-selection).

---

### MOONSHOT_API_KEY

**Purpose:** Moonshot AI (Kimi) API access for enhancement (API mode).

**Format:** `sk-...`

**Used by:**
- `skill-seekers create` / `scan` / `enhance` (enhancement, Kimi/Moonshot)

**Example:**
```bash
export MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

### GITHUB_TOKEN

**Purpose:** GitHub API authentication for higher rate limits, plus authoring community-registry submissions.

**Format:** `ghp_...` (personal access token) or `github_pat_...` (fine-grained)

**Used by:**
- `skill-seekers create` (GitHub repos)
- `skill-seekers create --config` (unified multi-source)
- `skill-seekers scan` (local codebases)
- `skill-seekers scan` — *required* to submit AI-generated configs to the community registry (the scan itself runs without it; the publish prompt is just skipped with a hint)

**Benefits:**
- 5000 requests/hour vs 60 for unauthenticated
- Access to private repositories
- Higher GraphQL API limits
- Enables opening community-config GitHub issues from `scan`

**Example:**
```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Create token:** https://github.com/settings/tokens

---

## Platform Configuration

### ANTHROPIC_BASE_URL

**Purpose:** Custom Claude API endpoint.

**Default:** `https://api.anthropic.com`

**Use case:** Proxy servers, enterprise deployments, regional endpoints.

**Example:**
```bash
export ANTHROPIC_BASE_URL=https://custom-api.example.com
```

---

### OPENAI_BASE_URL

**Purpose:** Custom OpenAI-compatible API endpoint for enhancement.

**Default:** `https://api.openai.com/v1`

**Use case:** Any OpenAI-compatible provider — OpenRouter, Groq, Cerebras, Mistral,
NVIDIA NIM, local servers (Ollama, vLLM, LM Studio), proxies.

**Example:**
```bash
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
```

> Read automatically by the OpenAI SDK. Pair with `OPENAI_API_KEY` and `OPENAI_MODEL`.

---

## LLM Provider Selection

The AI **enhancement** step (`create`, `scan`, `enhance`) supports multiple providers
through one abstraction (`AgentClient` — every API enhancement call routes through it).
The provider is chosen by the **first** API key found, in the order of the
`API_PROVIDERS` registry in `cli/agent_client.py`: `ANTHROPIC_API_KEY` →
`ANTHROPIC_AUTH_TOKEN` → `GOOGLE_API_KEY` → `OPENAI_API_KEY` → `MOONSHOT_API_KEY`.
If none is set, it falls back to **LOCAL agent mode** (`--agent`, no API key
required — uses your Claude Pro / ChatGPT Plus subscription).

To force a provider when the key prefix is ambiguous (Moonshot keys also start
with `sk-`), set `SKILL_SEEKER_PROVIDER` to `anthropic`, `google`, `openai`,
`moonshot` (alias: `kimi`):

```bash
export SKILL_SEEKER_PROVIDER=moonshot
```

### Any OpenAI-compatible provider (OpenRouter, Groq, Cerebras, Mistral, NVIDIA NIM)

```bash
export OPENAI_API_KEY="<provider key>"
export OPENAI_BASE_URL="https://api.groq.com/openai/v1"   # provider endpoint
export OPENAI_MODEL="llama-3.3-70b-versatile"             # a model that provider offers
skill-seekers create <source>
```

| Provider     | `OPENAI_BASE_URL`                     |
|--------------|---------------------------------------|
| OpenRouter   | `https://openrouter.ai/api/v1`        |
| Groq         | `https://api.groq.com/openai/v1`      |
| Cerebras     | `https://api.cerebras.ai/v1`          |
| Mistral      | `https://api.mistral.ai/v1`           |
| NVIDIA NIM   | `https://integrate.api.nvidia.com/v1` |

> Set `OPENAI_MODEL` — the OpenAI default (`gpt-4o`) won't exist on other providers.
> Ensure no higher-priority key (e.g. `ANTHROPIC_API_KEY`) is set, or it wins.

### Subscriptions instead of API credits (LOCAL mode)

```bash
skill-seekers create <source> --agent codex    # ChatGPT Plus via Codex CLI
skill-seekers create <source> --agent claude   # Claude Pro/Max via Claude Code
```

---

## Paths and Directories

### SKILL_SEEKERS_HOME

**Purpose:** Base directory for Skill Seekers data.

**Default:**
- Linux/macOS: `~/.config/skill-seekers/`
- Windows: `%APPDATA%\skill-seekers\`

**Used for:**
- Configuration files
- Workflow presets
- Cache data
- Checkpoints

**Example:**
```bash
export SKILL_SEEKERS_HOME=/opt/skill-seekers
```

---

### SKILL_SEEKERS_OUTPUT

**Purpose:** Default output directory for skills.

**Default:** `./output/`

**Used by:**
- All scraping commands
- Package output
- Skill generation

**Example:**
```bash
export SKILL_SEEKERS_OUTPUT=/var/skills/output
```

---

### SKILL_SEEKERS_CONFIG_DIR

**Purpose:** Directory containing preset configs.

**Default:** `configs/` (relative to working directory)

**Example:**
```bash
export SKILL_SEEKERS_CONFIG_DIR=/etc/skill-seekers/configs
```

---

## Scraping Behavior

### SKILL_SEEKERS_RATE_LIMIT

**Purpose:** Default rate limit for HTTP requests.

**Default:** `0.5` (seconds)

**Unit:** Seconds between requests

**Example:**
```bash
# More aggressive (faster)
export SKILL_SEEKERS_RATE_LIMIT=0.2

# More conservative (slower)
export SKILL_SEEKERS_RATE_LIMIT=1.0
```

**Override:** Use `--rate-limit` flag per command.

---

### SKILL_SEEKERS_MAX_PAGES

**Purpose:** Default maximum pages to scrape.

**Default:** `500`

**Example:**
```bash
export SKILL_SEEKERS_MAX_PAGES=1000
```

**Override:** Use `--max-pages` flag or config file.

---

### SKILL_SEEKERS_WORKERS

**Purpose:** Default number of parallel workers.

**Default:** `1`

**Maximum:** `10`

**Example:**
```bash
export SKILL_SEEKERS_WORKERS=4
```

**Override:** Use `--workers` flag.

---

### SKILL_SEEKERS_TIMEOUT

**Purpose:** HTTP request timeout.

**Default:** `30` (seconds)

**Example:**
```bash
# For slow servers
export SKILL_SEEKERS_TIMEOUT=60
```

---

### SKILL_SEEKERS_USER_AGENT

**Purpose:** Custom User-Agent header.

**Default:** `Skill-Seekers/3.7.0`

**Example:**
```bash
export SKILL_SEEKERS_USER_AGENT="MyBot/1.0 (contact@example.com)"
```

---

## Enhancement Settings

### SKILL_SEEKER_AGENT

**Purpose:** Default local coding agent for enhancement and scan detection/generation.

**Default:** `claude`

**Options:** `claude`, `codex`, `copilot`, `opencode`, `kimi`, `custom`, plus IDE-mode aliases (`cursor`, `windsurf`, `cline`, `continue`)

**Used by:**
- `skill-seekers enhance`
- `skill-seekers scan` (overridable per-invocation via `--agent`)

**Example:**
```bash
export SKILL_SEEKER_AGENT=cursor
```

---

### SKILL_SEEKER_AGENT_CMD

**Purpose:** Custom CLI command template for `--agent custom` (LOCAL mode).

**Used by:** `skill-seekers create` / `scan` / `enhance` when `SKILL_SEEKER_AGENT=custom`.

**Example:**
```bash
export SKILL_SEEKER_AGENT=custom
export SKILL_SEEKER_AGENT_CMD="my-llm-cli --prompt-file {prompt_file}"
```

---

### SKILL_SEEKER_PROVIDER

**Purpose:** Force the API provider when key-prefix detection is ambiguous
(Moonshot keys also start with `sk-` and would otherwise be classified as OpenAI).

**Values:** `anthropic`, `google`, `openai`, `moonshot` (alias: `kimi`)

**Example:**
```bash
export SKILL_SEEKER_PROVIDER=moonshot
```

---

### SKILL_SEEKER_MODEL

**Purpose:** Global model override for API-mode enhancement (wins over all
per-provider model vars below).

**Example:**
```bash
export SKILL_SEEKER_MODEL=llama-3.3-70b-versatile
```

---

### Per-provider model overrides

Used only when `SKILL_SEEKER_MODEL` is unset. Each falls back to a per-provider default.

| Variable          | Provider           | Default (if unset)          |
|-------------------|--------------------|-----------------------------|
| `ANTHROPIC_MODEL` | Anthropic          | `claude-sonnet-4-20250514`  |
| `OPENAI_MODEL`    | OpenAI/-compatible | `gpt-4o`                    |
| `GOOGLE_MODEL`    | Gemini             | `gemini-2.0-flash`          |
| `MOONSHOT_MODEL`  | Moonshot/Kimi      | `moonshot-v1-auto`          |

```bash
export OPENAI_MODEL=llama-3.3-70b-versatile
```

---

### SKILL_SEEKER_ENHANCE_TIMEOUT

**Purpose:** Timeout for AI enhancement operations (seconds).

**Default:** `2700` (45 minutes)

**Special values:** `unlimited`, `none`, or `0` map to a 24-hour ceiling.

**Example:**
```bash
# For large skills
export SKILL_SEEKER_ENHANCE_TIMEOUT=3600

# No practical limit
export SKILL_SEEKER_ENHANCE_TIMEOUT=unlimited
```

---

### SKILL_SEEKER_ENHANCE_ACTIVE

**Purpose:** Recursion guard for LOCAL agent enhancement. Skill Seekers sets
this to `1` in the environment of every local agent it spawns (all spawn
paths); when it is already set, LOCAL enhancement refuses to spawn a nested
agent. You normally never set this yourself — only when wrapping Skill Seekers
inside another agent and you want enhancement suppressed.

**Example:**
```bash
export SKILL_SEEKER_ENHANCE_ACTIVE=1   # suppress nested local-agent spawns
```

---

## GitHub Configuration

### GITHUB_API_URL

**Purpose:** Custom GitHub API endpoint.

**Default:** `https://api.github.com`

**Use case:** GitHub Enterprise Server.

**Example:**
```bash
export GITHUB_API_URL=https://github.company.com/api/v3
```

---

### GITHUB_ENTERPRISE_TOKEN

**Purpose:** Separate token for GitHub Enterprise.

**Use case:** Different tokens for github.com vs enterprise.

**Example:**
```bash
export GITHUB_TOKEN=ghp_...           # github.com
export GITHUB_ENTERPRISE_TOKEN=...   # enterprise
```

---

## Vector Database Settings

### CHROMA_URL

**Purpose:** ChromaDB server URL.

**Default:** `http://localhost:8000`

**Used by:**
- `skill-seekers upload --target chroma`
- `export_to_chroma` MCP tool

**Example:**
```bash
export CHROMA_URL=http://chroma.example.com:8000
```

---

### CHROMA_PERSIST_DIRECTORY

**Purpose:** Local directory for ChromaDB persistence.

**Default:** `./chroma_db/`

**Example:**
```bash
export CHROMA_PERSIST_DIRECTORY=/var/lib/chroma
```

---

### WEAVIATE_URL

**Purpose:** Weaviate server URL.

**Default:** `http://localhost:8080`

**Used by:**
- `skill-seekers upload --target weaviate`
- `export_to_weaviate` MCP tool

**Example:**
```bash
export WEAVIATE_URL=https://weaviate.example.com
```

---

### WEAVIATE_API_KEY

**Purpose:** Weaviate API key for authentication.

**Used by:**
- Weaviate Cloud
- Authenticated Weaviate instances

**Example:**
```bash
export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

---

### QDRANT_URL

**Purpose:** Qdrant server URL.

**Default:** `http://localhost:6333`

**Example:**
```bash
export QDRANT_URL=http://qdrant.example.com:6333
```

---

### QDRANT_API_KEY

**Purpose:** Qdrant API key for authentication.

**Example:**
```bash
export QDRANT_API_KEY=xxxxxxxxxxxxxxxx
```

---

## Debug and Development

### SKILL_SEEKERS_DEBUG

**Purpose:** Enable debug logging.

**Values:** `1`, `true`, `yes`

**Equivalent to:** `--verbose` flag

**Example:**
```bash
export SKILL_SEEKERS_DEBUG=1
```

---

### SKILL_SEEKERS_LOG_LEVEL

**Purpose:** Set logging level.

**Default:** `INFO`

**Options:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

**Example:**
```bash
export SKILL_SEEKERS_LOG_LEVEL=DEBUG
```

---

### SKILL_SEEKERS_LOG_FILE

**Purpose:** Log to file instead of stdout.

**Example:**
```bash
export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log
```

---

### SKILL_SEEKERS_CACHE_DIR

**Purpose:** Custom cache directory.

**Default:** `~/.cache/skill-seekers/`

**Example:**
```bash
export SKILL_SEEKERS_CACHE_DIR=/tmp/skill-seekers-cache
```

---

### SKILL_SEEKERS_NO_CACHE

**Purpose:** Disable caching.

**Values:** `1`, `true`, `yes`

**Example:**
```bash
export SKILL_SEEKERS_NO_CACHE=1
```

---

## MCP Server Settings

### MCP_TRANSPORT

**Purpose:** Default MCP transport mode.

**Default:** `stdio`

**Options:** `stdio`, `http`

**Example:**
```bash
export MCP_TRANSPORT=http
```

**Override:** Use `--transport` flag.

---

### MCP_PORT

**Purpose:** Default MCP HTTP port.

**Default:** `8765`

**Example:**
```bash
export MCP_PORT=8080
```

**Override:** Use `--port` flag.

---

### MCP_HOST

**Purpose:** Default MCP HTTP host.

**Default:** `127.0.0.1`

**Example:**
```bash
export MCP_HOST=0.0.0.0
```

**Override:** Use `--host` flag.

---

## Examples

### Development Environment

```bash
# Debug mode
export SKILL_SEEKERS_DEBUG=1
export SKILL_SEEKERS_LOG_LEVEL=DEBUG

# Custom paths
export SKILL_SEEKERS_HOME=./.skill-seekers
export SKILL_SEEKERS_OUTPUT=./output

# Faster scraping for testing
export SKILL_SEEKERS_RATE_LIMIT=0.1
export SKILL_SEEKERS_MAX_PAGES=50
```

### Production Environment

```bash
# API keys
export ANTHROPIC_API_KEY=sk-ant-...
export GITHUB_TOKEN=ghp_...

# Custom output directory
export SKILL_SEEKERS_OUTPUT=/var/www/skills

# Conservative scraping
export SKILL_SEEKERS_RATE_LIMIT=1.0
export SKILL_SEEKERS_WORKERS=2

# Logging
export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log
export SKILL_SEEKERS_LOG_LEVEL=WARNING
```

### CI/CD Environment

```bash
# Non-interactive
export SKILL_SEEKERS_LOG_LEVEL=ERROR

# API keys from secrets
export ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY_SECRET}
export GITHUB_TOKEN=${GITHUB_TOKEN_SECRET}

# Fresh runs (no cache)
export SKILL_SEEKERS_NO_CACHE=1
```

### Multi-Platform Setup

```bash
# All API keys
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
export OPENAI_API_KEY=sk-...
export GITHUB_TOKEN=ghp_...

# Vector databases
export CHROMA_URL=http://localhost:8000
export WEAVIATE_URL=http://localhost:8080
export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

---

## Configuration File

Environment variables can also be set in a `.env` file:

```bash
# .env file
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
SKILL_SEEKERS_OUTPUT=./output
SKILL_SEEKERS_RATE_LIMIT=0.5
```

Load with:
```bash
# Automatically loaded if python-dotenv is installed
# Or manually:
export $(cat .env | xargs)
```

---

## Priority Order

Settings are applied in this order (later overrides earlier):

1. Default values
2. Environment variables
3. Configuration file
4. Command-line flags

Example:
```bash
# Default: rate_limit = 0.5
export SKILL_SEEKERS_RATE_LIMIT=1.0  # Env var overrides default
# Config file: rate_limit = 0.2      # Config overrides env
skill-seekers create --rate-limit 2.0  # Flag overrides all
```

---

## Security Best Practices

### Never commit API keys

```bash
# Add to .gitignore
echo ".env" >> .gitignore
echo "*.key" >> .gitignore
```

### Use secret management

```bash
# macOS Keychain
export ANTHROPIC_API_KEY=$(security find-generic-password -s "anthropic-api" -w)

# Linux Secret Service (with secret-tool)
export ANTHROPIC_API_KEY=$(secret-tool lookup service anthropic)

# 1Password CLI
export ANTHROPIC_API_KEY=$(op read "op://vault/anthropic/credential")
```

### File permissions

```bash
# Restrict .env file
chmod 600 .env
```

---

## Troubleshooting

### Variable not recognized

```bash
# Check if set
echo $ANTHROPIC_API_KEY

# Check in Python
python -c "import os; print(os.getenv('ANTHROPIC_API_KEY'))"
```

### Priority issues

```bash
# See effective configuration
skill-seekers config --show
```

### Path expansion

```bash
# Use full path or expand tilde
export SKILL_SEEKERS_HOME=$HOME/.skill-seekers
# NOT: ~/.skill-seekers (may not expand in all shells)
```

---

## See Also

- [CLI Reference](CLI_REFERENCE.md) - Command reference
- [Config Format](CONFIG_FORMAT.md) - JSON configuration

---

*For platform-specific setup, see [Installation Guide](../getting-started/01-installation.md)*