secrets-handling

name: secrets-handling user-invocable: false description: "A personal-machine credentials layout for the terminal: SSH host/auth and HTTP Basic via native mechanisms (~/.ssh/config, ~/.netrc, gh auth login); generic API tokens and passwords in ~/.config/credentials/secrets.env (mode 0600) read only through the secret helper or as shell env-vars; descriptions and server short-names in ~/.claude/credentials-index.md (no values inside). Direct reads of the credentials store are denied by settings.json patterns. Credential values reach the subprocess through $VAR or $(secret get NAME) shell substitution, never through the response transcript. A pre-reply scan checks the draft against shape regexes for GitHub / AWS / OpenAI / Anthropic / Slack / Stripe / SSH key blocks / generic high-entropy strings." when_to_use: "A task involves credentials in the terminal — invoking an HTTP API with a token, SSH'ing to a known host, running a CLI against a remote service, mentioning a server by short-name from the credentials index. Also applies when the response will include something resembling a token (command output, error message, copy-pasted snippet) — the pre-reply shape scan triggers here. Not relevant for pure local file edits or read-only analysis without external calls."

Secrets handling

Personal-machine policy for credentials. Not a vault, not a secret manager — a layout convention that makes accidental disclosure less likely and gives the model an explicit map of what exists.

The three tiers

What to read, what to refuse

Always read when relevant:

• ~/.claude/credentials-index.md — the directory of what exists. Read this when the user mentions a server short-name or service that might need credentials, and you don't yet know whether it is registered. The index tells you the short-name, the access pattern (env-var or secret get), and any side notes.

Never read directly:

• ~/.config/credentials/secrets.env and .bak — the secret store itself.
• ~/.ssh/id_*, ~/.netrc, ~/.aws/credentials, ~/.gnupg/* — tier-1 native stores.
• Any .env.production*, .env.prod* in projects.

These are enforced by permissions.deny in settings.json and by path-validation.py (PreToolUse hook). The skill is the policy; the hook is the safety net.

How to use a secret in a command

Pattern A — secret is already in the shell environment (because ~/.zshenv sourced the store at session start):

curl -H "x-api-key: $DOKPLOY_PROD_API_KEY" https://...

The variable expands inside the shell process; the value is never written into the message you send.

Pattern B — secret is in the store but not in env (rare — for example, a token you just secret set and want to use without restarting the shell):

curl -H "x-api-key: $(secret get DOKPLOY_PROD_API_KEY)" https://...

secret get runs in a subshell; its stdout is captured by $() and substituted into curl's argv inside the same shell process. The value reaches the curl process but not the model's transcript.

Anti-pattern (do not do):

cat ~/.config/credentials/secrets.env | grep DOKPLOY    # denied by hook
TOKEN=$(secret get DOKPLOY_PROD_API_KEY); echo "Token is $TOKEN"    # would echo the secret

Never assign a secret to a regular variable that gets echoed, logged, or written to a file (other than as an env-var consumed silently by another tool).

How to refer to a service in conversation

When the user says "go to vps-store, check the nginx logs":

1. Read ~/.claude/credentials-index.md, locate the vps-store section.
2. Note the access pattern from the index (ssh vps-store, key path, any pre-set env-var names).
3. Run the command using Pattern A or B.

When the user mentions a service that is not in the index:

• Ask the user whether it should be added, or proceed without persistent storage (one-shot value passed inline).
• Do not invent credentials; do not assume short-names.

Auto-mode caveat

The store is sourced by ~/.zshenv at shell start. Claude Code's Bash subprocess always reads ~/.zshenv (not .zshrc), so the secrets are present in env for all commands you run, including unattended auto-runs.

If a secret is missing from env (recently added via secret set but the current shell predates the change, or sourcing failed) — use Pattern B ($(secret get NAME)) explicitly. Do not try to source ~/.zshenv to reload — it may have side effects on the current Bash subprocess state.

If you must read a value into your own reasoning (rare — e.g. validating format), use secret get NAME and immediately discard; do not echo it back in the response.

Pre-reply self-scan for accidental leakage

Before sending a response that involved fetching or generating credentials, scan your draft text for known secret shapes. If any match — stop, do not send, surface the issue to the user and ask whether to redact.

High-confidence patterns (sourced from gitleaks rules, verified):

Lower-confidence (community-derived, format-only, no vendor regex):

A match means something resembling a secret is in your response. It may be a legitimate placeholder (sk-xxxxxxxx) — in that case, redacted form (sk-***) is fine. Real-looking values must not be sent.

Common rationalisations to refuse

When this skill is irrelevant

• The task does not touch any service that needs auth (pure local file edits, pure read-only analysis without external calls).
• The user explicitly disables tier-2 / tier-3 (secret not installed, no index file). Then fall back to whatever credential method the project actually uses.

Cross-refs

• curl-requests — HTTP testing; the canonical consumer of secret get (Pattern B) and env-var (Pattern A).
• surface-ticket — if a credential is missing or misconfigured and out of scope to fix now, surface a ticket; do not leave the issue dangling.
• path-validation.py (PreToolUse hook) — enforces denial of direct reads on ~/.config/credentials/; this skill is the policy, hook is the safety net.
• secret-commit-gate.py (PreToolUse hook) — denies a git commit whose staged diff adds a high-confidence token from the table above (type + file only in the reason, never the value). Keep the gate's SECRET_PATTERNS in sync with this skill's high-confidence table; encrypted-secret repos (SOPS / git-crypt) are auto-skipped. See ADR 0079.
• secret helper script (~/.local/bin/secret) — installed by install.sh; the only sanctioned read/write interface to the tier-2 store.