adding-env-variables

Q: How do I install adding-env-variables?

Run npx skills add https://github.com/inkeep/agents --skill adding-env-variables in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/adding-env-variables/ (personal) or .claude/skills/adding-env-variables/ (project).

by inkeepCode Quality & Workflow

Guide for adding new environment variables to the codebase. Ensures env.ts schemas include descriptions and .env.example is kept in sync. Triggers on: add env variable, new environment variable, env.ts change, add config variable, INKEEP, adding to .env.

Installs: 50
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/inkeep/agents --skill adding-env-variables

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads adding-env-variables automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Adding Environment Variables Guide

Comprehensive guidance for adding new environment variables to the Inkeep Agent Framework. This ensures consistency, documentation, and type safety across all packages.

CI Enforcement

Environment variable descriptions are enforced by CI. The check:env-descriptions script runs in CI and will fail if any variables in env.ts files are missing .describe() calls.

Run locally to check:

pnpm check:env-descriptions

Environment Architecture

The framework uses environment variables defined in multiple env.ts files:

Package	File	Purpose
agents-api	`agents-api/src/env.ts`	Main API server configuration
agents-core	`packages/agents-core/src/env.ts`	Shared core configuration
agents-cli	`agents-cli/src/env.ts`	CLI tool configuration

Note: The following files are auto-generated and should NOT be edited:

packages/agents-mcp/src/lib/env.ts (Generated by Speakeasy)

Required Steps for Adding Environment Variables

Step 1: Add to `.env.example`

Location: .env.example (root of repository)

Add the variable with a descriptive comment:

# ============ SECTION NAME ============
# Description of what this variable does
# Additional context if needed (e.g., where to get API keys)
MY_NEW_VARIABLE=default-value-or-empty

Example:

# ============ AI PROVIDERS ============
# Required for agent execution
# Get your API keys from:
# Anthropic: https://console.anthropic.com/
# OpenAI: https://platform.openai.com/
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

Step 2: Add to Relevant `env.ts` File(s)

Add the variable to the Zod schema with a .describe() call that matches the .env.example comment:

const envSchema = z.object({
  // ... existing variables ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('Description of what this variable does'),
});

Step 3: Description Requirements

Every environment variable MUST have a .describe() call with a clear, concise description that:

Explains what the variable is used for
Matches the comment in .env.example
Includes helpful context (e.g., where to get API keys, default behavior)

Examples of good descriptions:

// AI Provider keys
ANTHROPIC_API_KEY: z
  .string()
  .describe('Anthropic API key for Claude models (required for agent execution). Get from https://console.anthropic.com/'),

// Database configuration
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('PostgreSQL connection URL for the management database (Doltgres with Git version control)'),

// Authentication
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('Secret key for Better Auth session encryption (change in production)'),

// Feature flags
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable Langfuse LLM observability (set to "true" to enable)'),

Zod Schema Patterns

Required Variables

MY_REQUIRED_VAR: z
  .string()
  .describe('This variable is required for the application to function'),

Optional Variables

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('Optional configuration for feature X'),

Variables with Defaults

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('Configuration with a sensible default'),

Enum Variables

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('Logging verbosity level'),

Numeric Variables

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('Maximum number of connections in the pool'),

Boolean Variables (as strings)

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable feature X (set to "true" to enable)'),

Variables with Validation

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET must be at least 32 characters')
  .optional()
  .describe('Secret key for signing JWT tokens (minimum 32 characters)'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: 'Invalid email address',
  })
  .describe('Admin email address for notifications'),

Category Organization

Group related variables with comments in both .env.example and env.ts:

In `.env.example`:

# ============ DATABASE ============
INKEEP_AGENTS_MANAGE_DATABASE_URL=...
INKEEP_AGENTS_RUN_DATABASE_URL=...

# ============ AI PROVIDERS ============
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

In `env.ts`:

const envSchema = z.object({
  // Database
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the management database'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the runtime database'),

  // AI Providers
  ANTHROPIC_API_KEY: z
    .string()
    .describe('Anthropic API key for Claude models'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('OpenAI API key for GPT models'),
});

Which `env.ts` File to Use?

Choose the appropriate file based on where the variable is used:

Use Case	File
API server configuration	`agents-api/src/env.ts`
Shared across packages	`packages/agents-core/src/env.ts`
CLI-specific	`agents-cli/src/env.ts`
Multiple packages	Add to `agents-core` and import where needed

Checklist for Adding Environment Variables

Before completing any environment variable addition, verify:

Common Mistakes to Avoid

Missing .describe() call - Every variable needs a description (CI will fail!)
Inconsistent descriptions - Keep .env.example and .describe() in sync
Wrong file - Add to the package that actually uses the variable
Missing validation - Add constraints for sensitive values (min length for secrets, email validation, etc.)
Editing auto-generated files - Never edit agents-mcp env files

FAQ

What does the adding-env-variables skill do?

How do I install adding-env-variables?

Run npx skills add https://github.com/inkeep/agents --skill adding-env-variables in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/adding-env-variables/ (personal) or .claude/skills/adding-env-variables/ (project).

Which AI agents can use adding-env-variables?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is adding-env-variables safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains adding-env-variables?

It is published by inkeep in inkeep/agents. It has 50 recorded installs.

More from inkeep/agents

View all →

api-logging-guidelines

inkeep/agents

Open the skill to read its SKILL.md instructions.

Backend & APIs52 installs

data-model-changes

inkeep/agents

Guide for making changes to the database schema, validation, types, and data access layer. Use when adding tables, columns, relations, or modifying the data model. Triggers on: add table, add column, modify schema, database change, data model, new entity, schema migration.

Data & Databases49 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

adding-env-variables

Install

Install

Describe the task

Review the result

SKILL.md

Adding Environment Variables Guide

CI Enforcement

Environment Architecture

Required Steps for Adding Environment Variables

Step 1: Add to .env.example

Step 2: Add to Relevant env.ts File(s)

Step 3: Description Requirements

Zod Schema Patterns

Required Variables

Optional Variables

Variables with Defaults

Enum Variables

Numeric Variables

Boolean Variables (as strings)

Variables with Validation

Category Organization

In .env.example:

In env.ts:

Which env.ts File to Use?

Checklist for Adding Environment Variables

Common Mistakes to Avoid

FAQ

More from inkeep/agents

Popular code quality & workflow skills

Step 1: Add to `.env.example`

Step 2: Add to Relevant `env.ts` File(s)

In `.env.example`:

In `env.ts`:

Which `env.ts` File to Use?