Skip to content
Skills Library
DevOps & cloud · Automation

using-sops

/using-sops

Use for secrets or key setup in a repo with .sops.yaml, encrypted environment files, or a pnpm secrets script.

Repository
agents ↗
Licence
GPL-3.0
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Use for secrets or key setup in a repo with .sops.yaml, encrypted environment files, or a pnpm secrets script.

Original author description

Use for secrets or key setup in a repo with .sops.yaml, encrypted environment files, or a pnpm secrets script.

How it works

  1. Identities
  2. Agent workflow
  3. Human setup
Original SKILL.md headings · 86 lines, 716 words
SKILL.md preview
---
name: using-sops
description: "Use for secrets or key setup in a repo with .sops.yaml, encrypted environment files, or a pnpm secrets script."
---

# Using sops

Repositories that use this layout commit their secrets to git as sops-encrypted
dotenv files, one per deployment environment: `secrets/dev.env`, `secrets/prod.env`. The
files decrypt with age identities. There is no `.env`, no secrets service, and no session
to log in to. Every checkout, worktree, and cloud sandbox has the encrypted files at
clone; the only input anywhere is an age private key.

`pnpm secrets` (`tools/secrets.ts`) is the only interface. Do not call `sops` directly in a
repo that has the wrapper.

## Identities

| Identity   | Scope       | Where the private key lives                                       | Decrypts    |
| ---------- | ----------- | ---------------------------------------------------------------- | ----------- |
| `agent`    | user-wide   | `~/.config/sops/age/keys.txt` on every machine agents run on; `SOPS_AGE_KEY` in cloud sandboxes | `dev.env` |
| `personal` | user-wide   | the user's password manager                                      | files listing its public key |
| `prod`     | per project | that project's production platform and documented password-manager item | `prod.env` |

`.sops.yaml` lists recipients by public key. Encrypting needs no private key; decrypting
or editing needs one recipient's private key. `agent` and `personal` are local-development
keys shared by every project; `prod` is minted per project so one leaked deploy variable
exposes one project. These are conventions, not guaranteed recipients. Existing repos
may use only shared `dev` and `prod` keys. Read the repository's secrets guide and
`.sops.yaml` before choosing a key; the encrypted file's recipient metadata determines
which identities can decrypt it.

## Agent workflow

Dev secrets are yours to manage without asking:

```sh
pnpm secrets show dev                    # everything, decrypted
pnpm secrets get dev STRIPE_KEY
pnpm secrets set dev STRIPE_KEY sk_test_1
pnpm secrets unset dev STRIPE_KEY
pnpm secrets exec dev -- node apps/worker/src/main.ts
```

`exec` puts the decrypted values in the child's environment (over the shell's), removes
`SOPS_AGE_KEY*` from it, forwards signals, and exits with the child's status.

When an authorized task needs production secrets, perform elevation yourself. Do not
ask the user to run the command or reconfirm an already authorized task.

1. Check access with `pnpm secrets exec prod -- true`, which prints no secret values.
   An existing `.age/elevated` file alone does not prove that its key can decrypt prod.
2. If access fails, read the repo's secrets guide and recipient configuration. Use the
   documented account, vault, item, and field for a matching key. Do not assume a
   `Personal` vault, an `age-personal` recipient, or the CLI's default account.
3. Run the documented read yourself, piping the key directly into the wrapper:
   `op read 'op://VAULT/ITEM/FIELD' --account ACCOUNT | pnpm secrets elevate`.
   Replace the placeholders with the discovered identifiers; never print the key.
4. Confirm decryption with `pnpm secrets exec prod -- true`, then continue the task.

When the documented 1Password location is missing, use `op account list --format json`
and `op vault list --account ACCOUNT --format json` to identify the correct account and
vault. Search item metadata in that vault for the documented key name with
`op item list --account ACCOUNT --vault VAULT --format json`; inspect only matching
items. Pass `--account` on subsequent reads. `Private`, `Personal`, and `Shared` are
distinct names, not interchangeable aliases. If a key is found but cannot decrypt,
compare its public key with the file's recipients instead of repeatedly trying vault
names. Keep private keys out of tool output.

Ask the user only when progress requires their interaction, such as unlocking
1Password or granting unavailable access. State the actual blocker. Elevation is per
checkout and lasts until `.age/elevated` is deleted; do not copy it into another worktree.

When you add a variable, add it to the env schema and to every `secrets/<env>.env` you can
decrypt. If you cannot decrypt prod, say so in the PR: the typed env check fails the prod
boot until the value is set, which is the intended signal.

Never write an `AGE-SECRET-KEY-...` into a tracked file, a log, or a commit. Never put `personal` or `prod` in a cloud
environment.

## Human setup

For the one-time steps (generating keys, installing `sops` and `age`, wiring the `agent`
key into agent tools and cloud sandboxes, configuring the prod platform, and rotating
keys), read `references/setup.md`. When the user asks
to be reminded of the steps, walk them through that file in order.

For the sops and age behavior the design relies on (identity union, `updatekeys`,
`exec-env` limitations, dotenv quirks), read `references/sops-notes.md`.
Files in this package (4)
  • SKILL.md 5 KB
  • agents/openai.yaml 1 KB
  • references/setup.md 6 KB
  • references/sops-notes.md 3 KB

Versions

The database has no other skills named using-sops.

Database snapshot: 13.11.2026 · package version c81137bb8469 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sops-setup
    Set up SOPS + age encryption for sharing .env files securely across machines. Detects existing state, installs tools, generates age keys, creates .sops.yaml, and encrypts .env files as YAML (avoids SOPS dotenv bug #1435). Use when user mentions "sops setup", "encrypt env",…
  • 100sops-encrypt
    Encrypt .env files using SOPS + age. Converts dotenv to YAML format (avoids SOPS bug #1435), then encrypts. Auto-detects unencrypted .env files. Use when user mentions "encrypt env", "sops encrypt", "encrypt secrets", "encrypt .env", "encrypt environment", "re-encrypt", "update encrypted".
  • 100secrets-management
    Use when working with Vault, SOPS, secret scanning, or managing credentials safely
  • 100secrets-management
    Guides eliminating hardcoded secrets from code and CI/CD, setting up a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, SOPS+age/KMS for GitOps), rotating credentials, and adding secret-scanning to catch leaks. Use when the user asks to "remove hardcoded…
  • 100sops-encryption
    Encrypt files and configs with Mozilla SOPS. Integrate with AWS KMS, GCP KMS, or PGP for key management. Use when encrypting configuration files, Kubernetes secrets, or implementing GitOps with encrypted secrets.
  • 100manage-secrets
    Use when a repo handles credentials — decide where each secret lives per host (Vercel, GitHub environments, sops+age for Compose, Supabase), keep them out of images, logs, bundles and state, set up .env.example, rotation and secret scanning.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.