Config File Documenter

What this skill does

Inventories every environment variable in .env.example (and similar files like config/default.yaml) and produces a single reference page. Each entry is cross-referenced to the source files that read it.

Inputs

• repo_dir: project root.
• Optional config_globs: paths to scan; defaults to .env.example, .env.sample, config/*.yaml, config/*.json.
• Optional out_path: where to write the reference page (default docs/config.md).

Steps

1. Collect declared variables: rg -oN '^[A-Z][A-Z0-9_]+(?==)' .env.example plus YAML/JSON keys parsed via yq / jq.
2. For each variable, search reads in the source: rg -nN "process\.env\.<NAME>\b|os\.environ\[['\"]<NAME>['\"]\]|os\.getenv\(['\"]<NAME>['\"]\)" <repo_dir>.
3. If a variable has zero reads, mark it unused and surface in the report's warnings.
4. Detect default values from the read site (e.g., process.env.X || 'foo'); record the default.
5. Detect required-ness: a read with no default and a runtime throw nearby is required; otherwise optional.
6. Detect type from value patterns in .env.example: digits-only -> integer, true|false -> boolean, URL prefix -> url, else string.
7. Group variables by feature using common prefixes (DB_, STRIPE_, NEXT_PUBLIC_).
8. Emit a markdown table per group: | Name | Type | Required | Default | Read at | Description |.
9. Pull the description from a same-line # comment in .env.example if present.
10. Write to out_path.

Output

A markdown reference at out_path with one H2 per prefix group and a final "Unused / Stale" section. Stdout summarizes counts per group plus the unused list.

Verification

Re-run the rg queries for three sampled variables and confirm the cited file:line exists. Verify every variable in .env.example appears in the report — wc -l of .env.example declarations should match the report's table row count plus the unused count. If a variable read in code is missing from .env.example, surface as an "undeclared" finding rather than silently adding it.

Edge cases

• Variables read indirectly via process.env[name] (computed key): cannot be cross-referenced; flag and skip.
• Multiple .env.* files (per environment): merge declarations, dedupe, note origin in the description.
• Encrypted values (e.g., SOPS-managed): skip default extraction, mark as secret.
• Variables only referenced in tests: tag as test-only rather than mark them unused.