Skip to content
Hidden Logic Lab

Keep secrets out of agent chat with env and a SKILL.md

Claude Code or Cursor follows a checked-in skill that forbids pasting DB and API secrets into chat: use .env, a secret manager, op run, or CI secrets, and reference variable names only.

Claude Code, Cursor
·Coding·30 min·Working

A secrets-hygiene SKILL.md, a .env.example with placeholders, and a short runbook for local dev that never requires copying production values into the agent.

  1. 1

    Audit what agents have been pasting

    Rotate anything that already appeared in chat or tickets. The skill is policy; rotation closes the leak.

  2. 2

    Commit SKILL.md and refresh .env.example

    Variable names only in example files. Link the skill from AGENTS.md or Claude Code skills path the same day.

  3. 3

    Run one failing integration through the skill

    Reproduce a DB or API error using local env injection. The agent should guide checks without asking for the production password.

The prompt to paste

Write a secrets-hygiene SKILL.md for agents working in this repository. Humans must never paste production secrets into chat; agents must never echo secrets they see in files.

Repo context:
[languages, how we load env e.g. dotenv, doppler, 1Password op run, Vercel/Netlify env]
Test and dev commands:
[paste package.json scripts or [confirm command]]

SKILL.md must include:
1. Purpose: develop and debug using env vars and secret managers, not chat paste.
2. When to use: any task touching auth, payments, databases, third-party APIs; when not to use: public docs-only questions.
3. Hard rules for the agent:
   - Never ask the human to paste API keys, passwords, connection strings, or JWTs into chat.
   - Never print, log, or repeat secret values from .env, config, or process env in replies or commits.
   - Use placeholder names only (e.g. DATABASE_URL, STRIPE_SECRET_KEY) and tell the human which name to set locally.
   - If a fix requires a real value to verify, instruct the human to run the command locally and paste redacted output (exit code, error type) — not the secret.
4. Human workflow: .env.example updated, .env gitignored, local run via [op run -- … / doppler run / docker compose] as we actually use.
5. CI workflow: secrets only in platform secret stores; agents edit workflow YAML to reference secret names, not values.
6. Steps for debugging auth/DB failures without secrets: read code paths, suggest checks, propose test doubles or staging keys if documented.
7. Pitfalls: committing .env, echoing env in test logs, “temporary” keys in PR descriptions, screenshotting dashboards with tokens visible.
8. Done means: checklist including “no secret-shaped strings in the diff or PR body” and “.env.example documents every required name.”

Also return a ## .env.example block (separate from SKILL.md) listing variable NAMES and one-line descriptions only — no real values.

Rules:
- Do not invent a secret manager we do not use; mark [confirm tool] if unsure.
- Output SKILL.md first, then .env.example.

Redacted logs still leak format and length. Train reviewers to reject PRs that add echo $SECRET or printenv dumps in scripts.

Sample case written by Hidden Logic Lab. Not affiliated with Claude Code or Cursor.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.