# Skills CLI Environment Variables: Complete Configuration Guide

> Master the Skills CLI environment variables for authentication, endpoints, and agent config. Explore 16+ variables to optimize your workflow in this complete guide.

- Repository: [Vercel Labs/skills](https://github.com/vercel-labs/skills)
- Tags: how-to-guide
- Published: 2026-04-23

---

**The Skills CLI supports 16+ environment variables spanning authentication, API endpoints, telemetry control, CI detection, and agent configuration.**

The `vercel-labs/skills` repository provides a CLI tool for discovering and installing reusable skills for AI agents. Understanding its environment variable configuration is essential for customizing behavior in development, CI/CD pipelines, and enterprise deployments.

## Authentication Variables

### GitHub Token Support

The CLI recognizes two environment variables for GitHub API authentication:

| Variable | Purpose |
|----------|---------|
| `GITHUB_TOKEN` | Primary GitHub personal access token |
| `GH_TOKEN` | Alternative token variable (common CLI convention) |

These tokens authenticate API calls when fetching skill folder hashes. According to the source code in [`src/skill-lock.ts`](https://github.com/vercel-labs/skills/blob/main/src/skill-lock.ts) (lines 137-141), the CLI checks both variables to support different user workflows.

```bash

# Set GitHub token for authenticated API access

export GITHUB_TOKEN="ghp_your_token_here"

# Or use the alternative variable

export GH_TOKEN="ghp_your_token_here"

```

## API Endpoint Configuration

### Custom Skills API URL

The `SKILLS_API_URL` variable overrides the base URL for the skills search API endpoint (`/api/search`). By default, this points to `https://skills.sh`.

In [`src/find.ts`](https://github.com/vercel-labs/skills/blob/main/src/find.ts) (lines 15-17), the implementation reads:

```typescript
const SKILLS_API_URL = process.env.SKILLS_API_URL || "https://skills.sh";

```

```bash

# Point to a self-hosted or enterprise skills instance

export SKILLS_API_URL="https://skills.company.internal"

```

### Custom Download URL

The `SKILLS_DOWNLOAD_URL` variable controls where raw skill files are fetched from. This defaults to `https://skills.sh` but can be configured independently of the API URL.

The source in [`src/blob.ts`](https://github.com/vercel-labs/skills/blob/main/src/blob.ts) (lines 44-46) shows:

```typescript
const SKILLS_DOWNLOAD_URL = process.env.SKILLS_DOWNLOAD_URL || "https://skills.sh";

```

```bash

# Use CDN for downloads while keeping API on primary domain

export SKILLS_DOWNLOAD_URL="https://cdn.skills.sh"

```

## Path and File Location Variables

### XDG State Home Override

The `XDG_STATE_HOME` variable follows the XDG Base Directory Specification to customize where state files are stored. Specifically, this affects the global lock file location.

According to [`src/skill-lock.ts`](https://github.com/vercel-labs/skills/blob/main/src/skill-lock.ts) (lines 67-75) and [`src/cli.ts`](https://github.com/vercel-labs/skills/blob/main/src/cli.ts) (lines 311-316), the lock file path resolves as:

```typescript
const lockDir = process.env.XDG_STATE_HOME 
  ? path.join(process.env.XDG_STATE_HOME, "agents") 
  : path.join(os.homedir(), ".agents");

```

```bash

# Store state in XDG-compliant location

export XDG_STATE_HOME="$HOME/.local/state"

# Results in lock file at: ~/.local/state/agents/.skill-lock.json

```

## Agent Configuration Directories

The CLI supports custom installation directories for two agent frameworks:

| Variable | Agent | Default Behavior |
|----------|-------|----------------|
| `CODEX_HOME` | OpenAI Codex | Uses system default configuration path |
| `CLAUDE_CONFIG_DIR` | Anthropic Claude | Uses system default configuration path |

In [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts) (lines 10-11), these are read directly:

```typescript
const CODEX_HOME = process.env.CODEX_HOME;
const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR;

```

```bash

# Custom Codex installation location

export CODEX_HOME="$HOME/.config/codex-custom"

# Custom Claude configuration directory

export CLAUDE_CONFIG_DIR="$HOME/.config/claude-enterprise"

```

## Internal and Development Features

### Install Internal Skills

The `INSTALL_INTERNAL_SKILLS` variable controls whether hidden or internal skills appear in search results and installation. This is primarily used for development and testing.

In [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts) (lines 14-17), the logic evaluates:

```typescript
const installInternal = ["1", "true"].includes(
  process.env.INSTALL_INTERNAL_SKILLS?.toLowerCase() || ""
);

```

```bash

# Enable internal skill installation

export INSTALL_INTERNAL_SKILLS="1"

# Alternative value

export INSTALL_INTERNAL_SKILLS="true"

```

## Telemetry and Privacy Controls

### CI Environment Detection

The CLI automatically detects when running in continuous integration environments using multiple standard variables:

| Variable | Platform |
|----------|----------|
| `CI` | Generic CI indicator |
| `GITHUB_ACTIONS` | GitHub Actions |
| `GITLAB_CI` | GitLab CI |
| `CIRCLECI` | CircleCI |
| `TRAVIS` | Travis CI |
| `BUILDKITE` | Buildkite |
| `JENKINS_URL` | Jenkins |
| `TEAMCITY_VERSION` | TeamCity |

In [`src/telemetry.ts`](https://github.com/vercel-labs/skills/blob/main/src/telemetry.ts) (lines 60-70), detection occurs:

```typescript
const ciEnvVars = [
  "CI", "GITHUB_ACTIONS", "GITLAB_CI", "CIRCLECI",
  "TRAVIS", "BUILDKITE", "JENKINS_URL", "TEAMCITY_VERSION"
];
const isCI = ciEnvVars.some(v => process.env[v]);

```

### Disable Telemetry

Two variables completely disable telemetry reporting:

| Variable | Behavior |
|----------|----------|
| `DISABLE_TELEMETRY` | Explicit opt-out for Skills CLI |
| `DO_NOT_TRACK` | Industry-standard privacy signal |

According to [`src/telemetry.ts`](https://github.com/vercel-labs/skills/blob/main/src/telemetry.ts) (lines 73-75):

```typescript
const telemetryDisabled = 
  Boolean(process.env.DISABLE_TELEMETRY) || 
  Boolean(process.env.DO_NOT_TRACK);

```

```bash

# Disable all telemetry

export DISABLE_TELEMETRY="1"

# Or use the standard privacy variable

export DO_NOT_TRACK="1"

```

## Summary

- **Skills CLI environment variables** cover authentication, API endpoints, file paths, agent configuration, and telemetry control
- **GitHub authentication** uses `GITHUB_TOKEN` or `GH_TOKEN` for API access
- **API customization** via `SKILLS_API_URL` and `SKILLS_DOWNLOAD_URL` enables self-hosted deployments
- **Path overrides** with `XDG_STATE_HOME` follow XDG specifications for lock file placement
- **Agent directories** configure custom paths for Codex (`CODEX_HOME`) and Claude (`CLAUDE_CONFIG_DIR`)
- **CI detection** automatically identifies 8+ common CI platforms for appropriate telemetry handling
- **Privacy controls** through `DISABLE_TELEMETRY` and `DO_NOT_TRACK` completely disable usage reporting

## Frequently Asked Questions

### How do I configure Skills CLI for a private enterprise instance?

Set both `SKILLS_API_URL` and `SKILLS_DOWNLOAD_URL` to your internal domain. For authenticated access to private repositories, also configure `GITHUB_TOKEN` with appropriate scopes. The CLI reads these in [`src/find.ts`](https://github.com/vercel-labs/skills/blob/main/src/find.ts) and [`src/blob.ts`](https://github.com/vercel-labs/skills/blob/main/src/blob.ts) respectively.

### What is the difference between DISABLE_TELEMETRY and DO_NOT_TRACK?

Both variables completely disable telemetry reporting when set to any truthy value. `DISABLE_TELEMETRY` is specific to the Skills CLI, while `DO_NOT_TRACK` follows the industry-standard privacy convention. The telemetry module in [`src/telemetry.ts`](https://github.com/vercel-labs/skills/blob/main/src/telemetry.ts) checks both (lines 73-75).

### How does XDG_STATE_HOME affect Skills CLI behavior?

When `XDG_STATE_HOME` is set, the CLI stores its global lock file at `$XDG_STATE_HOME/agents/.skill-lock.json` instead of the default `~/.agents/.skill-lock.json`. This enables compliance with XDG Base Directory specifications as implemented in [`src/skill-lock.ts`](https://github.com/vercel-labs/skills/blob/main/src/skill-lock.ts) (lines 67-75).