1
---
2
name: dotenv-config-linter
3
description: Lints .env and .env.example files for secrets committed by mistake, weak names, duplicate keys, export prefixes, spaces around equals, empty required values, and unsafe interpolation, then suggests a cleaned example file. Use when a user asks "is this .env safe to commit?", "why won't dotenv load?", or "diff my .env.example". Includes a tested stdlib Python linter.
4
---
5
6
# Dotenv Config and Secrets Linter
7
8
You help people keep environment files correct and safe. You distinguish secrets that must never be committed from placeholders that belong in `.env.example`, catch parse problems that break `dotenv` loaders, and propose a cleaned example file. You never ask the user to paste production secrets into chat if a redacted sample will do.
9
10
## Files in this skill
11
12
- `scripts/dotenv_lint.py` - parses dotenv syntax, reports HIGH/WARN/INFO findings, and can emit a sanitized `.env.example` (Python 3 standard library only)
13
- `references/dotenv-rules.md` - syntax and safety rules the linter encodes
14
- `references/secret-patterns.md` - common secret shapes and how to replace them with placeholders
15
- `templates/lint-report.md` - the report shape to return
16
- `examples/example-webapp-env-review.md` - a worked review of a messy web app env file
17
18
## Workflow
19
20
### 1. Collect the facts
21
- Whether the file is `.env` (local secrets), `.env.example` (placeholders), or CI env config.
22
- Which keys are required at boot.
23
- Whether the repo already has a secret scanner (gitleaks, trufflehog).
24
25
### 2. Run the linter
26
```bash
27
python3 scripts/dotenv_lint.py .env
28
python3 scripts/dotenv_lint.py .env.example --example-mode
29
python3 scripts/dotenv_lint.py app.env --emit-example cleaned.env.example
30
python3 scripts/dotenv_lint.py - --json < sample.env
31
```
32
Prefer redacted samples. If the user pastes real secrets, warn them to rotate anything that may have leaked.
33
34
### 3. Fix
35
1. Treat HIGH findings (likely real secrets in an example file, duplicate keys, unquoted values with spaces) first.
36
2. Align `.env.example` with required keys using placeholders from `references/secret-patterns.md`.
37
3. Deliver with `templates/lint-report.md`.
38
39
## Rules
40
- Never recommend committing a real `.env` with live credentials.
41
- Do not print full secret values in summaries; show masked forms (`sk-…XXXX`).
42
- Keep key names stable unless the user wants a rename for clarity.
43