Skip to main content
Agent skill

Python Configuration

Python configuration management via environment variables and typed settings. Use when externalizing config, setting up pydantic-settings, managing secrets, or implementing environment-specific behavior.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Python Configuration when an AI agent needs a reusable SKILL.md workflow for this job: Python configuration management via environment variables and typed settings. Use when externalizing config, setting up pydantic-settings, managing secrets, or implementing environment-specific behavior.

When not to use it

Skip Python Configuration when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/python-configuration
# Save SKILL.md to ~/.claude/skills/python-configuration/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/python-configuration/SKILL.md. For a shared project, commit the folder at .claude/skills/python-configuration/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Python Configuration skill for this task: Setting up a new project's configuration system. Confirm any required inputs or files before making changes.

What supports this recommendation?

90/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
100/100
Practical detail
100/100
Source evidence
63/100
Source signals
80/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Python Configuration Management

Externalize configuration from code using environment variables and typed settings. Well-managed configuration enables the same code to run in any environment without modification.

## When to Use This Skill

- Setting up a new project's configuration system - Migrating from hardcoded values to environment variables - Implementing pydantic-settings for typed configuration - Managing secrets and sensitive values - Creating environment-specific settings (dev/staging/prod) - Validating configuration at application startup

## Core Concepts

### 1. Externalized Configuration

All environment-specific values (URLs, secrets, feature flags) come from environment variables, not code.

### 2. Typed Settings

Parse and validate configuration into typed objects at startup, not scattered throughout code.

### 3. Fail Fast

Validate all required configuration at application boot. Missing config should crash immediately with a clear message.

### 4. Sensible Defaults

Provide reasonable defaults for local development while requiring explicit values for sensitive settings.

## Quick Start

```python from pydantic_settings import BaseSettings from pydantic import Field

class Settings(BaseSettings): database_url: str = Field(alias="DATABASE_URL") api_key: str = Field(alias="API_KEY") debug: bool = Field(default=False, alias="DEBUG")

settings = Settings() # Loads from environment ```

## Fundamental Patterns

### Pattern 1: Typed Settings with Pydantic

Create a central settings class that loads and validates all configuration.

```python from pydantic_settings import BaseSettings from pydantic import Field, PostgresDsn, ValidationError import sys

class Settings(BaseSettings): """Application configuration loaded from environment variables."""

# Database db_host: str = Field(alias="DB_HOST") db_port: int = Field(default=5432, alias="DB_PORT") db_name: str = Field(alias="DB_NAME") db_user: str = Field(alias="DB_USER") db_password: str = Field(alias="DB_PASSWORD")

# Redis redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

# API Keys api_secret_key: str = Field(alias="API_SECRET_KEY")

# Feature flags enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

model_config = { "env_file": ".env", "env_file_encoding": "utf-8", }

# Create singleton instance at module load try: settings = Settings() except ValidationError as e: print(f"Configuration error:\n{e}") sys.exit(1) ```

Import `settings` throughout your application:

```python from myapp.config import settings

def get_database_connection(): return connect( host=settings.db_host, port=settings.db_port, database=settings.db_name, ) ```

### Pattern 2: Fail Fast on Missing Configuration

Required settings should crash the application immediately with a clear error.

```python from pydantic_settings import BaseSettings from pydantic import Field, ValidationError import sys

class Settings(BaseSettings): # Required - no default means it must be set api_key: str = Field(alias="API_KEY") database_url: str = Field(alias="DATABASE_URL")

# Optional with defaults log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try: settings = Settings() except ValidationError as e: print("=" * 60) print("CONFIGURATION ERROR") print("=" * 60) for error in e.errors(): field = error["loc"][0] print(f" - {field}: {error['msg']}") print("\nPlease set the required environment variables.") sys.exit(1) ```

A clear error at startup is better than a cryptic `None` failure mid-request.

### Pattern 3: Local Development Defaults

Provide sensible defaults for local development while requiring explicit values for secrets.

```python class Settings(BaseSettings): # Has local default, but prod will override db_host: str = Field(default="localhost", alias="DB_HOST") db_port: int = Field(default=5432, alias="DB_PORT")

# Always required - no default for secrets db_password: str = Field(alias="DB_PASSWORD") api_secret_key: str = Field(alias="API_SECRET_KEY")

# Development convenience debug: bool = Field(default=False, alias="DEBUG")

model_config = {"env_file": ".env"} ```

Create a `.env` file for local development (never commit this):

```bash # .env (add to .gitignore) DB_PASSWORD=local_dev_password API_SECRET_KEY=dev-secret-key DEBUG=true ```

### Pattern 4: Namespaced Environment Variables

Prefix related variables for clarity and easy debugging.

```bash # Database configuration DB_HOST=localhost DB_PORT=5432 DB_NAME=myapp DB_USER=admin DB_PASSWORD=secret

# Redis configuration REDIS_URL=redis://localhost:6379 REDIS_MAX_CONNECTIONS=10

# Authentication AUTH_SECRET_KEY=your-secret-key AUTH_TOKEN_EXPIRY_SECONDS=3600 AUTH_ALGORITHM=HS256

# Feature flags FEATURE_NEW_CHECKOUT=true FEATURE_BETA_UI=false ```

Makes the database settings easy to list for debugging. Print only the names, so no value (such as a password inside a connection URL) reaches your terminal or logs:

```bash env | grep -o '^DB_[A-Za-z0-9_]*' ```

## Detailed worked examples and patterns

Detailed sections (starting with `## Advanced Patterns`) live in `references/details.md`. Read that file when the navigation summary above is insufficient.

## Best Practices Summary

1. **Never hardcode config** - All environment-specific values from env vars 2. **Use typed settings** - Pydantic-settings with validation 3. **Fail fast** - Crash on missing required config at startup 4. **Provide dev defaults** - Make local development easy 5. **Never commit secrets** - Use `.env` files (gitignored) or secret managers 6. **Namespace variables** - `DB_HOST`, `REDIS_URL` for clarity 7. **Import settings singleton** - Don't call `os.getenv()` throughout code 8. **Document all variables** - README should list required env vars 9. **Validate early** - Check config correctness at boot time 10. **Use secrets_dir** - Support mounted secrets in containers

Intended uses

  • Setting up a new project's configuration system
  • Migrating from hardcoded values to environment variables
  • Implementing pydantic-settings for typed configuration
  • Managing secrets and sensitive values
  • Creating environment-specific settings (dev/staging/prod)
  • Validating configuration at application startup

Implementation notes

  • Never hardcode config - All environment-specific values from env vars
  • Use typed settings - Pydantic-settings with validation
  • Fail fast - Crash on missing required config at startup
  • Provide dev defaults - Make local development easy
  • Never commit secrets - Use .env files (gitignored) or secret managers
  • Namespace variables - DBHOST, REDISURL for clarity
  • Import settings singleton - Don't call os.getenv() throughout code
  • Document all variables - README should list required env vars
  • Validate early - Check config correctness at boot time
  • Use secretsdir - Support mounted secrets in containers

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.