Detect Environment Variables
Overview
The detect-env-vars skill scans a project directory and builds a complete,
structured inventory of every environment variable in use. It reads from
three independent source types and merges the results:
| Source |
Examples |
What is captured |
| dotenv template |
.env.example, .env.sample, .env.dist |
Variable names, example values, comments, required vs. optional |
| config files |
*.yaml, *.yml, *.toml, *.json, *.ini |
${VAR} / $VAR interpolation references |
| source code |
*.py, *.js, *.ts, *.go, *.rb, *.sh |
os.environ, os.getenv, process.env, os.Getenv, ENV[] calls |
Quick Start
from harness_skills.env_var_detector import detect_env_vars
result = detect_env_vars(".") # scan current directory
print(result.unique_var_names) # sorted, de-duplicated names
print(result.total_vars_found) # total occurrences (not unique)
print(result.dotenv_files_found) # .env.example paths scanned
print(result.source_files_scanned) # number of source files inspected
# Granular scanning
from harness_skills.env_var_detector import (
scan_dotenv_file,
scan_config_file,
scan_source_file,
)
from pathlib import Path
root = Path(".")
# Parse a single .env.example
entries = scan_dotenv_file(Path(".env.example"), root)
for e in entries:
status = "required" if e.required else "optional"
print(f" [{status}] {e.name}={e.default_value} # {e.comment}")
# Extract ${VAR} refs from a YAML config
entries = scan_config_file(Path("config/app.yaml"), root)
# Scan a Python file for os.environ references
entries = scan_source_file(Path("app/settings.py"), root, "python")
Function Reference
detect_env_vars(path, *, skip_dirs, include_config, include_source)
Recursively scans path and returns an
EnvVarDetectionResult.
| Parameter |
Type |
Default |
Description |
path |
str | Path |
"." |
Root directory (or single file) to scan |
skip_dirs |
frozenset[str] |
None |
Extra directory names to skip (merged with built-in skip list: .git, .venv, node_modules, __pycache__, …) |
include_config |
bool |
True |
Set False to skip config-file scanning |
include_source |
bool |
True |
Set False to skip source-code scanning |
scan_dotenv_file(path, root)
Parses a single .env.example-style file.
KEY=value lines → required=True
# KEY=value lines → required=False (documented optional variable)
- Preceding comment lines are attached to the next variable as
comment
scan_config_file(path, root)
Scans any text-based config file for ${VAR_NAME} and $VAR_NAME patterns.
scan_source_file(path, root, language)
Scans a single source file. Supported language values:
"python", "javascript", "typescript", "go", "ruby", "shell".
Data Models
EnvVarEntry
class EnvVarEntry(BaseModel):
name: str # e.g. DATABASE_URL
source: EnvVarSource # dotenv_example | config_file | source_code
file_path: str # repo-relative path
line_number: int | None
default_value: str | None
comment: str | None
required: bool # False = commented-out optional variable
EnvVarDetectionResult
class EnvVarDetectionResult(HarnessResponse):
command: str # "detect-env-vars"
status: Status # always "passed"
scanned_path: str
env_vars: list[EnvVarEntry] # one per occurrence
unique_var_names: list[str] # sorted, de-duplicated names
dotenv_files_found: list[str]
config_files_found: list[str]
source_files_scanned: int
total_vars_found: int
Detection Patterns
Python
| Pattern |
Regex |
os.environ['KEY'] |
os\.environ\[['"]KEY['"] |
os.environ.get('KEY') |
os\.environ\.get\(['"]KEY['"] |
os.getenv('KEY') |
os\.getenv\(['"]KEY['"] |
JavaScript / TypeScript
| Pattern |
Regex |
process.env.KEY |
process\.env\.KEY |
process.env['KEY'] |
process\.env\[['"]KEY['"] |
Go
| Pattern |
Regex |
os.Getenv("KEY") |
os\.Getenv\("KEY"\) |
os.LookupEnv("KEY") |
os\.LookupEnv\("KEY"\) |
Ruby
| Pattern |
Regex |
ENV['KEY'] |
ENV\[['"]KEY['"] |
ENV.fetch('KEY') |
ENV\.fetch\(['"]KEY['"] |
Config files
| Pattern |
Notes |
${VAR_NAME} |
Shell-style brace substitution |
$VAR_NAME |
Bare dollar (min 3 chars to reduce false-positives) |
Key Files
| Path |
Purpose |
harness_skills/env_var_detector.py |
Core detection logic — three scanners + detect_env_vars() |
harness_skills/models/env_vars.py |
Pydantic models: EnvVarEntry, EnvVarDetectionResult, EnvVarSource |
tests/test_env_var_detector.py |
Full test suite (40+ test cases) |
.claude/commands/detect-env-vars.md |
Agent slash-command documentation |
Notes
- The skill is read-only — it never modifies project files.
- Variables found in multiple files produce one
EnvVarEntry each (the env_vars
list may contain duplicates across files); unique_var_names is always de-duplicated.
- The built-in skip list prevents scanning
.git, .venv, node_modules,
__pycache__, dist, build, .claw-forge, and .tox.
- Related skills:
/detect-api-style, /module-boundaries, /harness:context.
1---2name: detect-env-vars3description: >4 Codebase analysis skill that detects environment variable patterns from5 .env.example / .env.sample template files, YAML/TOML/JSON/INI config files6 that use ${VAR} interpolation, and source code references (os.environ,7 os.getenv, process.env, os.Getenv, ENV[]) across Python, JavaScript,8 TypeScript, Go, Ruby, and Shell. Produces a structured, de-duplicated9 inventory of every environment variable the project depends on.10 Use when: (1) onboarding to a new project and need to know what env vars to11 set, (2) auditing which services / files read a given variable, (3) generating12 .env documentation, (4) validating that .env.example is complete against13 actual code usage. Triggers on: env var, environment variable, .env.example,14 process.env, os.environ, os.getenv, config variables, secret inventory,15 required environment, dotenv.16metadata:17 source: https://skillmd.com/skills/bowen31337/detect-env-vars18---1920# Detect Environment Variables2122## Overview2324The `detect-env-vars` skill scans a project directory and builds a complete,25structured inventory of every environment variable in use. It reads from26**three independent source types** and merges the results:2728| Source | Examples | What is captured |29|--------|----------|------------------|30| **dotenv template** | `.env.example`, `.env.sample`, `.env.dist` | Variable names, example values, comments, required vs. optional |31| **config files** | `*.yaml`, `*.yml`, `*.toml`, `*.json`, `*.ini` | `${VAR}` / `$VAR` interpolation references |32| **source code** | `*.py`, `*.js`, `*.ts`, `*.go`, `*.rb`, `*.sh` | `os.environ`, `os.getenv`, `process.env`, `os.Getenv`, `ENV[]` calls |3334---3536## Quick Start3738```python39from harness_skills.env_var_detector import detect_env_vars4041result = detect_env_vars(".") # scan current directory42print(result.unique_var_names) # sorted, de-duplicated names43print(result.total_vars_found) # total occurrences (not unique)44print(result.dotenv_files_found) # .env.example paths scanned45print(result.source_files_scanned) # number of source files inspected46```4748```python49# Granular scanning50from harness_skills.env_var_detector import (51 scan_dotenv_file,52 scan_config_file,53 scan_source_file,54)55from pathlib import Path5657root = Path(".")5859# Parse a single .env.example60entries = scan_dotenv_file(Path(".env.example"), root)61for e in entries:62 status = "required" if e.required else "optional"63 print(f" [{status}] {e.name}={e.default_value} # {e.comment}")6465# Extract ${VAR} refs from a YAML config66entries = scan_config_file(Path("config/app.yaml"), root)6768# Scan a Python file for os.environ references69entries = scan_source_file(Path("app/settings.py"), root, "python")70```7172---7374## Function Reference7576### `detect_env_vars(path, *, skip_dirs, include_config, include_source)`7778Recursively scans *path* and returns an79[`EnvVarDetectionResult`](#envvardetectionresult).8081| Parameter | Type | Default | Description |82|-----------|------|---------|-------------|83| `path` | `str \| Path` | `"."` | Root directory (or single file) to scan |84| `skip_dirs` | `frozenset[str]` | `None` | Extra directory names to skip (merged with built-in skip list: `.git`, `.venv`, `node_modules`, `__pycache__`, …) |85| `include_config` | `bool` | `True` | Set `False` to skip config-file scanning |86| `include_source` | `bool` | `True` | Set `False` to skip source-code scanning |8788### `scan_dotenv_file(path, root)`8990Parses a single `.env.example`-style file.9192- `KEY=value` lines → `required=True`93- `# KEY=value` lines → `required=False` (documented optional variable)94- Preceding comment lines are attached to the next variable as `comment`9596### `scan_config_file(path, root)`9798Scans any text-based config file for `${VAR_NAME}` and `$VAR_NAME` patterns.99100### `scan_source_file(path, root, language)`101102Scans a single source file. Supported `language` values:103`"python"`, `"javascript"`, `"typescript"`, `"go"`, `"ruby"`, `"shell"`.104105---106107## Data Models108109### `EnvVarEntry`110111```python112class EnvVarEntry(BaseModel):113 name: str # e.g. DATABASE_URL114 source: EnvVarSource # dotenv_example | config_file | source_code115 file_path: str # repo-relative path116 line_number: int | None117 default_value: str | None118 comment: str | None119 required: bool # False = commented-out optional variable120```121122### `EnvVarDetectionResult`123124```python125class EnvVarDetectionResult(HarnessResponse):126 command: str # "detect-env-vars"127 status: Status # always "passed"128 scanned_path: str129 env_vars: list[EnvVarEntry] # one per occurrence130 unique_var_names: list[str] # sorted, de-duplicated names131 dotenv_files_found: list[str]132 config_files_found: list[str]133 source_files_scanned: int134 total_vars_found: int135```136137---138139## Detection Patterns140141### Python142| Pattern | Regex |143|---------|-------|144| `os.environ['KEY']` | `os\.environ\[['"]KEY['"]` |145| `os.environ.get('KEY')` | `os\.environ\.get\(['"]KEY['"]` |146| `os.getenv('KEY')` | `os\.getenv\(['"]KEY['"]` |147148### JavaScript / TypeScript149| Pattern | Regex |150|---------|-------|151| `process.env.KEY` | `process\.env\.KEY` |152| `process.env['KEY']` | `process\.env\[['"]KEY['"]` |153154### Go155| Pattern | Regex |156|---------|-------|157| `os.Getenv("KEY")` | `os\.Getenv\("KEY"\)` |158| `os.LookupEnv("KEY")` | `os\.LookupEnv\("KEY"\)` |159160### Ruby161| Pattern | Regex |162|---------|-------|163| `ENV['KEY']` | `ENV\[['"]KEY['"]` |164| `ENV.fetch('KEY')` | `ENV\.fetch\(['"]KEY['"]` |165166### Config files167| Pattern | Notes |168|---------|-------|169| `${VAR_NAME}` | Shell-style brace substitution |170| `$VAR_NAME` | Bare dollar (min 3 chars to reduce false-positives) |171172---173174## Key Files175176| Path | Purpose |177|------|---------|178| `harness_skills/env_var_detector.py` | Core detection logic — three scanners + `detect_env_vars()` |179| `harness_skills/models/env_vars.py` | Pydantic models: `EnvVarEntry`, `EnvVarDetectionResult`, `EnvVarSource` |180| `tests/test_env_var_detector.py` | Full test suite (40+ test cases) |181| `.claude/commands/detect-env-vars.md` | Agent slash-command documentation |182183---184185## Notes186187- The skill is **read-only** — it never modifies project files.188- Variables found in multiple files produce one `EnvVarEntry` each (the `env_vars`189 list may contain duplicates across files); `unique_var_names` is always de-duplicated.190- The built-in skip list prevents scanning `.git`, `.venv`, `node_modules`,191 `__pycache__`, `dist`, `build`, `.claw-forge`, and `.tox`.192- Related skills: `/detect-api-style`, `/module-boundaries`, `/harness:context`.