onepassword-agent

name	onepassword-agent
description	Safely interact with 1Password from agent workflows using a service account token and the 1Password SDK. Use when Codex needs to load OP_SERVICE_ACCOUNT_TOKEN, resolve 1Password secret references, inject credentials into commands, upload secrets to CI/CD tools, use SSH keys without printing them, or read/write items in an agent-scoped vault without exposing secret values.

1Password Agent

Use this skill to move secrets between 1Password and tools without showing raw values to the model or terminal output. Default token source: op://your-vault/your-item/credential (set OP_SERVICE_ACCOUNT_TOKEN_REF to override).

Bootstrap Once

At the start of a new agent/session that will use 1Password, run this once:

source "$HOME/.agents/skills/onepassword-agent/scripts/load-token.zsh"

This is the only normal use of source. It loads OP_SERVICE_ACCOUNT_TOKEN into the current shell and writes a 0600 local cache so later fresh tool shells can reuse the token without another op read or Touch ID prompt.

After bootstrapping, do not source load-token.zsh again for routine work. Use the Node helper for every 1Password interaction:

node "$HOME/.agents/skills/onepassword-agent/scripts/op-agent.mjs" vaults

If the helper says both the environment token and local cache are missing, ask before bootstrapping again because that can trigger Touch ID or a 1Password approval prompt. Use --token-ref or OP_SERVICE_ACCOUNT_TOKEN_REF only when the token moves from the default reference. Never ask the user to paste the token into chat.

Rules

• Use full op://vault/item/field secret references for secret values.
• Prefer IDs for item management: vault ID, item ID, section ID, and field ID.
• Do not print tokens, passwords, private keys, API keys, TOTP seeds, or resolved secret values.
• Do not call op read for the service account token after OP_SERVICE_ACCOUNT_TOKEN is already set.
• Do not source load-token.zsh before each operation. Source it once to bootstrap, then use node .../op-agent.mjs for all further operations.
• Prefer the helper's env/cache reuse over repeated source load-token.zsh calls.
• Prefer run, pipe, or secret-file so secrets go directly to the target tool.
• Use pipe for CI secret upload commands that read from stdin.
• Use secret-file for commands that require a private key or certificate path; it writes a 0600 temp file and deletes it after the command exits.
• Confirm destructive operations like archive/delete unless the user explicitly requested the exact action.
• Read references/onepassword-sdk-notes.md when you need SDK field/category constraints.

Helper

Run the helper with Node:

node "$HOME/.agents/skills/onepassword-agent/scripts/op-agent.mjs" --help

Core commands:

• vaults: list accessible vaults.
• items --vault-id <id>: list active items in a vault.
• item --vault-id <id> --item-id <id>: show redacted item metadata.
• validate --ref 'op://...': validate secret reference syntax.
• run --env NAME=op://... -- <command>: inject resolved refs as environment variables.
• pipe --ref op://... -- <command>: send one resolved secret to command stdin.
• secret-file --ref op://... --env NAME -- <command>: pass a temp file path in NAME.
• set-field --vault-id <id> --item-id <id> --field-id <id> --value-ref op://...: update an existing field from a safe source.
• create-login --vault-id <id> --title <title> --username-ref op://... --password-ref op://...: create a login item without literal secrets.
• archive --vault-id <id> --item-id <id>: archive an item.

Common Patterns

Upload a private key to GitHub Actions without printing it:

node "$HOME/.agents/skills/onepassword-agent/scripts/op-agent.mjs" pipe \
  --ref 'op://Jarvis Vault/Deploy SSH/private key?ssh-format=openssh' \
  -- gh secret set DEPLOY_KEY --repo owner/repo --body-file -

Use an SSH key through a temp file:

node "$HOME/.agents/skills/onepassword-agent/scripts/op-agent.mjs" secret-file \
  --ref 'op://Jarvis Vault/Deploy SSH/private key?ssh-format=openssh' \
  --env SSH_KEY_PATH \
  -- sh -c 'ssh -i "$SSH_KEY_PATH" user@host'

Run a command with injected API credentials:

node "$HOME/.agents/skills/onepassword-agent/scripts/op-agent.mjs" run \
  --env API_TOKEN='op://Jarvis Vault/Example API/token' \
  -- sh -c 'curl -H "Authorization: Bearer $API_TOKEN" https://example.invalid'

Use sh -c when the child command needs shell expansion of injected environment variables.

Resources

• scripts/load-token.zsh: source once to export OP_SERVICE_ACCOUNT_TOKEN and seed the local token cache.
• scripts/op-agent.mjs: run with node for every subsequent redacted read, env injection, stdin piping, temp-file use, and item write.
• references/onepassword-sdk-notes.md: compact SDK notes and constraints.