Skills CLI Environment Variables: Complete Configuration Guide

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 (lines 137-141), the CLI checks both variables to support different user workflows.

# 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 (lines 15-17), the implementation reads:

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

# 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 (lines 44-46) shows:

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

# 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 (lines 67-75) and src/cli.ts (lines 311-316), the lock file path resolves as:

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

# 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 (lines 10-11), these are read directly:

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

# 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 (lines 14-17), the logic evaluates:

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

# 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 (lines 60-70), detection occurs:

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 (lines 73-75):

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

# 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 and 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 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 (lines 67-75).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}