agentleFS
fortunto2fortunto2/solo-factory/skills/secrets/SKILL.md

solo-secrets

Skill18 starsChanged 4 months agoMITView on GitHub

Keep API keys, tokens and passwords out of repos, configs, argv and chat logs — store them in the OS keystore (macOS Keychain, Linux libsecret), track rotation, scan for plaintext and migrate it. Use when user says "куда положить токен", "где хранить ключ", "секрет", "пароль в конфиге", "api key", "store this token", ".env", "rotate the key", "ротация", "токен утёк", "scan for secrets", or a credential shows up in a file, a prompt or a tool output. Do NOT use for auth flows inside an app (use /deploy or the stack template) or for redacting transcripts (the secret_guard hook does that).

  • Reads credentials

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never echo it back: Do not repeat, quote or "confirm" the value in a reply, a commit, a file or a command line.

    line 26
  2. Very specific:

    Rotate: when it is leaked or due: secret rotate <name> shows where to issue a new value, stores it, and resets the clock.

    line 37
  3. Very specific:

    Don't paste the value into the chat to "check it".

    line 132
  4. Distinctive:

    Don't commit the registry to a public repo: names, scopes and file paths are a map for an attacker even without values.

    line 133
  5. Distinctive:

    Don't rewrite git history to "fix" a leak before rotating.

    line 135

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/secrets — credentials in the keystore, never in plain text

One CLI, scripts/secret (stdlib Python 3.10+, no install), and one registry of metadata only. Values live in the OS keystore; everything a human or an agent sees is masked to the first 4 characters and the length: cfut…(45).

S=${CLAUDE_PLUGIN_ROOT:-.}/skills/secrets/scripts/secret   # or copy the path; alias it

When a secret appears — do this, in order

  1. Never echo it back. Do not repeat, quote or "confirm" the value in a reply, a commit, a file or a command line. Refer to it by name.
  2. Was it seen anywhere that keeps logs? A chat, an agent transcript, a screenshot, CI output, a ticket, a commit (even one later amended): it is leaked. Run secret leak <name> --where "<where>" and tell the user to rotate it now. Claude Code writes prompts to ~/.claude/projects/*/*.jsonl; a blocked prompt is still echoed there.
  3. Store it from stdin, never argv: pbpaste | secret set example-api-token --class api-scoped --used-in "<tool>" (or run secret set <name> for a hidden prompt). Shell history and ps both see argv.
  4. Point the code at the keystore (secret migrate prints the snippet), then blank the plaintext. Keep the old value until the new one works; never delete the only copy.
  5. Rotate when it is leaked or due: secret rotate <name> shows where to issue a new value, stores it, and resets the clock. Revoke the old value at the provider.

Commands

CommandDoes
secret set <name> [--class C --scope S --used-in P --rotate-url U --note T]value from stdin or a hidden prompt → keystore; metadata → registry
secret add <name> [same flags]metadata only: an item already in the keystore, or one tracked for rotation
secret get <name>value to stdout, for piping: TOKEN="$(secret get x)"
secret exec A=ENV [B=ENV2] -- cmdruns one command with the values in its environment, nothing exported
secret listmetadata + whether the keystore holds the item
secret dueoverdue / due in 30 days; exit 1 when overdue
secret rotate <name> [--revoked]guided rotation; --revoked = old value killed, no replacement
secret leak <name> --where Wclass → leaked, due today
secret scan [paths] [--json] [--min high] [--gh]plaintext secrets, masked; --gh asks GitHub if a remote is PUBLIC
secret migrate <file> <key> <name> [--remove]a.b.c in YAML or KEY in env/toml/ini → keystore, read back, then (optionally) blanked
secret check [paths]one counted line for a recurring health check; exit 1 on critical/high/overdue

Registry: $SECRETS_REGISTRY, default ~/.config/secrets/registry.json. It holds no values, so it can be committed to a private repo. Its scan block takes paths (default scan roots), exclude (globs) and owners (remote substrings that are yours; a tracked hit in a clone of someone else's repo is reported low).

Policies

ClassRotate everyFor
prod-admin90 daysaccount-wide or write access to production: cloud admin, DNS, payments, DB owner
api-scoped180 daysa token limited to one API and one project (the default)
personal-low365 daysread-only or low-blast-radius personal tokens
leakednowanything seen in a chat, log, screenshot, commit or public place

Rules that do not bend:

  • Never in git, not even a private repo, not even "for a minute". History keeps it.
  • Never in argv or shell history. Pipe from stdin or use the hidden prompt.
  • Never in a plain config that a tool reads; configs hold the keystore name.
  • Least privilege, one token per tool. A token shared by three tools cannot be rotated without breaking two of them, and its leak has three blast radii.
  • Leak → rotate now, not at the next due date. Removing it from the file does not un-leak it.
  • Files that must exist as files (.p8, .pem, service-account JSON): keep them in ~/.secrets/ with chmod 600 (directory 700), outside every repo, and register them with secret add <name> --note "file: ~/.secrets/…". If a tool can take the content instead of a path, store it base64: base64 < key.p8 | secret set example-p8-key and decode at use: secret get example-p8-key | base64 -d.

Scan

secret scan walks the paths (skipping node_modules, venvs, build output, lockfiles, files over 1 MB) and reports three kinds of evidence:

  • prefixed tokens — sk-, sk-ant-, ghp_, github_pat_, glpat-, xox?-, AKIA, AIza, cfut_, hf_, npm_, whsec_, Telegram bot tokens, JWTs, private key blocks, DSN passwords. Counted anywhere, docs and tests included.
  • name = value — a secret-sounding name (*_TOKEN, api_key, clientSecret…) with a value that is not a reference (${X}, os.environ, config.x), a placeholder, a URL, a path or an identifier, and has the entropy of a key. In code files only quoted literals count; in tests, docs, examples and translations only long high-entropy ones.
  • key files by name — AuthKey_*.p8, *.pem, *.p12, service-account JSON, *token*.txt.

Severity is about where it sits, not what it is: critical = tracked in git (strong rule, or any rule in a PUBLIC repo); high = untracked but not gitignored, one git add -A from a commit; medium = gitignored or outside git, plaintext still to move; low = a Supabase anon JWT (public by design) or a third-party clone. A bare hash or UUID is never flagged on its own. A line can opt out with secret-scan: ignore.

A tracked secret is not fixed by deleting the file. It is in history and in every clone: rotate first, then decide whether to rewrite history (git filter-repo) — that is the owner's call, it breaks every clone and fork.

Other keystores

The CLI picks the backend: macOS security (Keychain, generic password, service=<name>, account=$USER), else Linux secret-tool (libsecret, needs a running Secret Service such as GNOME Keyring). For 1Password, store with op item create --category "API Credential" --title example-api-token and read with op read "op://Private/example-api-token/credential"; op run --env-file is the equivalent of secret exec. Keep the registry either way: rotation dates are the part no keystore tracks for you.

Gotchas

  • security add-generic-password -w <value> puts the value in argv. The CLI writes through security -i on stdin with a hex value instead.
  • security find-generic-password -w prints hex for values with non-printable bytes; store binary as base64.
  • The first read of a Keychain item from a new binary may raise a macOS prompt; "Always Allow" binds it to that binary path.
  • A gitignored .env is still plaintext on disk and in every backup; it is medium, not fine.

Don't

  • Don't paste the value into the chat to "check it". Use secret list (masked).
  • Don't commit the registry to a public repo: names, scopes and file paths are a map for an attacker even without values.
  • Don't rewrite git history to "fix" a leak before rotating. The old value is already out.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.