Secrets Vault

---
name: secrets-vault
description: Use whenever an API key, token, password, connection string, or any other secret needs to be stored, rotated, retrieved, or used — so the value never enters the chat transcript. Triggers on "vault this", "save this key/token/password", "rotate the <x> key", "where's the <x> secret", "put this in the vault", or any time a credential is about to be handled.
---

# secrets-vault

A secret must never appear in an AI chat transcript. Once a key is typed into the
conversation it is in the transcript, in the context window, and possibly in a
summary — permanently, before any tool runs. This skill routes every secret
through the `vault` CLI so the value has no path into the conversation.

## The one rule that makes this work

**The user copies the secret to their clipboard. It enters from there, never from
the chat.** You never see the value, and you never ask them to type it.

If the user pastes an actual credential into the chat, or puts one in a command
argument, **stop and say so** — the value is already exposed; the fix is to
rotate it, then re-do this via the clipboard. Do not repeat the leaked value
back, and do not proceed as if it were safe.

## How you must handle secret values

- **Never** `cat`, `grep`, `head`, `tail`, `sed`, `less`, or otherwise read the
  vault file (`~/.vault/secrets.md` by default) to obtain a value. That prints it
  into the transcript. The store is greppable **by the human in their own
  terminal** — never by you inside a session.
- To store one: tell the user to copy it, then run
  `vault put <slug> --note "<what it is>"`. The value goes clipboard → vault; the
  clipboard is cleared; you get back a reference `vault://<slug>@vN` and a
  fingerprint. Both are safe to show.
- To run something that needs a secret, **inject** it, never print it:
  `vault use <slug> -- <command>` — the child process gets it as an environment
  variable named after the slug, and you only see the command's own output.
- `vault copy <slug>` puts the value on the clipboard and prints nothing — use
  this when the user needs to paste it somewhere themselves.
- `vault show <slug> --confirm` is the **only** path that prints a value. It is a
  deliberate escape hatch for a human pasting into a web console. If you run it,
  warn first, and afterward remind the user the value is now in the transcript
  and to treat it accordingly.
- If a `vault` command errors, scrub anything credential-shaped from the output
  before showing it.

## Commands

| Command | What it does |
|---|---|
| `vault put <slug> [--env NAME] [--note "..."]` | Clipboard → vault as v1. Prints the reference + fingerprint, clears the clipboard. |
| `vault rotate <slug> [--note "..."]` | New version from the clipboard; the previous version is kept and marked superseded, so rollback is always possible. Refuses a byte-identical rotation. |
| `vault list [filter]` | Slugs, versions, fingerprints, dates, notes. Safe to print. |
| `vault status` | Store health, permissions, configured backends. |
| `vault copy <slug>[@vN]` | Value → clipboard. Prints nothing. |
| `vault show <slug>[@vN] --confirm` | Prints the value. Requires `--confirm`. |
| `vault use <slug>[@vN] [more...] -- <cmd>` | Runs `<cmd>` with each value in its env var. |
| `vault scan [path]` | Finds credential-shaped values in a repo that are **not** vaulted — names + fingerprints + file permissions only, never values. |
| `vault fingerprint` | Fingerprints whatever is on the clipboard without storing it. |
| `vault publish` | Runs the user's configured publish backend (password manager, CRM, backoffice, S3, …). |

## References are the whole point

`vault://<slug>@vN` is a stable handle that is safe in a transcript. When the user
later says "deploy with `vault://stripe-prod@v2`", resolve it at run time with
`vault use` — never by reading the file. This lets you keep working with a secret
you can name but never see.

## Rotation hygiene

When a secret may have been exposed (typed into a chat, printed by `show`, found
by `scan` in a loose-permission file, or just old), recommend `vault rotate`. The
old version stays for rollback; the fingerprint changes, so the user can confirm
every system picked up the new value without ever seeing it.