secret-hygiene

A Claude Skill (plus a zero-dependency pre-commit hook) that stops credentials from ever reaching your code — API keys, passwords, tokens, JWTs, private keys, connection strings.

Why this exists, and why it's not another gitleaks

Scanners like gitleaks and trufflehog are excellent — but they all fire after a secret is already written into a file. They catch the symptom. This skill treats the cause: it teaches Claude (in Claude Code) the habit of never hardcoding a credential in the first place, reading it from the environment instead, and checking its own staged changes before proposing a commit.

If you pair-program with Claude, this closes the exact gap where leaks are born — the moment code gets written.

What's in here

• skills/secret-hygiene/ — the Skill. Drop it into Claude Code and Claude will apply secret-safe habits whenever it writes config, deploy scripts, a CLAUDE.md, or anything touching credentials, and scan staged changes before committing.
• skills/secret-hygiene/scripts/scan.py — the scanner it uses. Pure Python 3 stdlib, no install. Works standalone too.

Use the scanner directly

python3 skills/secret-hygiene/scripts/scan.py .          # scan a directory
python3 skills/secret-hygiene/scripts/scan.py --staged   # scan git-staged changes
python3 skills/secret-hygiene/scripts/scan.py --json     # machine-readable output

Exit code is 1 if anything is found — so it drops straight into a git hook:

cp skills/secret-hygiene/scripts/scan.py .secret-hygiene/scan.py
printf '#!/bin/sh\npython3 .secret-hygiene/scan.py --staged\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Now every commit is scanned first. See skills/secret-hygiene/references/pre-commit.md.

Silencing false positives

No scanner is perfect, and one loud false positive is how a hook gets disabled. Two escape hatches, both scoped as narrowly as possible:

• One line: append # secret-hygiene: ignore (or the detect-secrets-style # pragma: allowlist secret) to the offending line.
• Whole paths: add globs to a .secretignore file — same syntax as .gitignore (e.g. tests/fixtures/*, *.pem).

Use them only when you're sure the value is safe — a silenced real secret is worse than a warning.

Tests

pytest skills/secret-hygiene/tests/

Covers every detector, the placeholder/entropy filtering, both allowlist mechanisms, secret masking, JSON output, and the staged-scan git-hook path.

What it detects

JWTs · PEM private keys · AWS / GitHub / Slack / Google / OpenAI / Anthropic key formats · user:pass@host connection strings · and high-entropy values assigned to password / secret / token / *_key variables (including prefixed names like SSH_PASS, DB_PASSWORD). Placeholders (your_key_here, changeme, os.environ[...]) are filtered out by an entropy floor.

Honest scope

This is the fast, always-with-you first layer, not a full secrets platform. For a public repo or anything in production, also run gitleaks (pre-commit + CI) and trufflehog (history sweeps with live-credential verification). The skill says so itself and points you there — the layers complement each other.

License

MIT