How do I install the Using Sops skill?

Run npx skillmds@latest add jssblck/using-sops in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Using Sops skill do?

Use when a task needs secrets or key setup in a repo with .sops.yaml and secrets/ .env, or a pnpm secrets script. It is listed under Productivity on SkillMD.

Is Using Sops safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Using Sops?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Using Sops free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Using Sops?

jssblck (@jssblck) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Using Sops by jssblck — Agent Skill

Name: Using Sops
Rating: 4.2 (5 reviews)
Author: jssblck

File contents

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	every file
`prod`	per project	that project's production platform only	`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.

Agent workflow

Dev secrets are yours to manage without asking:

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.

Prod secrets need elevation. When a task requires reading or writing prod.env:

Check for .age/elevated in this checkout. If present, prod commands work; carry on.
If absent, ask the user to run, in a terminal of their own: op read 'op://Personal/age-personal/private key' | pnpm secrets elevate (or however their password manager prints the key). Say why you need it.
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.

---name: using-sopsdescription: Use when a task needs secrets or key setup in a repo with .sops.yaml and secrets/<env>.env, 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 | every file | | `prod` | per project | that project's production platform only | `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. ## 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. Prod secrets need elevation. When a task requires reading or writing `prod.env`: 1. Check for `.age/elevated` in this checkout. If present, prod commands work; carry on. 2. If absent, ask the user to run, in a terminal of their own: `op read 'op://Personal/age-personal/private key' | pnpm secrets elevate` (or however their password manager prints the key). Say why you need it. 3. 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`.

Frequently asked questions

Using Sops