Mac Keychain

Mac Keychain

Use this skill to operate on macOS Keychain generic password items.

Scope

• Support exists, read-meta, set, update, read-secret, reveal-secret, and delete.
• Operate on generic password items only.
• Stop if the request involves certificates, identities, private keys, or broad keychain administration.

Runtime

• Require macOS, /usr/bin/security, and /bin/zsh.
• Use the bundled scripts for deterministic behavior.
• Stop and explain the missing runtime dependency if the scripts cannot run as shipped.

Operating Rules

• Resolve the target with service + account before any write, delete, or secret read.
• Default to the current user's login keychain.
• Pass --keychain only when the target is not the default login keychain.
• Keep caller attribution, approval prompts, and workflow policy in the caller. Do not model them inside this skill.
• Keep the script interface narrow. Do not pass legacy caller-attribution or purpose flags.
• Keep this skill thin. It should expose local Keychain operations, not orchestrate a larger secret-management workflow.

Safety Model

• Do not guess missing service or account for set, update, read-secret, reveal-secret, or delete.
• Do not echo the incoming secret in set or update.
• Use read-secret for downstream machine use after the caller has already decided that retrieval is allowed.
• Use reveal-secret only when the user explicitly wants plaintext in visible output. Require --confirmed.
• Use delete only with a clear target. Require --confirmed.

Scripts

All scripts accept --service and --account. Use --keychain only for a non-default keychain.

• scripts/keychain-exists.sh: return whether an item exists.
• scripts/keychain-read-meta.sh: return safe metadata only.
• scripts/keychain-set.sh: create a new item and fail if it already exists.
• scripts/keychain-update.sh: update an existing item and fail if it does not exist.
• scripts/keychain-read-secret.sh: return a plaintext secret for downstream use. Use --value-only to emit only the secret.
• scripts/keychain-reveal-secret.sh: return a plaintext secret for visible output. Require --confirmed.
• scripts/keychain-delete.sh: delete an item. Require --confirmed.

Output

• Expect structured JSON on stdout for success and on stderr for failures, except scripts/keychain-read-secret.sh --value-only.
• Treat read-secret output as sensitive even when the caller does not print it.
• Keep normal user-facing status non-disclosing unless the requested action is reveal-secret.