An AGENTS.md secrets block is a short section of your repo's agent instructions that says four things: where environment config lives, what an agent must never print or commit, how to ask for a missing secret, and how to redact values in anything it outputs. Agents read key names from it, never values. Put it at the repo root so every package inherits it, and back it with a secret scanner so a slip fails before merge. Keep the wording short and explicit so every harness that reads the file sees the same rule.
Who this is for
You already keep an AGENTS.md (if not, start with the AGENTS.md guide) and you let coding agents run commands, edit config, and write logs. This page covers the file itself: the wording of the secrets section. The habit of keeping keys out of chat threads is a separate topic, covered in Never put secrets in chat ops.
The four parts of the block
| Part | What to write | What never to write |
|---|---|---|
| Where env lives | Paths to the env files or secret store, plus the example file that lists required keys | Any real value, even "just for local" |
| Never print or commit | "Do not echo, log, paste, or commit secret values. Refer to keys by name." | A list of exceptions |
| Requesting a secret | "If a key is missing, stop and ask a human for it by name." | "Use a dummy value to keep going" |
| Redaction | "Mask values in output as `****`. Show only the key name." | Partial values like the first and last characters |
A copyable section
Paste this into AGENTS.md and edit the paths. Every value shown is a placeholder.
## Secrets and environment- Environment config lives in `.env.local` (git-ignored). Required keys are listed, without values, in `.env.example`. - Read key names from `.env.example`. Do not open, print, or summarize `.env.local`. - Never echo, log, paste, or commit a secret value. Refer to keys by name only, for example `STRIPE_SECRET_KEY`. - Never hardcode a secret in source, tests, fixtures, or docs. Use `process.env.KEY_NAME` (or the language equivalent). - If a required key is missing, stop and ask a human for it by name. Do not invent a placeholder that could ship. - In any output, mask values as `****`. - Before finishing, run the secret scan in the verify step. A finding blocks the change. ```
In `.env.example`, keep the shape and drop the values:
STRIPE_SECRET_KEY=
DATABASE_URL=
RESEND_API_KEY=Root or per package
Write the rules once, at the root AGENTS.md. In a monorepo, a package-level AGENTS.md should only add *which* keys that package needs ("this app reads `DATABASE_URL` and `RESEND_API_KEY`"). Don't restate or loosen the root rules there; a package file that says "it's fine to log config here" undoes the whole block.
Pitfalls
- Examples with real-looking values. An agent copies the pattern it sees. Use empty values or obvious placeholders like `sk_test_REPLACE_ME`.
- "Read .env to understand the setup." That instruction invites the agent to print the file. Point it at `.env.example` instead.
- Silent fallbacks. "Use a default if missing" turns a missing secret into a hardcoded one. Make "stop and ask" the only path.
- Rules with no check. A sentence in a file is a request. The scanner is what enforces it.
How to check it
- Ask your agent to set up a feature that needs a key you haven't provided. It should stop and name the key, not invent one.
- Read its diff and terminal output for raw values.
- Run a secret scanner as part of your verify step so a leaked value fails the change before merge.
Where ShipKits fits
The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats, three skills, an ops playbook and a token-cost playbook. Done means a file, PR, or URL. Drop this secrets section into its shared instructions once, and every seat you add starts from the same rules. Soft path: start at /free. Cheat Sheet for the skim checklist mindset.
Soft next step
Copy the section above into your root AGENTS.md today and run the "missing key" test once. Soft ladder: /free, then the Operator Pack ($47). Related: never put secrets in chat, writing the verify step.