macos-keychain-secrets - SKILL.md Agent Skill

name: macos-keychain-secrets description: > Use when setting up or debugging local macOS Keychain secrets for app integrations, CLI tokens, or provider credentials.

macOS Keychain Secrets

Use this skill when setting up or debugging local macOS Keychain secrets for app integrations, CLI tokens, or provider credentials.

Diagnose

Check the keychain search list, default keychain, and login keychain file:

security list-keychains
security default-keychain
test -f "$HOME/Library/Keychains/login.keychain-db"

The default keychain should be the file ~/Library/Keychains/login.keychain-db, not the directory ~/Library/Keychains.

Prefer Existing App Wrappers

Before direct security commands, search for app-specific Keychain wrappers and service/account naming:

rg -n "Keychain|add-generic-password|find-generic-password|keychain" .

Use the wrapper if available.

Direct Security Commands

For lookup commands, always pass the explicit keychain path as the final argument:

security find-generic-password -s "$service" -a "$account" "$HOME/Library/Keychains/login.keychain-db" >/dev/null

For direct writes, use the prompt form only after verifying the default keychain is ~/Library/Keychains/login.keychain-db. security treats -p and -w password as insecure because they expose the secret as an argument; bare -w as the last option prompts for the secret and writes to the default keychain:

security add-generic-password -U -s "$service" -a "$account" -w

Do not combine a keychain path with prompt-form direct writes because security add-generic-password expects options before the optional keychain argument. If the default keychain is wrong and the user does not approve repairing it, stop or use an app-specific wrapper.

Do not put literal secret values in commands, transcripts, or shell history. Disable xtrace before handling secrets and unset secret variables after use. If non-interactive writes are required, prefer an app-specific wrapper or private local tooling that avoids exposing the secret in process arguments.

Do not use find-generic-password -w for agent verification because it prints the secret. Verify item presence only.

Default Keychain Repair

If security default-keychain points at a directory or bad path, ask before mutating. With approval:

security default-keychain -s "$HOME/Library/Keychains/login.keychain-db"

Secret Handling

Never print secrets. Prefer existing authenticated tools, private files, app-specific wrappers, or prompt-form writes. Avoid shell history exposure. Verification should prove presence, not value.

Failure Handling

If macOS shows "Keychain Not Found", inspect security default-keychain. If prompts repeat or the user cancels, stop. Distinguish missing item from Keychain failure.