AgentKit Vault
Handle credentials the way the user chose, with no value ever entering the
conversation. ak secrets is the recommended store, not a mandatory one: a user
who keeps .env.* files or runs another secret manager is followed, never
pushed. Ask a question only when a decision is genuinely missing, and record the
answer so it is never asked again.
Hard rules
- Never print, echo, log, or paste a secret value. Report refs, counts, exit
codes, and
[redacted] only. Never ask a person to paste a value into the
conversation.
- Feed values only through stdin (
--value=-) or a file (--value-file), from
a script that reads the source and pipes it on. --value=<literal> is
rejected by the CLI and would leak into shell history.
- Do not read a
.env* file to discover what it contains. Its name is enough to
detect it; read it only inside a non-echoing script that moves a value the
user asked to move.
- Write
${secret:NAME} only where you mean it to resolve (see
runtime-and-lifecycle.md). Never type it
into a commit message, heredoc, or other shell text; author such text with the
file-editing tools instead.
- Never
--force over an existing ref whose source of truth is unclear. Check
first; ask when the stored value and the new one could disagree.
ak secrets get --reveal is for a person at a terminal. An agent confirms a
write by exit code, get (prints [redacted]), search, or list --json.
- To tell whether a stored ref holds the expected credential (which account,
old or rotated, the same as a
.env entry), read its hint in
list --json, get --json or search --json (a public prefix and the last
4 characters, or null with a hintReason), then confirm with
ak secrets compare <REF> --value-file <path> or --value=- from a
non-echoing script; it answers match or differs and prints neither value.
It refuses with exit 2 when the candidate or the stored value is under 16
characters after any public prefix and one trailing newline, the same rule
that withholds a hint (hintReason: short value), and each call is a row in
ak secrets audit when the ledger exists, so never loop it to guess a value.
Never ask for --reveal or create a duplicate ref "just in case" when the
hint and compare can answer. Quote a hint only as a hint, never as a value.
- Before saying anything about the cloud vault, read
ak secrets sync status --json (local, no network). Never claim sync is off
or absent without it.
Step 1: Read the recorded choice
ak config prefs resolve --json # read .prefs.secretStore.choice
| Choice |
What to do |
ak-vault |
Use ak secrets (Steps 2 to 4). |
env-file |
Work with the project's .env.* files as asked. Do not suggest the vault. Warn once, without blocking, if git check-ignore -q <file> says a secrets file is not ignored. |
external:<name> |
Use that manager's own documented workflow. Do not suggest the vault, and do not try to verify the manager exists. |
| unset |
Recommend once (below), then follow the answer. |
Recommend once. Only while the current task actually involves a credential
or a .env.* file, and only in an interactive session, ask one question:
store secrets in AgentKit's vault (recommended: encrypted, searchable,
optionally synced across devices), keep .env.* files, or use another manager
(name it). Ask in the same question whether the answer covers this project or
every project. Record it immediately:
ak config prefs set secret_store.choice ak-vault --scope project # or user, env-file, external:1password
A user who brushes the question off has still answered it: record what the
project already does (env-file when it keeps .env.* files) at project scope.
In --json, CI, or any non-interactive run, never ask and never recommend;
continue with whatever the project already uses.
Step 2: Settle the metadata before writing (ak-vault only)
Every ref needs a project and an environment so it can be found later. Infer
them first, from evidence rather than guesses:
- environment from the file name (
.env.production is production) or the
deploy target being configured;
- project from the repository (
git remote get-url origin basename, else the
repository directory name) or the deploy config's name;
- provider from the variable prefix (
CLOUDFLARE_* is cloudflare), account
only when the source states it.
When project or environment is still missing or ambiguous (a bare .env, a
monorepo with several apps, a key shared by several projects), ask the user
one question right away, before writing, offering the inferred candidates.
In a non-interactive run, stop without writing and name the missing fields.
Profile metadata (description, project, environment, provider, account, tags)
syncs only to devices on a current ak; older ones see the ref name, value,
and timestamps only. So the ref name itself must stay findable everywhere: use <PROJECT>_<NAME>
for a project-specific secret (add _<ENV> when the project keeps more than
one environment of it), and the provider's conventional name (for example
CLOUDFLARE_API_TOKEN) for a credential shared across projects. A ref name is
independent of the environment variable the app reads.
Step 3: Store, find, and sync
Check before writing: ak secrets search <words> --json or
ak secrets list --json. When a candidate ref exists, read its hint, then
pipe the new value into ak secrets compare <REF> --value=- from the
non-echoing script to learn whether the ref already holds it. An existing ref
for the same purpose is updated with
ak secrets rotate (value changed) or ak secrets annotate (metadata only),
not re-created. Then store, verify, and sync as described in
store-and-sync.md, which holds the non-echoing
script templates, import-env for whole files, and the sync cycle.
Step 4: Use, rotate, and recover
Runtime use through ${secret:NAME}, approvals, rotation, deletion, export,
audit, and vault recovery are in
runtime-and-lifecycle.md. Several of
those commands refuse to run under an agent by design; hand the exact command
to the user instead of looking for a way around it.
Command details
Flags and exit codes come from ak secrets <command> --help, which is the
current authority; read it before using a flag this skill does not show.
1---2name: ak-vault3description: "Store, find, sync, rotate, and use secrets (API keys, tokens, .env values) through AgentKit's `ak secrets` vault without ever printing a value, while honoring a user's recorded choice of .env files or another secret manager. Use when a task touches a credential, a .env.* file, or a deploy or API call that needs a key."4when_to_use: "Invoke when a task stores, finds, rotates, syncs, imports, or uses a credential, or meets .env.* files. It reads the recorded secret store choice first and asks at most once."5category: workflow6keywords: [secrets, vault, credentials, api-key, token, dotenv, env-file, ak-secrets, sync, rotate, import-env]7argument-hint: "[store|find|sync|use|rotate|import] [ref or .env path]"8metadata:9 source: https://skillmd.com/skills/majiayu000/ak-vault10 author: agentkit11 version: "1.0.0"12---1314# AgentKit Vault1516Handle credentials the way the user chose, with no value ever entering the17conversation. `ak secrets` is the recommended store, not a mandatory one: a user18who keeps `.env.*` files or runs another secret manager is followed, never19pushed. Ask a question only when a decision is genuinely missing, and record the20answer so it is never asked again.2122## Hard rules2324- Never print, echo, log, or paste a secret value. Report refs, counts, exit25 codes, and `[redacted]` only. Never ask a person to paste a value into the26 conversation.27- Feed values only through stdin (`--value=-`) or a file (`--value-file`), from28 a script that reads the source and pipes it on. `--value=<literal>` is29 rejected by the CLI and would leak into shell history.30- Do not read a `.env*` file to discover what it contains. Its name is enough to31 detect it; read it only inside a non-echoing script that moves a value the32 user asked to move.33- Write `${secret:NAME}` only where you mean it to resolve (see34 [runtime-and-lifecycle.md](references/runtime-and-lifecycle.md)). Never type it35 into a commit message, heredoc, or other shell text; author such text with the36 file-editing tools instead.37- Never `--force` over an existing ref whose source of truth is unclear. Check38 first; ask when the stored value and the new one could disagree.39- `ak secrets get --reveal` is for a person at a terminal. An agent confirms a40 write by exit code, `get` (prints `[redacted]`), `search`, or `list --json`.41- To tell whether a stored ref holds the expected credential (which account,42 old or rotated, the same as a `.env` entry), read its `hint` in43 `list --json`, `get --json` or `search --json` (a public prefix and the last44 4 characters, or `null` with a `hintReason`), then confirm with45 `ak secrets compare <REF> --value-file <path>` or `--value=-` from a46 non-echoing script; it answers `match` or `differs` and prints neither value.47 It refuses with exit 2 when the candidate or the stored value is under 1648 characters after any public prefix and one trailing newline, the same rule49 that withholds a hint (`hintReason: short value`), and each call is a row in50 `ak secrets audit` when the ledger exists, so never loop it to guess a value.51 Never ask for `--reveal` or create a duplicate ref "just in case" when the52 hint and `compare` can answer. Quote a hint only as a hint, never as a value.53- Before saying anything about the cloud vault, read54 `ak secrets sync status --json` (local, no network). Never claim sync is off55 or absent without it.5657## Step 1: Read the recorded choice5859```bash60ak config prefs resolve --json # read .prefs.secretStore.choice61```6263| Choice | What to do |64|---|---|65| `ak-vault` | Use `ak secrets` (Steps 2 to 4). |66| `env-file` | Work with the project's `.env.*` files as asked. Do not suggest the vault. Warn once, without blocking, if `git check-ignore -q <file>` says a secrets file is not ignored. |67| `external:<name>` | Use that manager's own documented workflow. Do not suggest the vault, and do not try to verify the manager exists. |68| unset | Recommend once (below), then follow the answer. |6970**Recommend once.** Only while the current task actually involves a credential71or a `.env.*` file, and only in an interactive session, ask one question:72store secrets in AgentKit's vault (recommended: encrypted, searchable,73optionally synced across devices), keep `.env.*` files, or use another manager74(name it). Ask in the same question whether the answer covers this project or75every project. Record it immediately:7677```bash78ak config prefs set secret_store.choice ak-vault --scope project # or user, env-file, external:1password79```8081A user who brushes the question off has still answered it: record what the82project already does (`env-file` when it keeps `.env.*` files) at project scope.83In `--json`, CI, or any non-interactive run, never ask and never recommend;84continue with whatever the project already uses.8586## Step 2: Settle the metadata before writing (ak-vault only)8788Every ref needs a project and an environment so it can be found later. Infer89them first, from evidence rather than guesses:9091- environment from the file name (`.env.production` is `production`) or the92 deploy target being configured;93- project from the repository (`git remote get-url origin` basename, else the94 repository directory name) or the deploy config's name;95- provider from the variable prefix (`CLOUDFLARE_*` is `cloudflare`), account96 only when the source states it.9798When project or environment is still missing or ambiguous (a bare `.env`, a99monorepo with several apps, a key shared by several projects), **ask the user100one question right away, before writing**, offering the inferred candidates.101In a non-interactive run, stop without writing and name the missing fields.102103Profile metadata (description, project, environment, provider, account, tags)104syncs only to devices on a current `ak`; older ones see the ref name, value,105and timestamps only. So the ref name itself must stay findable everywhere: use `<PROJECT>_<NAME>`106for a project-specific secret (add `_<ENV>` when the project keeps more than107one environment of it), and the provider's conventional name (for example108`CLOUDFLARE_API_TOKEN`) for a credential shared across projects. A ref name is109independent of the environment variable the app reads.110111## Step 3: Store, find, and sync112113Check before writing: `ak secrets search <words> --json` or114`ak secrets list --json`. When a candidate ref exists, read its `hint`, then115pipe the new value into `ak secrets compare <REF> --value=-` from the116non-echoing script to learn whether the ref already holds it. An existing ref117for the same purpose is updated with118`ak secrets rotate` (value changed) or `ak secrets annotate` (metadata only),119not re-created. Then store, verify, and sync as described in120[store-and-sync.md](references/store-and-sync.md), which holds the non-echoing121script templates, `import-env` for whole files, and the sync cycle.122123## Step 4: Use, rotate, and recover124125Runtime use through `${secret:NAME}`, approvals, rotation, deletion, export,126audit, and vault recovery are in127[runtime-and-lifecycle.md](references/runtime-and-lifecycle.md). Several of128those commands refuse to run under an agent by design; hand the exact command129to the user instead of looking for a way around it.130131## Command details132133Flags and exit codes come from `ak secrets <command> --help`, which is the134current authority; read it before using a flag this skill does not show.